Setting up of the Hermes2 Messaging Gateway

Introduction

Hermes 2 (or Corvus, the codename we used to call in the office) is a messaging gateway that enables the handling of electronic messages in the format of AS2 or ebMS. For details, you can refer to our product web page.

I have noticed different questions in the mailing list, and as one of the developer behind the product, I hope my contribution can help those people who is interested in using it.

First off, let's start our installation.

The procedures are basically the same as indicated in the installation guide but I will include a small section in answering some commonly asked question. Also, I want to bring up some interesting finding as I am going to deploy Hermes in a little bit different environment.

Prerequisite

Apart from the binary of Hermes 2, you will need to prepare some other supporting applications, note that I have replaced Postgres with Mysql cause my web host only provides the later one. :D

NOTE : I don't have time to test out everything on this platform so if you want full compliance, stick with Postgres. ;)

• Java JDK 1.4.2_04
  
• Java Cryptography Extension (JCE). It can be found in the download page of JDK 1.4.
  
• tomcat 5.0.28
  
• Mysql (I am using 4.1)
  

Configuration - Mysql

I will highlight the steps nvolved in using Mysql in place of Postgres, but for the rest of the installation, please check out the details from the installation guide.

1. Create two databases, named as "as2" and "ebms" respectively
   
2. Create an user "corvus", grant the right to "CREATE", "DELETE", "DROP", "SELECT", "INSERT", "UPDATE". Or you can simply grant ALL if you are as lazy as me.
   
3. Modify the table schemas, replace "VARCHAR" with "VARCHAR(255)" and "BYTEA" with "BLOB". Or you can download my copy from here.
   
4. Create the tables accordingly.
   

Configuration - Hermes

The configuration files in the binary is having Postgres configured as the database of choice. You will need to change the setting in using Mysql instead.

1. 
   Get yourself a nice editor, search for the string
   

   "org.postgresql.Driver"
   

   
   and replace it with
   

   "com.mysql.jdbc.Driver"

   
   
   Also, locate this as well,
   

   "jdbc:postgresql://localhost:5432/ebms"

   
   and replace it with,
   

   "jdbc:mysql://127.0.0.1:3306/ebms"

   
   
   Repeat the procedure for AS2.
   
2. 
   Put the jdbc driver of Mysql into the "lib" folder of the Corvus webapps
   

You can now startup the tomcat and check the various log files (catalina.out, corvus.log, ebms.log and as2.log) that no errors are thrown.

Configuration - Loopback test

Congratulation! Now you are just one step away from completion.

It doesn't mean all is set even if no error is thrown during startup, let's try out our installation with the loopback test. BUT since the program is developed with Postgres in mind so some changes has to be made.

1. Copy the JDBC driver of Mysql into the lib folder and modify the execution batch files to include it in the classpath.
   
2. Modify the file "partnership.module.corel.xml" in the "conf" folder. Do the same thing as in Step 1 in Hermes 2 configuration.
   

Ta-da, now you are all set and done. Run the loopback test as usual and you should get the following results,


- Module 'Corvus Partnership' initialized successfully.
Start sending AS2 loopback test case.
Sent AS2 loopback test case with returned message ID 20061117-170806-45901@210.245.164.9.
Start checking the received list.
Download the message from the list with ID 20061117-170806-45901@210.245.164.9.
Downloaded successfully.
End checking the received list.
============================
AS2 loop back test finished.
============================


Note

There's something funny upon executing the loopback test ...

I have encountered several DAO issues and turns out it is the case sensitivity in the SQL query. The DB tables are all created with a big cap for the first letter and somehow, in the SQL query, some of the statement is using lower cap and the mismatch leads to the DAO issue. I have changed the table name accordingly in all the DAO XML files and everything is working fine.

What if ...

You are lucky if everything can go in one pass. I will put up pointer to questions which I have seen many times in the google group.

