Writing Hermes 2 WS client under JAVA

Introduction

This article is purposed to assist developers whose want to write a Hermes 2 web service client using JAVA.
It assumes you have successfully installed Hermes 2 and how to communicate Hermes 2 in external application.

Please refer to Hermes 2 Installation Guide and communicating hermes 2 through WS if you don't.


Table of Content

  1. Writing an ebMS 2.0 Sender Web Service client
  2. Writing an ebMS 2.0 Receiver List Web Service client
  3. Writing an ebMS 2.0 Receiver Web Service client
  4. Writing an ebMS 2.0 Status Web Service client
  5. Writing an ebMS 2.0 Message History Web Service client
  6. Writing an AS2 Sender Web Service client
  7. Writing an AS2 Receiver List Web Service client
  8. Writing an AS2 Receiver Web Service client
  9. Writing an AS2 Status Web Service client
  10. Writing an AS2 Message History Web Service client
The source code using in below section is originally from the loopback test in the Hermes 2 open source. You may refer it for full detail. Also the sample code assumes the hermes 2 you installed is in localhost with port 8080 (the default port of Tomcat).




0. Pre-requisite

The sample code requires several library and shown below:

  1. saaj-api.jar and saaj-impl.jar
    (From the starting of JDK1.6, this is already bundled along with the JDK and does not require).
  2. activiation.jar
  3. mail.jar



1. Global Import for all web service sample code

Each web service sample code requires at least the imports shown below for running properly:

import java.net.URL;
import java.net.MalformedURLException;
import javax.activation.DataHandler;
import javax.activation.FileDataSource;
import javax.xml.soap.AttachmentPart;
import javax.xml.soap.MessageFactory;
import javax.xml.soap.Name;
import javax.xml.soap.SOAPBody;
import javax.xml.soap.SOAPConnection;
import javax.xml.soap.SOAPConnectionFactory;
import javax.xml.soap.SOAPElement;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPFactory;
import javax.xml.soap.SOAPMessage;



2. Writing an ebMS 2.0 Sender Web Service client

We need to create a SOAP Message with 10 parameters (cpaId, service, action, convId, fromPartyId, fromPartyType, toPartyId, toPartyType, refToMessageId and serviceType) as the web service request message and send it to Hermes 2.
It can be done by the following steps:

1. Define the namespace URI and prefix conformed the WSDL. Also the endpoint URL of the ebMS sender web service.

private String nsURI = "http://service.ebms.edi.cecid.hku.hk/";
private String nsPrefix = "tns";
private URL senderWSURL = "http://localhost:8080/corvus/httpd/ebms/sender";

2. Create a SOAP Message factory and SOAP Message object accordingly.
SOAPMessage request = MessageFactory.newInstance().createMessage();

3. Populate the SOAP Body by filling the required parameters.
This is the sample WSDL request for the sending EbMS message WS request:
  • <cpaId> ebmscpaid </cpaId>
  • <service> http://localhost:8080/corvus/httpd/ebms/inbound <service>
  • <action> action </action>
  • <convId> convId </convId>
  • <fromPartyId> fromPartyId </fromPartyId>
  • <fromPartyType> fromPartyType </fromPartyType>
  • <toPartyId> toPartyId </toPartyId>
  • <toPartyType> toPartyType </toPartyType>
  • <refToMessageId> </refToMessageId>
  • <serviceType> </serviceType>
SOAPBody soapBody = request.getSOAPBody();
soapBody.addChildElement(createElement("cpaId", nsPrefix, nsURI, cpaId));
soapBody.addChildElement(createElement("service", nsPrefix, nsURI, service));
soapBody.addChildElement(createElement("action", nsPrefix, nsURI, action));
soapBody.addChildElement(createElement("convId", nsPrefix, nsURI, conversationId));
soapBody.addChildElement(createElement("fromPartyId", nsPrefix, nsURI, fromPartyId));
soapBody.addChildElement(createElement("fromPartyType", nsPrefix, nsURI, fromPartyType));
soapBody.addChildElement(createElement("toPartyId", nsPrefix, nsURI, toPartyId));
soapBody.addChildElement(createElement("toPartyType", nsPrefix, nsURI, toPartyType));
soapBody.addChildElement(createElement("refToMessageId", nsPrefix, nsURI, refToMessageId));
soapBody.addChildElement(createElement("serviceType", nsPrefix, nsURI, serviceType));
The method createElement basically creates a SOAP Element with namespace prefix equal to nsPrefix, the namespace URL equal to nsURI and with a textual value equal to the last arguments of the method.
The implementation of createElement is shown below:
SOAPElement soapElement = SOAPFactory.newInstance().createElement(localName, nsPrefix, nsURI);
soapElement.addTextNode(value);
return soapElement;

