Web Services Client Overview

Web services typically use a SOAP over HTTP protocol. In this scenario, SOAP envelopes are sent out. When collections and other complex objects are bundled in SOAP envelopes, the ASCII data structures can become difficult to read and edit. Novice developers should not try to build web services clients by direct manipulation of SOAP envelopes. Experienced developers typically do not build web services clients at the SOAP envelope level. Doing so is tedious and error prone. For this reason, all major programming languages provide web services development kits. In Silk Central, the Java API for XML Web Services (JAX-WS) is used for building web services and clients that communicate using SOAP messages.

Regardless of the implementation language (Java, C++, C#, Perl, or Python), building web service clients generally follows the same pattern:

Point a development kit tool to the web services WSDL.
Get a client stub returned.
Edit the client stub generated in step 2 to obtain a full-blown client.

JAX-WS follows this pattern. Here, the wsimport tool (bundled with the JDK) is used to build the client stubs from the WSDL. Detailed information on how to use wsimport can be found in the JDK Tools and Utilities documentation. A brief description of the switches used in the above summary is as follows:

-s: The output directory of the client stubs
-p: The target package. Deploy to this package structure

Example: wsimport -s <location of generated stubs> -p <target package> <WSDL>

The wsimport tool generates several classes to support a client to the web service. If YourWebService is the name of the service, then one can expect the following classes to be output:

YourWebService: An interface representing YourWebService.
YourWebServiceService: A generated class representing the YourWebService Locator, for example to get a list of available ports (service endpoint interfaces)
WSFaultException: An exception class mapped from wsdl:fault
WsFaultBean: Asynchronous response bean derived from response wsdl:message
Serializeable Objects: Client-side objects corresponding to the objects YourWebService uses.

To generate a JAX-WS client for accessing Silk Central web services, create a new a Java class called YourWebServiceClient. You have to bind to the web service through a port; a port is a local object that acts as a proxy for the remote service. Note that the port is created by executing the wsimport tool in the step above. To retrieve this proxy, invoke the getRequirementsServicePort method on the service:

// Bind to the Requirements service
  RequirementsServiceService port = new RequirementsServiceService
    (new URL("http", mHost, mPort, "/Services1.0/jaxws/requirements?wsdl"));
  RequirementsService requirementsService = port.getRequirementsServicePort();

To authenticate with the web services, generate a web-service token in the User Settings page of the Silk Central UI. To access this page, hover the mouse cursor over the user name in the Silk Central menu and select User Settings.

You can also invoke the service's logonUser method by passing username and password to obtain a session ID:

// Login to Silk Central and get session ID
  String sessionId = requirementsService.logonUser(mUsername, mPassword);