1. When I boot up Hermes 2, I saw this message in the corvus.log,
   

   Unsupported keysize or algorithm parameters

   
   
   This error will raise if you forgot to deploy the JCE patch. Make sure you are copying to the right location. Also, I found that I have to set the "JAVA_HOME" in my user profile in order to have the patch loaded properly.
   
   
2. Why is the JDK version so specific? Can I use some other version like JDK 1.5?
   Trust me, you will save yourself a lot of time in using the version we request. We find that a method we rely on, has somehow been changed to a private method since 1.4.2_04, so you might experience issues like
   
   

   java.lang.IllegalAccessError: tried to access field
org.apache.xpath.compiler.FunctionTable.m_functions from class org.apache.xml.security.Init

   
   
   For JDK 1.5, we have identified some code changes that need to be done before it can operate properly.
   
3. Is the "wildcard" feature that was introduced in Hermes 1 still valid in Hermes 2?
   No, this feature has been taken away from Hermes 2, due to the change in principle from push mode to polling mode. You need to specify precisely on what are the messages you want to send or receive.
   
4. OK, now everything is working, what if I want to write a client?
   To keep things simple, let's focus on ebms message delivery first. First of all, you need to create a "partnership" for sending out messages. You can do so by using the program in the loopback test, the program will read a "data" file which define the details of the partnership (think partnership to CPA in ebMS).
   After that, you develop your program and make a web service call to Corvus for message delivery. The web service call will include some of the key information you defined in the partnership, so that Corvus can pick up the rest (like where to send it to) from the database.
   The "end point" on Corvus that responsible for picking up the request is
   "http://127.0.0.1:8080/corvus/httpd/ebms/sender" and you need to supply the following information in the web service call,
   
   
   
   • cpaId
     
   • service
     
   • action
     
   • conversation id
     
   • from party id
     
   • from party id type
     
   • to party id
     
   • to party id type
     
   • ref to message id
     
   
   Also, you will want to create an "AttachmentPart" which carries the "payload" you want to send over to the recipient.
   Upon making the request, you should get a soap response. The body inside should contain an element called "message_id" and the value of this is a string. This is the "token" that Corvus generated for you. You can use this "token" to perform query.
   

I hope this episode can help you a bit in kicking start the installation. When you are busying in setting up the environment, I will prepare my next episode, focusing on the partnership thing and hope to bring you something more interesting. Stay tuned.

Comments

[eXXos]

Thanks a lot for this tutorial. Very helpful and interesting !

[Gary]

Hi,

You mentioned

For JDK 1.5, we have identified some code changes that need to be done before it can operate properly.

Can you advise what these are? I get the following when I run the loopback test