4. Attach a payload if necessary. The example here uses a purchase order XML as the payload of the ebms message. So the associated content type is application/xml.
AttachmentPart attachmentPart = request.createAttachmentPart();
FileDataSource fileDS = new FileDataSource(new File("purchase_order.xml"));
attachmentPart.setDataHandler(new DataHandler(fileDS));
attachmentPart.setContentType("application/xml");
request.addAttachmentPart(attachmentPart);

5. Save any changes to SOAP Message we've made.
request.saveChange();

6. Send the SOAP request to Hermes 2 ebMS Sender Web service and get the SOAP Response for extracting the message identifiers of this ebMS message you request for this SOAP request.
SOAPMessage response = soapConn.call(request, senderWSURL);
SOAPBody responseBody = response.getSOAPBody();

7. Process the SOAP Response to see whether there is any SOAP fault and extract the message identifiers to System.out if doesn't.
if (!responseBody.hasFault()){
      SOAPElement messageIdElement = getFirstChild(responseBody, "message_id", nsURI);
      System.out.println(messageIdElement == null ? null : messageIdElement.getValue());
} else {
      throw new SOAPException(responseBody.getFault().getFaultString());
}
The method getFirstChild get the first child with the name messageId and namspace URI equal to nsURI.The messageId represent the message has been sucessfully send to hermes2 and registered an identifier.
The SOAP Request is now transformed to ebms message storing in the persistence. It will deliver the ebms message a while later to your partner specifing in the SOAP request parameter (It use cpaId, service and action to identify the partnership).

Top




3. Writing an ebMS 2.0 Receiver List Web Service client

We need to create a SOAP Message with 9 parameters (cpaId, service, action, convId, fromPartyId, fromPartyType, toPartyId, toPartyType and numOfMessages) as the web service request message and send it to Hermes 2.
It can be done by the following steps:

1. Define the namespace URI and prefix conformed the WSDL.

private String nsURI = "http://service.ebms.edi.cecid.hku.hk/";
private String nsPrefix = "tns";
private String URL receiverListWSURL = "http://localhost:8080/corvus/httpd/ebms/receiver_list";

2. Create a SOAP Message factory and SOAP Message object accordingly.
SOAPMessage request = MessageFactory.newInstance().createMessage();

3. Populate the SOAP Body by filling the required parameters.
This is the sample WSDL request for the sending EbMS message WS request:
  • <cpaId> ebmscpaid </cpaId>
  • <service> http://localhost:8080/corvus/httpd/ebms/inbound <service>
  • <action> action </action>
  • <convId> convId </convId>
  • <fromPartyId> fromPartyId </fromPartyId>
  • <fromPartyType> fromPartyType </fromPartyType>
  • <toPartyId> toPartyId </toPartyId>
  • <toPartyType> toPartyType </toPartyType>
  • <numOfMessages> </100>
SOAPBody soapBody = request.getSOAPBody();
soapBody.addChildElement(createElement("cpaId", nsPrefix, nsURI, cpaId));
soapBody.addChildElement(createElement("service", nsPrefix, nsURI, service));
soapBody.addChildElement(createElement("action", nsPrefix, nsURI, action));
soapBody.addChildElement(createElement("convId", nsPrefix, nsURI, conversationId));
soapBody.addChildElement(createElement("fromPartyId", nsPrefix, nsURI, fromPartyId));
soapBody.addChildElement(createElement("fromPartyType", nsPrefix, nsURI, fromPartyType));
soapBody.addChildElement(createElement("toPartyId", nsPrefix, nsURI, toPartyId));
soapBody.addChildElement(createElement("toPartyType", nsPrefix, nsURI, toPartyType));
soapBody.addChildElement(createElement("numOfMessages", nsPrefix, nsURI, numOfMessages));
The method createElement basically creates a SOAP Element with namespace prefix equal to nsPrefix, the namespace URL equal to nsURI and with a textual value equal to the last arguments of the method.
The implementation of createElement is shown below:
SOAPElement soapElement = SOAPFactory.newInstance().createElement(localName, nsPrefix, nsURI);
soapElement.addTextNode(value);
return soapElement;

