# Building a JMS Client

You may configure a WebLogic Workshop web service or web service method to accept requests via JMS (Java Message Service) using the jms-soap, jms-soap12 or jms-xml attributes of the @SOAPBinding annotation. To build a client that sends messages to a WebLogic Workshop web service over a JMS queue, you need to configure the client to:

1. Instantiate a javax.naming.InitialContext object with the properties shown in the following table:

   Property | String Setting
   --- | ---
   SECURITY_PRINCIPAL | User or principal name; default is "system"
   SECURITY_CREDENTIALS | Principal password; default is "password"
   INITIAL_CONTEXT_FACTORY | The context factory for the JMS service
   PROVIDER_URL | Host URL, using the t3 protocol (e.g., "t3://localhost:7001")

2. Connect to the queue named jws.queue. (This queue is already configured on WebLogic Server, you do not need to create it.)

3. Depending on the web service's @SOAPBinding settings, format request messages as XML or SOAP in a javax.jms.TextMessage object. If the web service is conversational, see Conversing with Non-Workshop Clients to learn how to include conversation headers in the request messages.

   Each message must also have a String property named URI that identifies the target web service. For example, if the URL to the web service is http://localhost:7001/WebServices/jms/JMSService.jws, specify the URI property as /WebServices/jms/JMSService.jws.

4. Send the message.

Note: the target Web Service must not be a conversational web service.

## SOAP Encodings

The SOAP specification allows two types of SOAP messages, called "document/literal" and "SOAP RPC". The soap-style attribute of the @SOAPBinding annotation determines which SOAP format a web service or web service method accepts.

In both SOAP formats, the top-level element of the SOAP body must be exactly the namespace-qualified name of the target web service method. Method parameters are specified by child elements.

The following example shows invocation of the Hello method (of some web service) using the SOAP document/literal syntax. Note that the <name> parameter has no data type specification.

    <SOAP-ENV:Envelope
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <SOAP-ENV:Body>
        <Hello xmlns="http://www.openuri.org/">
          <name>John</name>
        </Hello>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

Contrast with the following example, which invokes the same method using the SOAP RPC syntax. Note that the <name> parameter's data type is specified by the attribute xsi:type="xsd:string".

    SOAP-ENV:Envelope
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <Hello xmlns="http://www.openuri.org/">
          <name xsi:type="xsd:string">John</name>
        </Hello>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

##
SOAP 1.2 Encodings

SOAP 1.2 is an update of SOAP 1.1 that was released as a standard by the World Wide Web Consortium in 2003. It is designed for the exchange of information between decentralized, distributed computers. SOAP 1.2 allows XML-based information to be exchanged between programs, machines, or organizations.

The SOAP distributed processing model can support many Message Exchange Patterns (MEP) including but not limited to one-way messages, request/response interactions, and peer-to-peer conversations. The SOAP processing model itself does not maintain any state or perform any correlation or coordination between messages

The SOAP 1.2 header is similar to the SOAP 1.1 header. It contains an envelope, encoding, namespace, and content. Each SOAP header block contains the following information:

- A [namespace name] property which has a value, that is the name of the element MUST be namespace qualified. (required)
- Any number of character information item children. (optional)
- Any number of element information item children. (optional)
- Zero or more attribute information items in its [attributes] property. (optional) Among these may be any or all of the following items:
  - encodingStyle attribute information
  - role attribute information
  - mustUnderstand attribute information
  - relay attribute information

The following example shows Node A sending a message to Node C.

    <?xml version="1.0"?>
    <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"
    	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    	xmlns:xsi="http://www.w3.org/2001/SMLSchema-instance">
      <env:Body>
    	<test:echoFloat xmlns:test="http://example.org/ts-tests"
    		xmlns:rpc="http://www.w3.org/2002/06/soap-rpc"
    		env:encodingStyle="http://www.w3.org/2002/06/soap-encoding">
    	<rpc:result>return</rpc:result>
    	<inputFloat xsi:type="xsd:float">0.005</inputFloat>
    	</test:echoFloat>
      </env:Body>
    </env:Envelope>

Now Node C responds:

    <?xml version="1.0"?>
    <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope/"
    	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    	xmlns:xsi="http://www.w3.org/2001/SMLSchema-instance">
      <env:Body>
    	<test:echoFloatResponse xmlns:test="http://example.org/ts-tests"
    		xmlns:rpc="http://www.w3.org/2002/06/soap-rpc"
    		env:encodingStyle="http://www.w3.org/2002/06/soap-encoding">
    	<rpc:result>return</rpc:result>
    	<return xsi:type="xsd:float">0.005</return>
    	</test:echoFloatResponse>
      </env:Body>
    </env:Envelope>

So, how can you distinguish between SOAP 1.1 and 1.2 at a glance? Compare the SOAP 1.1 example at the top of this section with the SOAP 1.2 example above. The first obvious difference is that the 1.2 examples include a version number. It's tempting to think that this is actually a difference between the two, but that is only partly right. The tag gives the version of XML used, not the version of SOAP. That would be too easy. Most of the time SOAP 1.1 will not have this tag, but it can. Conversely, while SOAP 1.2 will usually include this tag, it isn't required.

The most distinct difference between the two is in the envelope. According to the SOAP 1.2 Recommendation states that SOAP 1.2 must have an Envelope element associated with the namespace http://www.w3.org/2002/06/soap-envelope, while SOAP 1.1 must have an Envelope element associated with the http://schemas.xmlsoap.org/soap/envelope namespace. If the message doesn't indicate what versions it supports, it means that the only supported envelope is SOAP 1.1.

What if you can't see the envelope? That makes things much harder. There are other differences between SOAP 1.2 and 1.1, but they are harder to spot. One way to tell the difference is to send the version that is most likely to match the service you are using. If it's not the right one, a VersionMismatch fault will be generated. It is suggested that a SOAP 1.2 node include the list of envelope versions that it supports as part of the VersionMismatch fault by using the SOAP upgrade extension identified by the http://www.w3.org/2001/06/soap-upgrade identifier. This not being a very palatable way of telling the difference, there is one more thing you can try. Look at the namespaces.

The namespaces are different between the two versions. You may also see the namespace http://www.w3.org/2001/12/soap-rpc. Also, some of the schemas have been changed for SOAP 1.2 so that they are compliant with the XML Schema Recomendation. In a WSDL created by Workshop, look for these specific schemata:

- SOAP 1.2 - xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
- SOAP 1.1 - xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

Here are some other key words for distinguishing between the two versions:

- SOAP 1.1: href, text/xml, SOAPAction, actor, faultcode, faultstring
- SOAP 1.2: ref, application/soap+xml, rpc:result, Node, Role, Misunderstood, DataEncodingUnknown, Code, Reason

For a more comprehensive list of changes see the SOAP 1.2 Primer at http://www.w3.org/2000/xp/Group/2/01/29/edcopy-soap12-part0-20020129.html#L4697.

The preceding examples are not intended to explain the complex topic of SOAP encodings. To learn more about SOAP encodings, see the SOAP specifications at www.w3.org or consult a book on SOAP. You can also consult the target web service's WSDL file for an exact description of the messages expected by each of the web service's methods.

For more information on building a JMS client, see Developing a WebLogic JMS Application on e-docs.bea.com.

Related Topics

Conversing with Non-Workshop Clients

How Do I: Tell Developers of Non-WebLogic Workshop Clients How to Participate in Conversations?

Sample: JMS-XML Protocol

Sample SOAP 1.1 Service

Sample SOAP 1.2 Service