This is the specification for Isode's High Level X.400 Java Client API (HLXJA)

This API is an extension of the existing X.400 Java API, which in turn uses the X.400 C API. The goal of this API is to allow developers to easily build X.400 User Agents (UAs).

The main characteristics of this API are:

  • use of standard Java setters and getters to make programming X.400 UAs more intuitive
  • consistent exception handling
  • capable of using P3 or P7
  • compatible with the existing X.400 Java API, so that the same objects can be used for lower level API access if needed

HLXJA can be used to connect to either an X.400 MTAs via P3 or to an X.400 Message Store via P7. In most cases client applications can be written to so that most of the code is the same, independently of the protocol being used. However, there are operations like P7 Summarize that only apply to P7 connections. The documentation makes clear those cases when the protocol being used affects functionality.

Writing an application which uses HLXJA

Client applications will typically follow this this basic structure (see the sections below):

  • Create bind session objects corresponding to the messaging servers that will be used
  • Send or receive messages
  • Unbind from the messaging server

Session objects

The session classes P3BindSession and P7BindSession are used to encapsulate information about a connection.

P3BindSession objects are constructed by specifying three parameters: the presentation address of an MTA's P3 channel, the O/R address of the user and the password of the user. The Presentation Address is a String that may be an RFC 1278 format presentation address (for example, "593"/Internet=server.host.net+102).

P7BindSession objects are constructed by specifying three parameters: the presentation address of an P7 Message Store, the O/R address of the user and the password of the user. The Presentation Address of the P7 Message Store is a String that may be an RFC 1278 format presentation address (for example, "3001"/Internet=server.host.net+3001).

Having created a session object, an application will use the bind() methods to bind to the server. 

Sending and receiving messages

Included in this API there are a couple of examples on how to send X.400 messages (com.isode.x400.highlevel.test.SendX400Mail.java) and to receive X.400 messages (com.isode.x400.highlevel.test.ReceiveX400Mail.java)

Unbinding from a server

The unbind() method is used to unbind from server. Normally an application will bind to a server and keep the connection open sending and or receiving messages with the same session. It is good practice for applications to unbind once they no longer require a connected session, as otherwise errors will be logged by the server.

Exceptions

The HLXJA uses X400APIExceptions to report errors which are likely to be caught and handled by user code. For example, an attempt to bind to a message store that is not running will result in a NotBoundException being thrown.

Multi-threaded applications

Just like the X.400 Java API, the HLXJA is designed to be used with a multi-threaded process, and a process may have multiple associations. However, each association must only be accessed by a single thread.

Building and Deploying an application which uses the High Level X.400 Java Client API

The HLXJA class library is contained inside isode-hlxja.jar, which by default is installed, along with various other class libraries, in the directory (LIBDIR)/java/classes. To compile an application which uses HLXJA, you must ensure that isode-hlxja.jar appears on the CLASSPATH used by the compiler.

To run an application which uses the High Level X.400 Java Client API you must have isode-hlxja.jar on your CLASSPATH, and you must also make sure that the JVM is able to locate shared libraries that are used by High Level X.400 Java Client API . These shared libraries are installed in (LIBDIR).

For example, to build an application on Unix, you would use something like: 

% javac -cp /opt/isode/lib/java/classes/isode-hlxja.jar MyClass.java
and to run the application: 
% java -Djava.library.path=/opt/isode/lib -cp /opt/isode/lib/java/classes/isode-hlxja.jar:. MyClass


There are further examples with a Unix shell script and a Windows batch file that explains how to run an application written using this API.
There are also instructions on how to import the project into Eclipse to develop UAs using this environment.

Examples

There are currently two sample programs, both can use either P3 or P7 servers. One connects to a server and sends a sample message to itself, the other example connects to a server and receives a message, printing the information in stdout.


Packages 
Package Description
com.isode.x400.highlevel