4. Save any changes to SOAP Message we've made.
request.saveChange();

5. Send the SOAP request to Hermes 2 ebMS Receiver List Web service and get the SOAP Response for extracting the message identifiers of this ebMS message you request for this SOAP request.
SOAPMessage response = soapConn.call(request, receiverListWSURL);
SOAPBody responseBody = response.getSOAPBody();

7. Process the SOAP Response to see whether there is any SOAP fault and extract the all downloadable message identifiers to System.out if doesn't.
The response is something like:
<soap-body>
     <messageIds>
         <messageId> .. </messageId>
         <messageId> .. </messageId>
         <messageId> .. </messageId>
         <messageId> .. </messageId>
     </messageIds>
</soap-body>


if (!responseBody.hasFault()){
      SOAPElement messageIdsElement = getFirstChild(responseBody, "messageIds", nsURI);
      Iterator messageIdElementIter = getChildren(messageIdsElement, "messageId", nsURI);

      while(messageIdElementIter.hasNext()) {
        SOAPElement messageIdElement = (SOAPElement)messageIdElementIter.next();
        System.out.println(messageIdElement.getValue());
      }
} else {
throw new SOAPException(responseBody.getFault().getFaultString());
}
The method getFirstChild get the first child with the name messageIds and namspace URI equal to nsURI.
It then extract messageId which represent a list of avalable message awaiting further action.
The SOAP Request is now transformed to ebms message storing in the persistence. It will deliver the ebms message a while later to your partner specifing in the SOAP request parameter (It use cpaId, service and action to identify the partnership).

Top




4. Writing an ebMS 2.0 Receiver Web Service client

We need to create a SOAP Message with the message identifier you want to download as the web service request message and send it to Hermes 2.
It can be done by the following steps:

1. Define the namespace URI and prefix conformed the WSDL.

private String nsURI = "http://service.ebms.edi.cecid.hku.hk/";
private String nsPrefix = "tns";
private URL receiverWSURL = "http://localhost:8080/corvus/httpd/ebms/receiver";

2. Create a SOAP Message factory and SOAP Message object accordingly.
SOAPMessage request = MessageFactory.newInstance().createMessage();

3. Populate the SOAP Body by filling the required parameters.
This is the sample WSDL request for the sending EbMS message WS request:
  • <messageId> messageId </messageId>
SOAPBody soapBody = request.getSOAPBody();
soapBody.addChildElement(createElement("messageId", nsPrefix, nsURI, messageId));
The method createElement basically creates a SOAP Element with namespace prefix equal to nsPrefix, the namespace URL equal to nsURI and with a textual value equal to the last arguments of the method.
The implementation of createElement is shown below:
SOAPElement soapElement = SOAPFactory.newInstance().createElement(localName, nsPrefix, nsURI);
soapElement.addTextNode(value);
return soapElement;

4. Save any changes to SOAP Message we've made.
request.saveChange();

5. Send the SOAP request to Hermes 2 ebMS Receiver List Web service and get the SOAP Response for extracting the message identifiers of this ebMS message you request for this SOAP request.
SOAPMessage response = soapConn.call(request, receiverWSURL);
SOAPBody responseBody = response.getSOAPBody();

7. Process the SOAP Response to see whether there is any SOAP fault and extract the the payload if the received ebMS message has payload inside the SOAP Response.
The response is something like:
<soap-body>
     <hasMessage>
</soap-body>
       .
       .
    attachment as a MIME part.

if (!responseBody.hasFault()){
     SOAPElement hasMessageElement = getFirstChild(responseBody, "hasMessage", nsURI);
     ArrayList payloadsList = new ArrayList();
     if (hasMessageElement != null){
        Iterator attachmentPartIter = response.getAttachments();
        while(attachmentPartIter.hasNext()) {
           AttachmentPart attachmentPart = (AttachmentPart) attachmentPartIter.next();
           InputStream ins = attachmentPart.getDataHandler().getInputStream();
           // Do something I/O to extract the payload to physical file.
        }
     }
     } else {
        throw new SOAPException(responseBody.getFault().getFaultString());
     }
