Tuesday, June 10, 2008

Technical Notes: Using the JangoMail API with Java

Robert Fischer is the creator of OffstageArts, an open source integrated arts management system (http://offstagearts.org). OffstageArts is written in Java and deployed via Java WebStart. Mr. Fischer has graciously provided notes on his solution for us to post so others can follow in his footsteps. Many thanks to Robert for sharing his work with us!

Using JangoMail with Java

The most convenient way to use JangoMail with Java is to use Java-based SOAP tools. Apache Axis (http://ws.apache.org/axis/) is available as a commponly used Java SOAP system. Although these tools can be intimidating at first, they make life much easier over the long run. Moreover, using them does not require much effort, just follow the steps below.

Axis is able to download the JangoMail WSDL web service description file and generate a set of JangoMail Java stub classes from it. You can then compile those classes and use them in your application. The JangoMail SOAP stub classes (generated by Axis) insulate you from the complexities of SOAP XML. An example of using these classes:


// Make a service

JangoMail service = new JangoMailLocator();

// Now use the service to get a stub which implements the SDI.

String usr = "JangoMailUserName";
String pwd = "JangoMailPassword";
JangoMailSoap soap = service.getJangoMailSoap(new URL(https://api.jangomail.com/api.asmx));

soap.addGroup(usr, pwd, "TestGroup");

Doing It -- Automated

The easiest way to go through this process is to use the enclosed Netbeans/Maven project. For this, you will need NetBeans with the Maven Plug-in. If you do not have that, it can be obtained at: http://netbeans.org/ and then by following directions at: http://mevenide.codehaus.org/m2-site/mevenide2-netbeans/installation.html

With NetBeans+Maven, you are now ready to go:

  1. Download and unzip the accompanying project from the following link, and open it in NetBeans: Download here.
  2. Edit the file RunWsdl.java and make sure the variable "mavenProjectRoot" is set correctly for your project home directory.
  3. Right-click on the project and select "Run." This should download the WSDL file and generate all the necessary Java classes in the project.
  4. Right-click on the project and select "Clean and Build." This will compile the Java classes you just produced. Look at Test.java for a simple example on how these classes can be used.

This procedure has now produced a file "jangomail-1.0-LATEST.jar" that you can use in other projects. If your other projects are Maven- based, you can use the dependency:

groupId = com.jangomail
artifactId = jangomail
version = 1.0-LATEST

When the JangoMail API changes, you must re-run this procedure to make the updates available to your application.

Doing It -- Manual

If you do not have NetBeans + Maven, then you will need to download Axis and run it manually:

  1. Download Apache Axis from http://ws.apache.org/axis/
  2. Put all the jar files in Apache Axis on your CLASSPATH.
  3. In a command shell, change directory to your source directory.
  4. Run the command:
    java org.apache.axis.wsdl.WSDL2Java https://api.jangomail.com/api.asmx?WSDL
  5. Compile the source code that results.
You can now use these classes in your own program, as given in the example above. You will have to include the Axis-supplied .jar files as well.