Handling Multiple Replies |
  
|
Handling Multiple Replies |
|
Summary
The Service Definition Wizard currently creates methods with a single reply IPM definition. This article details the steps necessary to change the Service Definition File (SDF) to handle multiple reply IPMs.
More Information
Each method definition in the SDF contains a <replies/> section that includes a <reply/> section for each reply IPM type that the server receives. The SDF can be manually updated to include multiple <reply/> sections, each handling a range of reply code values specified by the replyCode attribute.
Each reply definition specifies a reply IPM type and the reply codes associated with that type. The reply code value may be a single value, a comma separated list of values or value ranges, or an asterisk indicating any reply code.
Note that SOAP/AM Server assumes that the reply code is a signed integer value in the first two bytes of the reply IPM.
For example, say that a particular method has the following sections:
The type of reply:
<type name="ipm_credit_account_reply" size="10" >
<element name="reply_code" type="short" offset="0" size="2" />
<element name="balance" type="long" offset="2" size="8" scale="4" />
</type>
The associated parameters for the reply:
<parameters>
...
<parameter name="result" type="int" direction="out" />
<parameter name="replyMsg" type="ipm_credit_account_reply" direction="out"/>
</parameters>
And the replies section:
<replies>
<reply type="ipm_credit_account_reply" replyCode="*">
<mappings>
<mapping name="result" element="reply_code" />
<mapping name="replyMsg" element="." />
</mappings>
</reply>
</replies>
The only reply that is expected is that of the ipm_credit_account_reply type. In order to handle more than one reply add the desired reply to the list of replies. In this example an IPM is added that would indicate an error condition. As shown below:
Add the type of reply that service needs to handle:
<types>
...
<type name="ipm_credit_account_reply" size="10" >
<element name="reply_code" type="short" offset="0" size="2" />
<element name="balance" type="long" offset="2" size="8" scale="4" />
</type>
<type name="ipm_error_reply" size="2">
<element name="reply_code" type="short" offset="0" size="2"/>
</type>
</types>
Add the associated additional parameter:
<parameters>
....
<parameter name="result" type="int" direction="out" />
<parameter name="replyMsg" type="ipm_credit_account_reply" direction="out"/>
<parameter name="errorMsg" type="ipm_error_reply" direction="out" />
</parameters>
Add the additional reply:
<replies>
<reply type="ipm_credit_account_reply" replyCode="0">
<mappings>
<mapping name="result" element="reply_code"/>
<mapping name="replyMsg" element="."/>
</mappings>
</reply>
<reply type="ipm_error_reply" replyCode="*">
<mappings>
<mapping name="result" element="reply_code"/>
<mapping name="errorMsg" element="."/>
</mappings>
</reply>
</replies>
The server will iterate over the list of replies in the order that they appear in the SDF. It is generally a good programming practice to have a replyCode of "*" at the end of the list of replies, as it will be the default case triggered should no previous reply code match. In the case above, if the SOAP/AM server receives a reply code of "0", then the reply is matched to that of an ipm_credit_account_reply. If the reply code is any other code, then the ipm_error_reply is what SOAP/AM Server will look for to create the SOAP XML response to the calling client.