The method getFirstChild get the first child with the name hasMessage and namspace URI equal to nsURI. The boolean value of hasMessage representing whethere there is payload in this message.

The payload is extracted as the input stream from the attachment part and can be saved by some traditional I/O pipeling to physical file or other business operation.

Top




5. Writing an ebMS 2.0 Status Web Service client

We need to create a SOAP Message with the message identifier you want to track it's status as the web service request message and send it to Hermes 2.
It can be done by the following steps:

1. Define the namespace URI and prefix conformed the WSDL.

private String nsURI = "http://service.ebms.edi.cecid.hku.hk/";
private String nsPrefix = "tns";
private URL statusQueryWSURL = "http://localhost:8080/corvus/httpd/ebms/status";

2. Create a SOAP Message factory and SOAP Message object accordingly.
SOAPMessage request = MessageFactory.newInstance().createMessage();

3. Populate the SOAP Body by filling the required parameters.
This is the sample WSDL request for the sending EbMS message WS request:
  • <messageId> messageId </messageId>
SOAPBody soapBody = request.getSOAPBody();
soapBody.addChildElement(createElement("messageId", nsPrefix, nsURI, messageId));
The method createElement basically creates a SOAP Element with namespace prefix equal to nsPrefix, the namespace URL equal to nsURI and with a textual value equal to the last arguments of the method.
The implementation of createElement is shown below:
SOAPElement soapElement = SOAPFactory.newInstance().createElement(localName, nsPrefix, nsURI);
soapElement.addTextNode(value);
return soapElement;

4. Save any changes to SOAP Message we've made.
request.saveChange();

5. Send the SOAP request to Hermes 2 ebMS Status Web service and get the SOAP Response for extracting the message identifiers of this ebMS message you request for this SOAP request.
SOAPMessage response = soapConn.call(request, statusQueryWSURL);
SOAPBody responseBody = response.getSOAPBody();

7. Process the SOAP Response to see whether there is any SOAP fault and extract the the status information.
The response is something like:
<soap-body>
    <MessageInfo>
       <status> The current status of message </status>
       <statusDescription> The current status description of message </statusDescription>
       <ackMessageId> The message id of acknowledgment / receipt if any </ackMessageId>
       <ackStatus> The status of acknowledgment / receipt if any </ackStatus>
       <ackStatusDescription> The status description of acknowledgment / receipt if any
       </ackStatusDescription>
    </MessageInfo>
</soap-body>

