This recipe explains how to set different direction annotation attributes for the web service operation parameters. With the direction of the parameters, we define the flow of the values between web service and client. To receive more than one value from a web service, we have several possibilities. We can define a Java class that is returned by the method. We can also return values through return parameters as well as over method input parameters (value by reference). When using the last scenario, the annotation for defining parameter direction comes in handy.
In this recipe, we will amend the example from the Defining a one or two way web service recipe.
The direction of parameters is defined through the port type. We first open the CCGatePortType class. We will add annotations to the Refund method:
@WebMethod @WebResult(name = "RefundResponse") public TransactionResponse Refund(@WebParam(name = "token", mode = WebParam.Mode.IN) String token, @WebParam(name = "amount", mode = WebParam.Mode.INOUT) Holder<BigDecimal> amount) throws RemoteException;
We changed the Refund method code as well so that it deduces the fee from the amount to be refunded, which is omitted due to no relevance to the current recipe.
In this recipe, we used the @WebParam annotation. For the direction of the parameters, we set the mode attribute. The meaning of the mode attribute is as follows:
WebParam.Mode.IN:The direction of the parameters is strictly input, meaning we expect no value changes to the input variable.WebParam.Mode.OUT:The direction of the parameters is strictly transferring results to the output. This means there is no real expected input value, however an output value is expected.WebParam.Mode.INOUT:The direction of parameters is input and output. We set the value to the parameter at the input and we also expect a value at its output.
When applying the WebParam.Mode.OUT or WebParam.Mode.INOUT mode, we need to use the Handler class instead of regular method variable declarations. The Handler class takes care of transferring values from and to the operation parameter.
By comparing the WSDL document of the deployed web service before and after the code change, it shows the difference in the RefundResponse complex type definition:
<xs:complexType name="RefundResponse">
<xs:sequence>
<xs:element name="amount" type="xs:decimal" minOccurs="0"/>
<xs:element name="RefundResponse" type="tns:transactionResponse" minOccurs="0"/>
</xs:sequence>
</xs:complexType>We can see that a new element amount is present in the response message definition. The cause lies in the fact that the amount parameter is defined as an input and output parameter in Java code.