Creating and Sending Messages without Using a Messaging Provider

1. Creating a Connection

 

 

If you are not using a messaging provider, you need to create a SOAPConnection object for sending messages directly to a remote party. This remote party is usually represented by a URL.

The following lines of code create a new instance of a SOAPConnectionFactory object and then use it to create a SOAPConnection object.

    SOAPConnectionFactory scf = SOAPConnectionFactory.newInstance();
    SOAPConnection connection = scf.createConnection();

2. Creating a message

 

 

To create a new message, you first need to get an instance of the MessageFactory class, from which you can create SOAPMessage objects.

The following code fragment gets a MessageFactory object and uses it to create a SOAPMessage object.

    MessageFactory mf = MessageFactory.newInstance();
    SOAPMessage message = mf.createMessage();

3. Populating the Message

 

 

All messages are automatically created with a SOAP part that contains a SOAP envelope that in turn contains a SOAP body. Content can be added to the SOAP body. A message may also have an optional attachment part, which contains content.

The SOAP part of a message, including its headers and content, can contain only data formatted using XML, wheras an attachment part can contain any kind of data, including XML or non-XML data and image files. The following code fragments demonstrate adding a header and its content, adding content to the SOAP body, and then adding an attachment part with data.

• The first step in populating a message is to get its SOAPPart object, from which you can get its SOAPEnvelope object.

    SOAPPart sp = message.getSOAPPart();
    SOAPEnvelope envelope = sp.getSOAPEnvelope();

• Use the SOAPEnvelope object to retrieve both the SOAPHeader object and the envelope's SOAPBody object. These are used for setting the various contents of the SOAP part of the message.

    SOAPHeader header = envelope.getSOAPHeader();
    SOAPBody body = envelope.getSOAPBody();

• Add content to the header.

A SOAPHeader object can contain only SOAPHeaderElement objects, so a new SOAPHeaderElement object is created and added to the header. The new SOAPHeaderElement object is initialized with the specified Name object. The last line in the following code fragment adds content to the new SOAPHeaderElement object headerElement.

    SOAPHeaderElement headerElement = header.addHeaderElement(
                               envelope.createName("GetLastTradePrice", "WOMBAT",
                               "http://www.wombat.org/trader"));

    headerElement.addTextNode("SUNW");

• Add content to the SOAP body part of the message.

The immediate children of a SOAPBody object can only be SOAPBodyElement objects, so a new SOAPBodyElement object is created and initialized with a new Name object. The last line in the following code fragment adds content to the new SOAPBodyElement object bodyElement.

    SOAPBodyElement bodyElement = body.addBodyElement(
                                      envelope.createName("Text", "jaxm",
                                      "http://java.sun.com/jaxm"));

    bodyElement.addTextNode("Some-text");

• Create and add an attachment part to the message.

To create an AttachmentPart object and add content to it, you can use a DataHandler object from the JavaBeans^TM Activation Framework (JAF) API. After being created and given content, an AttachmentPart object must be added to the message with the method addAttachmentPart. A second way to add content is to supply a String with the content to the method createAttachmentPart, as is shown with the second AttachmentPart object.

    URL url = new URL("http://wombats.com/img.jpg");
    AttachmentPart ap1 = message.createAttachmentPart(new DataHandler(url));
    message.addAttachmentPart(ap1);

    AttachmentPart ap2 = message.createAttachmentPart("hello",
    "text/plain; charset=ISO-8859-1");
     message.addAttachmentPart(ap2);

• Update the message

You update a SOAPMessage object with all the changes that have been made to it by calling the method saveChanges. This method is called automatically when a message is sent or written to. However, if changes are made to a message that was received or to one that has already been sent, the method saveChanges needs to be called explicitly in order to save the changes.

    message.saveChanges();

4. Sending the message on the connection

 

 

Now that the message has been created and its various parts filled, the message is ready to be sent.

• Create a URLEndpoint object with the URL of the end point to which the message is to be sent.

    URLEndpoint endPoint = new URLEndpoint("http://myservice.com/orders/info");

• Send the message as a synchronous call to the endpoint created above using the connection you created previously. The reply message is received back on the same connection.

    SOAPMessage reply = connection.call(message, endPoint);

5. Closing the connection

 

 