if (!responseBody.hasFault()){
    SOAPElement messageInfoElement = getFirstChild(responseBody, "messageInfo", nsURI);
    System.out.println("Message Status : "
      + getFirstChild(messageInfoElement, "status", nsURI);
    System.out.println("Message Status Desc : "
      + getFirstChild(messageInfoElement, "statusDescription", nsURI);
    System.out.println("Ack Message Identifiers : "
      + getFirstChild(messageInfoElement, "ackMessageId", nsURI);
    System.out.println("Ack Status : "
      + getFirstChild(messageInfoElement, "ackStatus", nsURI);
    System.out.println("Ack Status Desc : "
       + getFirstChild(messageInfoElement, "ackStatusDescription", nsURI);
} else {
    throw new SOAPException(responseBody.getFault().getFaultString());
}
The method getFirstChild get the first child with the name messageInfo and namspace URI equal to nsURI. It then retreive those status value from the element.




6. Writing an ebMS 2.0 Message History Web Service client

We need to create a SOAP Message with 7 parameters (messageId, messageBox, conversationId, cpaId, status, action and service) as the web service request message and send it to Hermes 2.
It can be done by the following steps:

1. Define the namespace URI and prefix conformed the WSDL.

private String nsURI = "http://service.ebms.edi.cecid.hku.hk/";
private String nsPrefix = "tns";
private URL msgHistoryWSURL = "http://localhost:8080/corvus/httpd/ebms/msg_history";

2. Create a SOAP Message factory and SOAP Message object accordingly.
SOAPMessage request = MessageFactory.newInstance().createMessage();

3. Populate the SOAP Body by filling the required parameters. This is the sample WSDL request for the message history query WS request:
  • <messageId> messageId </messageId>
  • <messageBox> messageBox </messageBox>
  • <conversationId> conversationId </conversationId>
  • <cpaId> cpaId </cpaId>
  • <service> service </service>
  • <action> action </action>
  • <status> status </status>
SOAPBody soapBody = request.getSOAPBody();
soapBody.addChildElement(createElement("messageId", nsPrefix, nsURI, messageId));
soapBody.addChildElement(createElement("messageBox", nsPrefix, nsURI, messageBox));
soapBody.addChildElement(createElement("conversationId", nsPrefix, nsURI, conversationId));
soapBody.addChildElement(createElement("cpaId", nsPrefix, nsURI, cpaId));
soapBody.addChildElement(createElement("service", nsPrefix, nsURI, service));
soapBody.addChildElement(createElement("fromPartyType", nsPrefix, nsURI, fromPartyType));
soapBody.addChildElement(createElement("action", nsPrefix, nsURI, action));
soapBody.addChildElement(createElement("status", nsPrefix, nsURI, status));

The method createElement basically creates a SOAP Element with namespace prefix equal to nsPrefix, the namespace URL equal to nsURI and with a textual value equal to the last arguments of the method. The implementation of createElement is shown below:
SOAPElement soapElement = SOAPFactory.newInstance().createElement(localName, nsPrefix, nsURI);
soapElement.addTextNode(value);
return soapElement;

4. Save any changes to SOAP Message we've made.
request.saveChange();

5. Send the SOAP request to Hermes 2 ebMS Status Web service and get the SOAP Response for extracting the message identifiers of this ebMS message you request for this SOAP request.
SOAPMessage response = soapConn.call(request, msgHistoryWSURL);
SOAPBody responseBody = response.getSOAPBody();

6. Process the SOAP Response to see whether there is any SOAP fault and extract the the status information.
The response is something like:
<soap-body>
    <messageList>
      <messageElement>
         <messageId> MessageID of the Message </messageId>
         <messageBox> Message Box containing this message </messageBox>
      </messageElement>
      <messageElement>
         <messageId> MessageID of the Message </messageId>
         <messageBox> Message Box containing this message </messageBox>
      </messageElement>
      <messageElement> . . . </messageElement>
      <messageElement> . . . </messageElement>
   </messageList>
</soap-body>

if (!responseBody.hasFault()){
    SOAPElement msgList = SOAPUtilities.getElement(responseBody, "messageList", nsURI, 0);

    Iterator msgIterator = msgList.getChildElements();
    while(msgIterator.hasNext()){

       List elementList = new ArrayList();

       SOAPElement messageElement = (SOAPElement)msgIterator.next();

       Iterator elements = messageElement.getChildElements();

       // MessageId
       SOAPElement msgId = (SOAPElement)(elements.next());

       // MessageId
       SOAPElement msgBox = (SOAPElement)(elements.next());

       System.out.println("Message ID: " + (String)msgId.get(0) +
          "\t" + "Message Box: " + msgBox.get(0));
    }
}
The method getElement get the element with the name messageList and namspace URI equal to NAMESPACE which is http://service.ebms.edi.cecid.hku.hk/. Then, list of messageElement will be extract from messageList, each messageElement contains value of messageId and messageBox.

Top




7. Writing a AS2 Sender Web Service client

We need to create a SOAP Message with 3 parameters (as2_from, as2_to, type) as the web service request message and send it to Hermes 2.
It can be done by the following steps:

1. Define the namespace URI and prefix conformed the WSDL. Also define the AS2 sender web service for Hermes 2.

private String nsURI = "http://service.as2.edi.cecid.hku.hk/";
private String nsPrefix = "tns";
private URL senderWSURL = "http://localhost:8080/corvus/httpd/as2/sender";

2. Create a SOAP Message factory and SOAP Message object accordingly.
SOAPMessage request = MessageFactory.newInstance().createMessage();

3. Populate the SOAP Body by filling the required parameters.
This is the sample WSDL request for the sending EbMS message WS request:
  • <as2_from> as2from </as2_from>
  • <as2_to> as2to <as2_to>
  • <type> type </type>
SOAPBody soapBody = request.getSOAPBody();
soapBody.addChildElement(createElement("as2_from", nsPrefix, nsURI, this.as2From));
soapBody.addChildElement(createElement("as2_to" , nsPrefix, nsURI, this.as2To));
soapBody.addChildElement(createElement("type" , nsPrefix, nsURI, this.type));
The method createElement basically creates a SOAP Element with namespace prefix equal to nsPrefix, the namespace URL equal to nsURI and with a textual value equal to the last arguments of the method.
The implementation of createElement is shown below:
SOAPElement soapElement = SOAPFactory.newInstance().createElement(localName, nsPrefix, nsURI);
soapElement.addTextNode(value);
return soapElement;

4. Attach a payload if necessary. The example here uses a purchase order XML as the payload of the ebms message. So the associated content type is application/xml.

NOTE Only ONE payload is allowed to attach in a SOAP Request for AS2 Sender web service.
AttachmentPart attachmentPart = request.createAttachmentPart();
FileDataSource fileDS = new FileDataSource(new File("purchase_order.xml"));
attachmentPart.setDataHandler(new DataHandler(fileDS));
attachmentPart.setContentType("application/xml");
request.addAttachmentPart(attachmentPart);

5. Save any changes to SOAP Message we've made.
request.saveChange();

6. Send the SOAP request to Hermes 2 ebMS Sender Web service and get the SOAP Response for extracting the message identifiers of this AS2 message you request for this SOAP request.
SOAPMessage response = soapConn.call(request, senderWSURL);
SOAPBody responseBody = response.getSOAPBody();

7. Process the SOAP Response to see whether there is any SOAP fault and extract the message identifiers to System.out if doesn't.
if (!responseBody.hasFault()){
    SOAPElement messageIdElement = getFirstChild(responseBody, "message_id", nsURI);
    System.out.println(messageIdElement == null ? null : messageIdElement.getValue());
} else {
    throw new SOAPException(responseBody.getFault().getFaultString());
}
The method getFirstChild get the first child with the name message_id and namspace URI equal to nsURI.

The SOAP Request is now transformed to as2 message storing in the file system. It will deliver the as2 message a while later to your partner specifing in the SOAP request parameter (It use AS2From and AS2To to identify the sending and receiving partnership).

Top



8. Writing a AS2 Receiver List Web Service client

We need to create a SOAP Message with 3 parameters (as2From, as2To, numOfMessages) as the web service request message and send it to Hermes 2.
It can be done by the following steps:

1. Define the namespace URI and prefix conformed the WSDL. Also define the AS2 receiver list web service for Hermes 2.

private String nsURI = "http://service.as2.edi.cecid.hku.hk/";
private String nsPrefix = "tns";
private URL receiverListWSURL = "http://localhost:8080/corvus/httpd/as2/receiver_list";

2. Create a SOAP Message factory and SOAP Message object accordingly.
SOAPMessage request = MessageFactory.newInstance().createMessage();

3. Populate the SOAP Body by filling the required parameters.
This is the sample WSDL request for the sending EbMS message WS request:
  • <as2_from> as2from </as2_from>
  • <as2_to> as2to <as2_to>
  • <numOfMessages> 100 </numOfMessages>
SOAPBody soapBody = request.getSOAPBody();
soapBody.addChildElement(createElement("as2From" , nsPrefix, nsURI, this.as2From));
soapBody.addChildElement(createElement("as2To" , nsPrefix, nsURI, this.as2To));
soapBody.addChildElement(createElement("numOfMessages", nsPrefix, nsURI, this.numOfMessages + ""));
The method createElement basically creates a SOAP Element with namespace prefix equal to nsPrefix, the namespace URL equal to nsURI and with a textual value equal to the last arguments of the method.
The implementation of createElement is shown below:
SOAPElement soapElement = SOAPFactory.newInstance().createElement(localName, nsPrefix, nsURI);
soapElement.addTextNode(value);
return soapElement;

4. Save any changes to SOAP Message we've made.
request.saveChange();

5. Send the SOAP request to Hermes 2 ebMS Receiver List Web service and get the SOAP Response for extracting the message identifiers of this ebMS message you request for this SOAP request.
SOAPMessage response = soapConn.call(request, senderWSURL);
SOAPBody responseBody = response.getSOAPBody();

7. Process the SOAP Response to see whether there is any SOAP fault and extract the all downloadable message identifiers to System.out if doesn't.
The response is something like:
<soap-body>
    <messageIds>
      <messageId> .. </messageId>
      <messageId> .. </messageId>
      <messageId> .. </messageId>
      <messageId> .. </messageId>
    </messageIds>
</soap-body>

if (!responseBody.hasFault()){
    SOAPElement messageIdsElement = getFirstChild(responseBody, "messageIds", nsURI);
    Iterator messageIdElementIter = getChildren(messageIdsElement, "messageId", nsURI);

    while(messageIdElementIter.hasNext()) {
      SOAPElement messageIdElement = (SOAPElement)messageIdElementIter.next();
      System.out.println(messageIdElement.getValue());
    }
} else {,br/>     throw new SOAPException(responseBody.getFault().getFaultString());
}
The method getFirstChild get the first child with the name messageIds and namspace URI equal to nsURI.
It then extract all children with the name messageId and namespace URI equal to nsURI.
The SOAP Request is now transformed to ebms message storing in the persistence. It will deliver the ebms message a while later to your partner specifing in the SOAP request parameter (It use cpaId, service and action to identify the partnership).

Top



9. Writing a AS2 Receiver Web Service client

The procedure is same as ebMS Receiver Web Service Client except following variables are different :

  1. namespace URI : http://service.as2.edi.cecid.hku.hk/
  2. web service URL : http://localhost:8080/corvus/httpd/as2/receiver

Top



10. Writing a AS2 Status Web Service client

We need to create a SOAP Message with the message identifier you want to track it's status as the web service request message and send it to Hermes 2.
It can be done by the following steps:

1. Define the namespace URI and prefix conformed the WSDL.

private String nsURI = "http://service.as2.edi.cecid.hku.hk/";
private String nsPrefix = "tns";
private URL statusQueryWSURL = "http://localhost:8080/corvus/httpd/as2/status";

2. Create a SOAP Message factory and SOAP Message object accordingly.
SOAPMessage request = MessageFactory.newInstance().createMessage();

3. Populate the SOAP Body by filling the required parameters.
This is the sample WSDL request for the sending EbMS message WS request:
  • <messageId> messageId </messageId>
SOAPBody soapBody = request.getSOAPBody();
soapBody.addChildElement(createElement("messageId", nsPrefix, nsURI, messageId));
The method createElement basically creates a SOAP Element with namespace prefix equal to nsPrefix, the namespace URL equal to nsURI and with a textual value equal to the last arguments of the method.
The implementation of createElement is shown below:
SOAPElement soapElement = SOAPFactory.newInstance().createElement(localName, nsPrefix, nsURI);
soapElement.addTextNode(value);
return soapElement;

4. Save any changes to SOAP Message we've made.
request.saveChange();

5. Send the SOAP request to Hermes 2 AS2 Status Web service and get the SOAP Response for extracting the message identifiers of this ebMS message you request for this SOAP request.
SOAPMessage response = soapConn.call(request, statusQueryWSURL);
SOAPBody responseBody = response.getSOAPBody();

6. Process the SOAP Response to see whether there is any SOAP fault and extract the the status information.
The response is something like:
<soap-body>
    <MessageInfo>
      <status> The current status of message </status>
      <statusDescription> The current status description of message </statusDescription>
      <mdnMessageId> The message id of acknowledgment / receipt if any </mdnMessageId>
      <mdnStatus> The status of acknowledgment / receipt if any </mdnStatus>
      <mdnStatusDescription> The status description of acknowledgment / receipt if any
      </mdnStatusDescription>
    </MessageInfo>
</soap-body>

if (!responseBody.hasFault()){
    SOAPElement messageInfoElement = getFirstChild(responseBody, "MessageInfo", nsURI);
    System.out.println("Message Status : "
      + getFirstChild(messageInfoElement, "status", nsURI);
    System.out.println("Message Status Desc : "
      + getFirstChild(messageInfoElement, "statusDescription", nsURI);
    System.out.println("Ack Message Identifiers : "
      + getFirstChild(messageInfoElement, "mdnMessageId", nsURI);
    System.out.println("Ack Status : "
      + getFirstChild(messageInfoElement, "mdnStatus", nsURI);
    System.out.println("Ack Status Desc : "
      + getFirstChild(messageInfoElement, "mdnStatusDescription", nsURI);
} else {
    throw new SOAPException(responseBody.getFault().getFaultString());
}
The method getFirstChild get the first child with the name message_id and namspace URI equal to nsURI.

Top




11. Writing an AS2 Message History Web Service client

We need to create a SOAP Message with 5 parameters (messageId, messageBox, as2From, as2To, and status) as the web service request message and send it to Hermes 2.
It can be done by the following steps:

1. Define the namespace URI and prefix conformed the WSDL.

private String nsURI = "http://service.as2.edi.cecid.hku.hk/";
private String nsPrefix = "tns";
private URL msgHistoryWSURL = "http://localhost:8080/corvus/httpd/as2/msg_history";

2. Create a SOAP Message factory and SOAP Message object accordingly.
SOAPMessage request = MessageFactory.newInstance().createMessage();

3. Populate the SOAP Body by filling the required parameters. This is the sample WSDL request for the message history query WS request:
  • <messageId> messageId </messageId>
  • <messageBox> messageBox </messageBox>
  • <as2From> as2From </as2From>
  • <as2To> as2To </as2To>
  • <status> status </status>
SOAPBody soapBody = request.getSOAPBody();
soapBody.addChildElement(createElement("messageId", nsPrefix, nsURI, messageId));
soapBody.addChildElement(createElement("messageBox", nsPrefix, nsURI, messageBox));
soapBody.addChildElement(createElement("as2From", nsPrefix, nsURI, cpaId));
soapBody.addChildElement(createElement("as2To", nsPrefix, nsURI, service));
soapBody.addChildElement(createElement("status", nsPrefix, nsURI, status));

The method createElement basically creates a SOAP Element with namespace prefix equal to nsPrefix, the namespace URL equal to nsURI and with a textual value equal to the last arguments of the method. The implementation of createElement is shown below:
SOAPElement soapElement = SOAPFactory.newInstance().createElement(localName, nsPrefix, nsURI);
soapElement.addTextNode(value);
return soapElement;

4. Save any changes to SOAP Message we've made.
request.saveChange();

5. Send the SOAP request to Hermes 2 AS2 Message History Web service and get the SOAP Response for extracting the message identifiers of this ebMS message you request for this SOAP request.
SOAPMessage response = soapConn.call(request, receiverListWSURL);
SOAPBody responseBody = response.getSOAPBody();

6. Process the SOAP Response to see whether there is any SOAP fault and extract the the status information.
The response is something like:
<soap-body>
    <messageList>
      <messageElement>
        <messageId> MessageID of the Message </messageId>
        <messageBox> Message Box containing this message </messageBox>
      </messageElement>
      <messageElement>
        <messageId> MessageID of the Message </messageId>
        <messageBox> Message Box containing this message </messageBox>
      </messageElement>
      <messageElement> . . . </messageElement>
      <messageElement> . . . </messageElement>
    </messageList>
</soap-body>

if (!responseBody.hasFault()){
    SOAPElement msgList = SOAPUtilities.getElement(responseBody, "messageList", nsURI, 0);

    Iterator msgIterator = msgList.getChildElements();
    while(msgIterator.hasNext()){

      List elementList = new ArrayList();

      SOAPElement messageElement = (SOAPElement)msgIterator.next();

      Iterator elements = messageElement.getChildElements();

      // MessageId
      SOAPElement msgId = (SOAPElement)(elements.next());

      // MessageId
      SOAPElement msgBox = (SOAPElement)(elements.next());

      System.out.println("Message ID: " + (String)msgId.get(0) +
        "\t" + "Message Box: " + msgBox.get(0));
    }
The method getElement get the element with the name messageList and namspace URI equal to NAMESPACE which is http://service.as2.edi.cecid.hku.hk/. Then, list of messageElement will be extract from messageList, each messageElement contains value of messageId and messageBox.
Top



Reference Article




Reference Documentation

  • Hermes 2 Application Development Guide



Reference Program Source



Posted by Twinsen Tsang on 06/20 at 11:50 AM