WSIL4J:
Web Services Inspection Language for Java API

The Web Services Inspection Language (WS-Inspection) provides a distributed Web service discovery method, by specifying how to inspect a web site for available Web services. The WS-Inspection specification defines the locations on a Web site where you could look for Web service descriptions.

WSIL4J Structure

WSIL4J is a Java class library that provides an API that is can be used to locate and process WS-Inspection documents. This class library can be used to read and parse a WS-Inspection document, as well as generate a new WS-Inspection document. The primary class for interacting with a WS-Inspection document is org.apache.wsil.WSILDocument. The org.apache.wsil.client.WSILProxy class is used for accessing specific service descriptions within a WS-Inspection document. For example, you can use this class to access service descriptions by service name. A WSILException is thrown when errors occur. This class will contain an exception message, and may also contain a reference to an exception that caused the error.

Prerequisites

• JDK version 1.3 or later.
• JAXP compliant XML parser, such as Apache Xerces.
• WSDL for Java API (WSDL4J), which is available from the IBM developerWorks site.
• UDDI for Java API (UDDI4J), which is available at www.uddi4j.org.
  • Also need the support for a UDDI4J SOAP transport, such as Apache Axis.
• Ant is required to build WSIL4J. Ant is available at the Apache ANT website.

Configuration

WSIL4J uses a set of system parameters to configure certain functions. The wsil.properties file is located in the org.apache.wsil.util package.

Accessing Builds and Source Code

The source code for this package is available on the Apache web site. Individual files can be accessed using the web-based CVS interface. The entire package can be downloaded using the following instructions.

Accessing the Nightly Builds

This package is built nightly along with Axis. The build will create two zip files: wsil4j-bin.zip and wsil4j-src.zip. The first file contains a complete build image, which includes wsil4j.jar, Javadoc, and all source code. The second file contains just a copy of the source code, which could be built using Ant. Both of these files can be accessed at the same location as the Axis nightly builds.

Accessing the Source Tree (AnonCVS)

So, you've decided that you need access to the source tree to see the latest and greatest code. There's two different forms of CVS access. The first is anonymous and anybody can use it. The second is not and you must have a login to the development server. If you don't know what this means, join the mailing list and find out.

Anyone can checkout source code from our anonymous CVS server. To do so, simply use the following commands (if you are using a GUI CVS client, configure it appropriatly):

cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login password: anoncvs cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout xml-axis-wsil

Full Remote CVS Access

If you are a Committer and have a login on the Apache development server, this section is for you. If you are not a Committer, but you want to submit patches or even request commit privelages, please see the Jakarta GuideLines page (we follow the same rules) for more information.

To have full access to the CVS server, you need to follow the links depending on the operating system you are using:

• Unix
• Windows

Building WSIL4J

• Obtain ANT and the JDK as listed in the prerequisites.
• Set required environment variables, including, JAVA_HOME, ANT_HOME.
• From the root directory of WSIL4J (where build.xml is located), run

  ant -Dwsil4j.build.classpath=<classpath> <target>

  where <classpath> contains the location of the JAR files for the XML parser, WSDL4J and UDDI4J
  
  and, where <target> is one of the following:
  • compile: Compiles the API
  • samples: Compiles the samples
  • javadocs: Builds the javadoc
  • srcdist: Creates the source distribution zip file.
  • dist: Creates the binary distribution zip file.
  • clean: Removes built files.
  • all: Cleans, creates source and binary distribution zip files.

Using WSIL4J

To run a program referencing WSIL4J,

• Include wsil4j.jar, wsdl4j.jar, and uddi4j.jar in the classpath.
• Include the jar file(s) for the JAXP compliant XML parser in the classpath.

Samples

There are two sample applications that use WSIL4J. Both of these samples are located in the samples directory. This directory also contains a sample WS-Inspection document.

• WSInspectionExample.java
  This sample shows how to use some of the basic WSIL4J functions. This includes how to read a WS-Inspection document and how to access the WSDL service descriptions contained in this document.
  
  After building the WSDL4J package, you can run this sample from the samples directory by using this command syntax:
  
  java -cp .;../lib/wsil4j.jar;<parser.jar>;<wsdl4j.jar> WSInspectionExample <documentURL>
  
  where,
  <parser.jar> is the location of the XML parser JAR files
  <wsdl4j.jar> is the location of the WSDL4J JAR file
  <documentURL> is the location of the WS-Inspection document
  
  As an example, you can execute the following command from the samples directory:

java -cp <classpath> WSInspectionExample file:///<wsil4j_path>/wsil4j/samples/inspection.wsil StockQuoteService

  NOTE: This sample does not use an UDDI functions, so the UDDI4J JAR file is not required.
  
  
• WSInspectionProxyExample.java
  This sample program shows how to use the proxy interface. This interface provides a set of functions that will read a WS-Inspection document and locate specific information within the document. For example, you could use the proxy interface to locate just the service descriptions with a specific name.
  
  You can run this sample using the following command format:
  
  java -cp .;../lib/wsil4j.jar;<parser.jar>;<wsdl4j.jar>;<uddi4j.jar>;<uddi4j-transport.jar> WSInspectionProxyExample <documentURL> <serviceName>
  
  where,
  <parser.jar> is the location of the XML parser JAR file(s)
  <wsdl4j.jar> is the location of the WSDL4J JAR file
  <uddi4j.jar> is the location of the UDDI4J JAR file
  <uddi4j-transport.jar> is the location of the UDDI4J SOAP transport JAR file(s)
  <documentURL> is the location of the WS-Inspection document
  <serviceName> is the service name to search the document for
  
  As an example, you can execute the following command from the samples directory:

java -cp <classpath> WSInspectionProxyExample file:///<wsil4j_path>/wsil4j/samples/inspection.wsil StockQuoteService

Work To Be Done

The current WSIL4J implementation contains most of the basic support for the Web Services Inspection Language. Here is a list of future enhancements and usages for this package:

• Change the name of this package (from WSIL4J).
  
  
• Add support for obtaining the WS-Inspection document references from an META tags in an HTML document.
  
  
• Enhance the relative URL support. Currently, the WSILDocument class contains a resolveURL method that can be used to resolve a relative URL into a complete URL. The relative URL is resolved using the URL that was used to read the WS-Inspection document.
  
  
• Add support for detecting recursive references to WS-Inspection documents when processing <link> elements.
  
  
• Provide support for both UDDI V1 and UDDI V2 references in the same WS-Inspection document. Right now, this support is limited to the version supported by the version of UDDI4J that is being used.
  
  
• Add a WS-Inspection interface to Apache Axis. This interface would return a WS-Inspection document that contains the list of deployed services .

Reference

• Web Services Inspection Language Specification
• WS-Inspection Overview
• Javadoc for the WSIL4J API classes
  [Note: This link will work only after this package has been built.]