C:\corvus\plugins>loopback.bat ebms
- Module 'Corvus Partnership' initialized successfully.
Start sending ebMS loopback test case.
AxisFault
faultCode: {http://xml.apache.org/axis/}HTTP
faultSubcode:
faultString: (404)/ebms/sender
faultActor:
faultNode:
faultDetail:
{}string: return code: 404
<html><head><title>Apache Tomcat/5.5.20 - Error report</tit
le><style><!--H1 {font-family:Tahoma,Arial,sans-serif;color:white;ba
ckground-color:#525D76;font-size:22px;} H2 {font-family:Tahoma,Arial,sans-serif;
color:white;background-color:#525D76;font-size:16px;} H3 {font-family:Tahoma,Ari
al,sans-serif;color:white;background-color:#525D76;font-size:14px;} BODY {font-f
amily:Tahoma,Arial,sans-serif;color:black;background-color:white;} B {font-famil
y:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;} P {font-family:
Tahoma,Arial,sans-serif;background:white;color:black;font-size:12px;}A {color :
black;}A.name {color : black;}HR {color : #525D76;}--></style> </hea
d><body><h1>HTTP Status 404 - /ebms/sender</h1><HR size=
"1" noshade="noshade"><p><b>type</b> St
atus report</p><p><b>message</b> <u>/ebms/sender&l
t;/u></p><p><b>description</b> <u>The requested
resource (/ebms/sender) is not available.</u></p><HR size="
1" noshade="noshade"><h3>Apache Tomcat/5.5.20</h3>
</body></html>

(404)/ebms/sender
at org.apache.axis.transport.http.HTTPSender.readFromSocket(HTTPSender.j
ava:630)
at org.apache.axis.transport.http.HTTPSender.invoke(HTTPSender.java:128)

at org.apache.axis.strategies.InvocationStrategy.visit(InvocationStrateg
y.java:71)
at org.apache.axis.SimpleChain.doVisiting(SimpleChain.java:150)
at org.apache.axis.SimpleChain.invoke(SimpleChain.java:120)
at org.apache.axis.client.AxisClient.invoke(AxisClient.java:180)
at org.apache.axis.client.Call.invokeEngine(Call.java:2564)
at org.apache.axis.client.Call.invoke(Call.java:2553)
at org.apache.axis.client.Call.invoke(Call.java:2248)
at org.apache.axis.client.Call.invoke(Call.java:2171)
at org.apache.axis.client.Call.invoke(Call.java:1691)
at hk.hku.cecid.edi.ebms.service.EbmsSoapHttpSendStub.request(EbmsSoapHt
tpSendStub.java:110)
at hk.hku.cecid.corvus.test.EbmsLoopBackTest.send(EbmsLoopBackTest.java:
87)
at hk.hku.cecid.corvus.test.EbmsLoopBackTest.main(EbmsLoopBackTest.java:
44)
The corvus log looks like this

2007-02-12 16:41:53 [http-8080-1 ]
2007-02-12 16:43:56 [http-8080-1 ]
2007-02-12 16:54:34 [http-8080-1 ]

[juan]

hello!
This tutorial very interesting; as can send me a ack?

[ronnie]

Gary, I hope we have some good news to you, my colleague is indeed trying to make Hermes2 running properly under JDK1.5. Basically, there are two things that you need to cater,

1. Modify the class "hk.hku.cecid.piazza.commons.xpath.XPathFunctionsProvider" and add the following method,

public Object extFunction(FuncExtFunction arg0, Vector arg1)
throws TransformerException {
return null;
}

This is to address the issue raised from JAXP compatibility issue.

2. Change all the variable with the name "enum" to something else as "enum" is now a reserved keyword.

We can now have the loopback running properly under JDK 1.5 but I guess we still need additional testing before we can call it JDK 1.5 compliant.

Hope this help!

[ronnie]

Juan, do u want me to send a message to your server? What's the endpoint ?

[juan]

I'd like to send a ack to client ebmail.

another doubt, why in ebms.log?:

hk.hku.cecid.piazza.commons.net.ConnectionException: Unable to connect to incoming mail server
by javax.mail.AuthenticationFailedException: Authentication failed.
at hk.hku.cecid.piazza.commons.net.MailReceiver.connect(MailReceiver.java:66)
at hk.hku.cecid.ebms.spa.task.MailCollector.getTaskList(MailCollector.java:49)
at hk.hku.cecid.piazza.commons.module.ActiveTaskModule.execute(ActiveTaskModule.java:137)
at hk.hku.cecid.piazza.commons.module.ActiveModule.run(ActiveModule.java:205)
at java.lang.Thread.run(Thread.java:534)

thank you very much

[Ghassan]

What about the table type storage engine when using Mysql in place of Postgres?? InnoDB, for example.

[ronnie]

Ghhassan, I haven't touched the storage engine, all I have done is to update the table schema with the appropriate datatype.

[Cheap Name brand products,Monc]

Oh my goodness! an remarkable article dude. Thank you However I am experiencing issue with ur rss . Don't know why Unable to subscribe to it. Is there anybody acquiring identical rss dilemma? Anybody who knows kindly respond. Thanks