Skip to main content

Using the jxAPI With Java and Apache Axis2

Warning: legacy API

This page is about the legacy SOAP-based jxAPI that is no longer updated or recommended for use in new projects. The documentation in this section may be outdated or inaccurate, and is provided for reference purposes only.

Journyx recommends using the REST-based API for new projects in most cases. However, at the current time, there are certain object types that are not available through the REST API.

Requirements​

  • A Journyx installation, version 9.0m or newer
  • Java JDK 6 or newer
  • Maven or other dependency manager (may be part of your IDE)

For versions of Journyx prior to 9.0m, please see below.

The jxAPI Client​

In your Journyx install's doc directory, we have provided a pre-built Apache Axis2 stub plus some useful utility functions. Located in jxapi_samples/java/jxapi_client, it is provided as a Maven project which you can (but should not have to) build yourself, with its generated jar under the target subdirectory so that you can drop it directly into your own project or insert it into your local Maven repository for future use.

The jxAPI client package has the following dependencies (which should be handled automatically by your dependency manager):

  • org.apache.axis2 / kernel / 1.6.2
  • org.apache.axis2 / adb / 1.6.2
  • org.apache.axis2 / axis2-transport-local / 1.6.2
  • org.apache.axis2 / axis2-transport-http / 1.6.2

The jxAPI client package can be used from most JVM-based languages (Clojure or Scala, for example), using those languages' standard Java interoperability capabilities.

Connecting​

The jxAPI client provides connection methods in the JxapiUtil class of the com.journyx.jxapi package. For example, to establish a connection:

import com.journyx.jxapi.*;
import org.apache.axis2.*;

public class MyApp {
  JxapiStub jx;

  public void setupAPI() throws AxisFault {
    this.jx = JxapiUtil.connect("localhost", 10000);
  }
}

The connect method takes an optional third argument which, if true, will attempt to use SSL to connect to the Journyx server.

Calling jxAPI Methods​

The JxapiStub object you get back from JxapiUtil.connect is a standard Axis2 API stub, meaning that it has methods corresponding to those described in the jxAPI documentation for typed APIs.

Exceptions from the Journyx server will cause an org.apache.axis.AxisFault exception to be thrown in the client. To determine the exact exception thrown on the server side, you will need to catch the AxisFault object and use its methods to inspect its contents.

Because the jxAPI documentation uses generic names for data types, note that the corresponding types in Java are:

  • a jxAPI "integer" is a java.math.BigInteger
  • a jxAPI "long" is also a java.math.BigInteger
  • a jxAPI "float" is a double
  • a jxAPI "string" is a java.lang.String
  • a jxAPI "boolean" is a boolean
  • a jxAPI "list" is a Java array
  • a jxAPI "record" or "structure" is a Java object

Records​

jxAPI records are represented in Java by classes from the jxapi package. These classes have a standard bean-type interface with accessor methods for each field.

If you instantiate an empty record directly with new, note that all unused string fields must be filled with an empty string before passing the record to the jxAPI or the server will throw an exception. As a convenience, you can use the newRecord or newRecordWithID methods from JxapiUtil to do this for you:

import jxapi.*;
import com.journyx.jxapi.*;

...
TimeRecord trec = (TimeRecord) JxapiUtil.newRecord(TimeRecord.class);
ProjectRecord prec = (ProjectRecord) JxapiUtil.newRecordWithID(ProjectRecord.class, "root");

Note that you pass in the actual class of record you wish to create, and must cast the result to the proper type.

Journyx Versions Before 9.0m​

To use the jxAPI from Java with Journyx versions from 8.8 to 9.0, you must build your own Axis2 stubs. (You can use the jxapi_client Maven project as an example of how to do this, but replace the WSDL in src/wsdl with one retrieved from your Journyx server at the URL http://hostname:port/jxapi_wsi.wsdl ). The following differences will apply:

  • You cannot use the JxapiUtil.connect method directly; either create the Axis2 stub directly or use the source to the connect method as an example of how to write your own.
  • You must connect to the SOAP URL http://hostname:port/jtcgi/jxapi_wsi.pyc
  • You must call _getServiceClient().getOptions().setProperty(HTTPConstants.CHUNKED, false) on your Axis2 stub after creating it. (HTTPConstants is in the org.apache.axis2.transport.http package.)
  • Arrays passed or returned from jxAPI methods will have an extra level of indirection; that is, instead of being passed and returned as native Java arrays, they will be objects of a class such as Array_of_string and you will have to call an accessor method to get the array from inside them. See the sample code in java_demo_axis2 for examples.

Clients built this way will continue to work with newer versions of Journyx.

Journyx Versions Before 8.8​

To use the jxAPI from Java with Journyx versions prior to 8.8, you must use Axis1; see java_axis1 for more details.