Introduction	Top

The LabVantage implementation of Axis and JAX Web Services comply with the reference implementations shown below. Choose the service with the reference implementation that meets your requirements.

LabVantage also provides a RESTful implementation. See LabVantage REST Web Services for information. 

SapphireWS	Top

Before proceeding, you must make certain the Ajax/JAX Web Services are enabled. Enable them if necessary by setting the Web Services → Enable property in the Security Policy to "Yes". Save, then restart the Application Server and the LabVantage application.

For clarity, this section uses example directory names rather than environment variables. If you want to use variables in a script, we recommend:

In general, these are suggested guidelines for preparing your environment:

Generate the WSDL file as follows:

Generate the Service Locator and stubs by running the example command shown below in C:\sapphirews (see http://ws.apache.org/axis/java/reference.html).

<path>\java.exe -classpath "C:\ear\labvantage.ear\lib\*;C:\ear\labvantage.ear\sapphire.jar" org.apache.axis.wsdl.WSDL2Java -o . -a -t -v -p .\gen SapphireWS.wsdl

where <path> is the path to java.exe (in the JDK). Also note that this example assumes the location of the exploded EAR is in C:\ear\labvantage.ear.

This command generates these Java source files in C:\sapphirews\gen:

You can ignore this message if it is issued: "Unable to find required classes (javax.activation.DataHandler and javax.mail.internet.MimeMultipart). Attachment support is disabled."

These operations provide generic calls to the LabVantage Java Public API (such as getSQLDataSet and processAction). However, they use LabVantage-specific XML structures to send/receive data to/from the Web Service. These methods allow direct object interaction with SOAP languages such as .NET. All parameters are "String" data type.

Note that the operations above make generic calls to the LabVantage Java Public API (such as getSqlDataSet and processAction). They also use LabVantage-specific XML structures to send/receive data to/from the Web Service, i.e., XML is sent within XML. This can sometimes be inefficient, since LabVantage objects must be manually serialized to LabVantage XML structures, then deserialized in the client using the XML structure to create the objects. Note that the LabVantage propertylist and dataset XML does not use standard XML ddt or schema, and is therefore not recognized by other languages.

To provide more efficient execution, the additional methods below used Transport Beans for classes that handle entities such as for Data Sets, Property Lists, and SDI Data. These are Java Bean Wrappers for classes that are built from primitives and expose get and set properties. Each complex LabVantage API object is therefore wrapped by a primitive Java Bean and return the Java Bean objects. This means that the SOAP interface in the LabVantage Axis engine and on the .NET (or other language) client is responsible for serialization. LabVantage therefore needs not know anything about the object, so it can be used "as-is" on the client. This allows direct object interaction with SOAP languages such as .NET. For example, you can send a Property List object to the Web Service call to process an Action. With the old methods and XML structures, you would have to send a Property List XML string... which the 3rd party vendor does not know how to build. The more complex methods such as getSDIData, getSDCProperties and getDatabaseList let you use functionality available through the LabVantage Java Public API to query the database. You can therefore do things such as query SDCs for primary and detail tables from any external language, rather than having to know the exact SQL and data structure of LabVantage.

The four examples described below use the SapphireWS Web Service to demonstrate various Web Service techniques. These examples assume that you know how to compile and run Java classes. Note that the declared package in each file is com.labvantage.training, so structure your environment accordingly.

SapphireBasicWS	Top

Before proceeding, you must make certain the Ajax/JAX Web Services are enabled. Enable them if necessary by setting the Web Services → Enable property in the Security Policy to "Yes". Save, then restart the Application Server and the LabVantage application.

Generate the WSDL file as follows:

The JAX-WS implementation permits using SOAP to directly call the WS endpoints without any stubs.

These operations are available with SapphireBasicWS. These entry point methods accept primitive types and are WS-I compliant.

HTTPS	Top

For guidelines concerning use of Axis/Jax Web Services over HTTPS connections, see Guidelines for Using Web Services over HTTPS.