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();
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();
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.
SOAPPart sp = message.getSOAPPart(); SOAPEnvelope envelope = sp.getSOAPEnvelope();
SOAPHeader header = envelope.getSOAPHeader(); SOAPBody body = envelope.getSOAPBody();
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");
SOAPBodyElement bodyElement = body.addBodyElement( envelope.createName("Text", "jaxm", "http://java.sun.com/jaxm")); bodyElement.addTextNode("Some-text");
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);
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();
Now that the message has been created and its various parts filled, the message is ready to be sent.
URLEndpoint
object
with the URL of the endpoint to which the message is to be sent.URLEndpoint endPoint = new URLEndpoint("http://myservice.com/orders/info");
SOAPMessage reply = connection.call(message, endPoint);
You need to close the SOAPConnection object when it is no longer
needed by calling the method
close
.
connection.close();
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.
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 JavaTM 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 messaging provider that has registered a
ProviderConnectionFactory
object with a JNDI
naming service, using the newInstance method
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 object.
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);
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));
This is the same as populating a message without a messaging provider.
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);
You use the ProviderConnection method close to close the ProviderConnection object when it is no longer needed.
pc.close();
The client application sends a request to an endpoint that is a web services
application. When the web service receives the request, it needs to process
the message, which it does in its implementation of the
method onMessage
. The web service will have implemented either the
the onMessage method of the interface
ReqRespListener
or OnewayListener
,
depending on what kind of messaging it does.
When the messaging provider gets a message for the web service, it invokes the
onMessage
method, passing it the SOAPMessage
object.
A web service that receives messages and is running in a servlet may extend the
JAXMServlet
class in order to work with the messaging provider
and the servlet container. The web service would have registered the
JAXMServlet
object at deployment time, allowing the messaging provider
to notify the container that a message has been received. A component that extends
the JAXMServlet
class must also implement either the
ReqRespListener
or OnewayListener
interface.