You need to close the SOAPConnection object when it is no longer needed by calling the method close.

    connection.close();

Creating and Sending Messages Using a Messaging Provider

When a messaging provider is used, all messages go through it. This means that when a client sends a message, the message goes to the messaging provider and is then forwarded to the recipient. When the client is the recipient of a message, the messaging provider gets the message and forwards it to the client. For this reason, the client's connection is with the messaging provider.

Note that in order to get a JAXM application that uses a messaging provider running, you'll have to refer to the "Deployment and Configuration Guide" for details about configuring the client and the messaging provider.

1. Creating a Connection

 

 

To get started with developing applications using JAXM with a messaging provider, you need to create a ProviderConnection object that represents the client's active connection to its messaging provider. To create this connection, you first need to obtain an instance of the ProviderConnectionFactory class that creates connections to the desired messaging provider. If the messaging provider has registered an instance of its connection factory with a naming service based on Java^TM Naming and Directory Interface (JNDI) technology, you can do a lookup of the ProviderConnectionFactory object that you want. Once you have an instance of the appropriate connection factory, you can use it to create a connection to your messaging provider.

The following code sample shows how to create a ProviderConnection object. The argument provided to the lookup method is the URI associated with the desired messaging provider.

The first two lines in this example use JNDI API to create a context, which is then used to do the lookup. The lookup method returns an Object, so the result of the lookup has to be cast to a ProviderConnectionFactory object.

    Context ctx = new InitialContext();
    ProviderConnectionFactory pcf = (ProviderConnectionFactory)ctx.lookup(
                                                                providerURI);
    ProviderConnection pc = pcf.createConnection();

It is also possible to get a ProviderConnectionFactory object without doing a JNDI lookup. You can simply use the ProviderConnectionFactory method newInstance, which will create a connection to the default provider implementation.

    ProviderConnectionFactory pcf = ProviderConnectionFactory.newInstance();
    ProviderConnection con = pcf.createConnection();

NOTE: Because this release does not come with a JNDI provider, newInstance() is the recommended way to work with a messaging provider. Typically a JNDI provider is part of a container (for example: Tomcat 4.x or J2EE); you will have to use a container-specific mechanism to populate the JNDI naming context with an appropriate instance of the ProviderConnectionFactory.
 
2. Creating a message factory

 

 

You use the connection to your messaging provider to create a MessageFactory object, which you can then use to create a message. If you specify a profile when you create a MessageFactory object, the message factory that is returned will create instances of SOAPMessage subclasses that are appropriate for the given profile.

The following code fragment uses the connection to the messaging provider to get metadata about the profiles that the provider supports. The profile that matches the ebXML profile is passed as a String to the method createMessageFactory.

    ProviderMetaData metaData = pc.getMetaData();
    String[] supportedProfiles = metaData.getSupportedProfiles();
    String profile = null;

    for(int i=0; i < supportedProfiles.length; i++) {
        if(supportedProfiles[i].equals("ebxml")) {
            profile = supportedProfiles[i];
            break;
        } 
    }
                
    MessageFactory mf = pc.createMessageFactory(profile);

3. Creating a message

 

 

With the MessageFactory object just created, you can create a SOAPMessage object that is appropriate to the minimal ebXML profile used in this RI. 

    EbXMLMessageImpl message = (EbXMLMessageImpl)mf.createMessage();
    message.setSender(new Endpoint(sender));
    message.setReceiver(new Endpoint(receiver));

4. Populating the message

 

 

This is the same as populating a message without a messaging provider.

5. Sending the message on the connection

 

 

Now that the message has been created and the various parts filled, the message is ready to be sent. In the following code sample, the message is sent asynchronously using the ProviderConnection method send. This method returns immediately after handing the message over to the messaging provider.

    pc.send(message);

6. Closing the connection

 

 

You use the ProviderConnection method close to close the ProviderConnection object when it is no longer needed.

    pc.close();

When a message is received on the client side, it is up to the application to process the message. The processing is determined by the JAXMServlet object that has been registered for the endpoint at deployment time because it has the implementation of the method onMessage. When the messaging provider gets a message, it calls the onMessage method of ReqRespListener or OnewayListener, passing it the SOAPMessage object. The implementation of the onMessage method determines how the message is processed.