17 Using the Web Services Framework

17.1.1 About SOAPMessageBuilder

This API offers different methods to construct a SOAP message. In addition, it allows the caller to set the actor, role, mustUnderstand, and relay attributes of the SOAP header element. Finally, the SOAP body of the message can be constructed with this API.

• createSOAPMessage() - create a empty SOAP message.

• setHeaderElementActor() - set the recipient of a SOAP header (SOAP1.1).

• setHeaderElementRole() - set the recipient of a SOAP header (SOAP 1.2).

• setHeaderElementMustUnderstand() - indicates whether a header entry is mandatory or optional for the recipient to understand.

• setHeaderElementRelay() - indicates whether the header is to be relayed to the next SOAP node if the current node doesn't understand the header.

• addToSOAPHeader() - add name/value pairs of elements and attributes to the SOAP header.

• addSOAPHeader() - add a DOM representation of a SOAP header.

• addSOAPBody() - add a DOM representation of a SOAP body.

• addSOAPPayload() - add entire SOAP message in XML format.

• getSOAPMessage() - returns constructed SOAP message.

17.1.2 About WebServiceInvoker

When a client program invokes a Web service method, there are various areas that need to be addressed, including:

• Security

• Setting up optional client-side SOAP message handlers

• Setting the attributes of the request

• Different modes of making the call

There are numerous predefined Web service security policies that are available through Oracle Web Service Manager with WebLogic Server in the areas of message-level and transport-level security.

As Enterprise Manager Web services support the oracle/wss_username_token_service_policy, the WebServiceInvoker API offers setUpUNTAuth(String username, String password) to set up the corresponding client-side security. The API also has setUpHttpBasicAuth(String username,String password) for calls out to other web services that support that security scenario.

If desired, a client program can have client-side SOAP message handlers that modify parts of the SOAP message before it is actually sent to the server. To that end, custom SOAP message handlers that implement the javax.xml.ws.handler.soap.SOAPHandler interface can be written. To associate one with your client progam, the addClientSideSOAPMsgHandler(String handlerClass) API can be called.

There are some basic attributes of a Web service method invocation that can be specified by the client. They include:

• connection timeout (com.sun.xml.ws.developer.JAXWSProperties.CONNECT_TIMEOUT)

• request timeout (com.sun.xml.ws.developer.JAXWSProperties.REQUEST_TIMEOUT)

• SOAP action (javax.xml.ws.BindingProvider.SOAPACTION_URI_PROPERTY)

These attributes can be set with these corresponding API calls:

• setConnectTimeout(int connectTimeout)

• setRequestTimeout(int requestTimeout)

• setSOAPAction(String soapAction)

WebServiceInvoker exposes four different ways to invoke a Web service:

• invokeSyncWS(SOAPMessage request)

  calls the method and waits for a response.

• invokeAsyncWS(SOAPMessage request. WebServiceAsyncProcessor asyncProcessor)

  calls the method and loops through the process() method of an implementation of oracle.sysman.emSDK.webservices.outbound.WebServiceAsyncProcessor.

• invokeAsyncWithHandlerWS(SOAPMessage request, WebServiceAsyncProcessor asyncProcessor, AsyncHandler asyncHandler)

  Same as invokeAsyncWS(), except the results of the method invocation are processed by the handleRepsonse() method of an implementation of javax.xml.ws.AsyncHandler.

• invokeOneWayWS(SOAPMessage request)

  Calls the method, immediately returns and doesn't expect a response back.

17.1.3 Using the InvokeAPITester Sample Program

The following is a sample test program that uses the WebServiceInvoker API to make Web service calls:

oracle.sysman.emSDKsamples.websvcs.outbound.InvokeAPITester

It is written to be flexible in that an input file of parameters is read and depending on the values of some of the parameters, the security mode and the invocation mode can be specified. The list of parameters that can be specified include:

• protocol

• host

• port

• path

• name

  Name is the name in the wsdl:definitions tag in the WSDL.

• username

  Used for security.

• password

  Used for security.

• calling mode

  Calling mode can be sync, async, asynccb or oneway.

• security mode

  Security mode is UNT.

• target namespace

  Target namespace is value of targetNamspace in wsdl:definitions tag in the WSDL for the Web service.

• port name

  Port name is the name attribute of port in the WSDL.

• payload XML

  Payload XML points to an XML file that contains the SOAP message for the request.

• default payload XML path

  Default payload XML path is the directory in which the payload file is located.

• client-side SOAP message handler class

  Handler class can specify a client-side SOAP message handler to manipulate the SOAP message before it is sent.