Web Services Client Examples

Service Desk Web Services API is based on The Apache Axis2 project which is a Java-based implementation of both the client and server sides of the Web services equation. Axis is essentially a SOAP engine -- a framework for constructing SOAP processors such as clients, servers, and so on.

The following samples demonstrate the structure for developing client code to consume Service Desk Web Services.

This section contains the following topics:

Setting up the Environment

Download the binary version of Apache Axis2 and extract the binary version (axis2-1.5.1-bin.zip). After extracting the file into E:Axis2Client (assuming your client directory), you will get a directory "E:Axis2Clientaxis2-1.5.1-binaxis2-1.5.1". This directory contains the binary version of the Apache Axis2 engine. Now, set the environment variables by invoking following code from a command line:

@set AXIS2&#95;HOME=D:\ java-tools\ axis2-1.5.1

Generating the Axis2 Client Code Using the wsdl2java Tool

A Web Services Description Language (WSDL) file describes a Web service. The Java API for XML-based Remote Procedure Call (JAX-RPC) 1.1 specification defines a Java API mapping that interacts with the Web service.

The Web Services for Java 2 Platform, Enterprise Edition (J2EE) 1.1 specification defines deployment descriptors that deploy a Web service in a J2EE environment. The WSDL2Java command is run against the WSDL file to create Java APIs and deployment descriptor templates according to these specifications.

The command-line syntax is:

WSDL2Java &#91;arguments&#93; WSDL-URI

From a command line generate the client code for ServiceRequest web service by issuing the following command:

%AXIS2&#95;HOME%\ bin\ WSDL2Java -url  http://nsd-preview.nimsoftondemand.com/webservices/ServiceRequest?wsdl -o com/infradeskonline/genclient

Where,

The "-url" is either the path where you have saved a copy of the wsdl to either ".wsdl" or ".xml", or the URL the WSDL resides at.
The "-o" is the path where you want the files to be written out to. If not specified, the files are written out to the current bin location.
The above command generates "ServiceRequestStub.java" and "ServiceRequestCallbackHandler.java" into "com/infradeskonline/genclient" directory.

Typical API Call Sequence

For each call, your client application typically performs the following tasks:

Prepares the request by defining request parameters, if applicable.
Invokes the call, which passes the request with its parameters to the Service Desk Web Service for processing.
Receives the response from the API.
Handles the response, either by processing the returned data (for a successful invocation) or by handling the error (for a failed invocation).

get Call Client Example

The following is an example of an Axis Client program that calls the getServiceRequest operation to query an excerpt of the primary details (general information) pertaining to the service request identified by the specified ticket identifier, in XML output format.

public class ServiceRequestClient
{    


public void main (

String &#91;&#93; args)
   { 


try
      { 
         // Create the request
         ServiceRequestStub                        srqStub         = 

new ServiceRequestStub();
         ServiceRequestStub.Credentials            credentials     = 

new ServiceRequestStub.Credentials();
         ServiceRequestStub.ExtendedSettings       extParams       = 

new ServiceRequestStub.ExtendedSettings();

         // Initialize Credentials (User Name & User Password / Authorization Token & Slice Token)
         credentials.setUserName (

"wsuser");
         credentials.setUserPassword (

"wsuser");

         // Initialize Extended Settings such as Response Format (XML, JSON)
         extParams.setResponseFormat (

"XML");

         // Invoke the GET service
         ServiceRequestStub.DefaultServiceResponse serviceResponse = srqStub.getServiceRequest (credentials, extParams, ticketIdentifier);

         // Inspect successful execution of service and retrieve the response text


if (serviceResponse.getResponseStatus ().equals (

"OK"))
         { 


System.out.println(

"XML Response : " + serviceResponse.getResponseText ());  
         } 
         // Retrieve the status code, status message and error messages, in 

case of failures


else
         { 


System.out.println(

"Status Code : " + serviceResponse.getStatusCode ());


System.out.println(

"Status Message : " + serviceResponse.getStatusMessage ());


System.out.println(

"Errors : " + Arrays.asList (serviceResponse.getErrors ()).toString ());
         } 
      } 


catch (Exception e) 
      { 


System.out.println (

"Exception: " + e.getMessage());
                } 
   } 
}

list Call Client Example

The following is an example of an Axis Client program that calls the listServiceRequest operation to query return the list of all open service requests for the logged in user and his groups matching the specified search criteria, in JSON output format.

public class ServiceRequestClient
{    


public void main (

String &#91;&#93; args)
   { 


try
      { 
         // Create the request
         ServiceRequestStub                        srqStub         = 

new ServiceRequestStub();
         ServiceRequestStub.Credentials            credentials     = 

new ServiceRequestStub.Credentials();
         ServiceRequestStub.ExtendedSettings       extParams       = 

new ServiceRequestStub.ExtendedSettings();

         // Initialize Credentials (User Name & User Password / Authorization Token & Slice Token)
         credentials.setUserName (

"wsuser");
         credentials.setUserPassword (

"wsuser");

         // Initialize Extended Settings such as Response Format (XML, JSON)
         extParams.setResponseFormat (

"JSON");

         // Invoke the LIST service
         ServiceRequestStub.DefaultServiceResponse serviceResponse = srqStub.listServiceRequest (credentials, extParams, ticketIdentifier);

         // Inspect successful execution of service and retrieve the response text


if (serviceResponse.getResponseStatus ().equals (

"OK"))
         { 


System.out.println(

"JSON Response : " + serviceResponse.getResponseText ());  
         } 
         // Retrieve the status code, status message and error messages, in 

case of failures


else
         { 


System.out.println(

"Status Code : " + serviceResponse.getStatusCode ());


System.out.println(

"Status Message : " + serviceResponse.getStatusMessage ());


System.out.println(

"Errors : " + Arrays.asList (serviceResponse.getErrors ()).toString ());
         } 
      } 


catch (Exception e) 
      { 


System.out.println (

"Exception: " + e.getMessage());
      } 
   } 
}

insert Call Client Example

The following is an example of an Axis Client program that calls the listServiceRequest operation to create/log a new service request ticket with the provided details.

public class ServiceRequestClient
{    


public void main (

String &#91;&#93; args)
   { 


try
      { 
         // Create the request
         ServiceRequestStub                        srqStub     = 

new ServiceRequestStub();
         ServiceRequestStub.Credentials            credentials = 

new ServiceRequestStub.Credentials();
         ServiceRequestStub.ExtendedSettings       extParams   = 

new ServiceRequestStub.ExtendedSettings();
         ServiceRequestStub.ServiceRequest         srqBean     = 

new ServiceRequestStub.ServiceRequest();

         // Initialize Credentials (User Name & User Password / Authorization Token & Slice Token)
         credentials.setUserName (

"wsuser");
         credentials.setUserPassword (

"wsuser");

         // Initialize Extended Settings such as Response Format (XML, JSON)
         extParams.setResponseFormat (

"JSON");

         // Initialize Service Request Bean with neccessary details
         srqBean.setRequester&#95;name (

"Admin, InteQ");
         srqBean.setTicket&#95;description (

"Ticket creation via webservice# " + 

new Date());

         // Invoke the INSERT service
         ServiceRequestStub.DefaultServiceResponse serviceResponse = srqStub.logServiceRequest (credentials, extParams, srqBean);

         // Inspect successful execution of service and retrieve the response text


if (serviceResponse.getResponseStatus ().equals (

"OK"))
         { 


System.out.println(

"JSON Response : " + serviceResponse.getResponseText ());  
         } 
         // Retrieve the status code, status message and error messages, in 

case of failures


else
         { 


System.out.println(

"Status Code : " + serviceResponse.getStatusCode ());


System.out.println(

"Status Message : " + serviceResponse.getStatusMessage ());


System.out.println(

"Errors : " + Arrays.asList (serviceResponse.getErrors ()).toString ());
         } 
      } 


catch (Exception e) 
      { 


System.out.println (

"Exception: " + e.getMessage());
      } 
   } 
}

update Call Client Example

The following is an example of an Axis Client program that calls the listServiceRequest operation to update an existing service request ticket that is identified by row_id "123" with the provided details.

public class ServiceRequestClient
{    


public void main (

String &#91;&#93; args)
   { 


try
      { 
         // Create the request
         ServiceRequestStub                        srqStub     = 

new ServiceRequestStub();
         ServiceRequestStub.Credentials            credentials = 

new ServiceRequestStub.Credentials();
         ServiceRequestStub.ExtendedSettings       extParams   = 

new ServiceRequestStub.ExtendedSettings();
         ServiceRequestStub.ServiceRequest         srqBean     = 

new ServiceRequestStub.ServiceRequest();

         // Initialize Credentials (User Name & User Password / Authorization Token & Slice Token)
         credentials.setUserName (

"wsuser");
         credentials.setUserPassword (

"wsuser");

         // Initialize Extended Settings such as Response Format (XML, JSON)
         extParams.setResponseFormat (

"JSON");

         // Initialize Service Request Bean with neccessary details
         srqBean.setRow&#95;id (123);
         srqBean.setTicket&#95;description (

"Updated - Ticket creation via webservice# " + 

new Date());

         // Invoke the UPDATE service
         ServiceRequestStub.DefaultServiceResponse serviceResponse = srqStub.logServiceRequest (credentials, extParams, srqBean);

         // Inspect successful execution of service and retrieve the response text


if (serviceResponse.getResponseStatus ().equals (

"OK"))
         { 


System.out.println(

"JSON Response : " + serviceResponse.getResponseText ());  
         } 
         // Retrieve the status code, status message and error messages, in 

case of failures


else
         { 


System.out.println(

"Status Code : " + serviceResponse.getStatusCode ());


System.out.println(

"Status Message : " + serviceResponse.getStatusMessage ());


System.out.println(

"Errors : " + Arrays.asList (serviceResponse.getErrors ()).toString ());
         } 
      } 


catch (Exception e) 
      { 


System.out.println (

"Exception: " + e.getMessage());
      } 
   } 
}

delete Call Client Example

The following is an example of an Axis Client program that calls the deleteAttachment operation and deletes the attachment document entry from the database that is identified by the Row Id# 12.

public class AttachmentClient
{    


public void main (

String &#91;&#93; args)
   { 


try
      { 
         // Create the request
         AttachmentStub                  attachmentStub = 

new AttachmentStub();
         AttachmentStub.Credentials      credentials    = 

new AttachmentStub.Credentials();
         AttachmentStub.ExtendedSettings extParams      = 

new AttachmentStub.ExtendedSettings();

         // Initialize Credentials (User Name & User Password / Authorization Token & Slice Token)
         credentials.setUserName (

"wsuser");
         credentials.setUserPassword (

"wsuser");

         // Initialize Extended Settings such as Response Format (XML, JSON)
         extParams.setResponseFormat (

"JSON");

         // Invoke the DELETE service
         AttachmentStub.DefaultServiceResponse serviceResponse = attachmentStub.deleteAttachment (credentials, extParams, 

"12");

         // Inspect successful execution of service and retrieve the response text


if (serviceResponse.getResponseStatus ().equals (

"OK"))
         { 


System.out.println(

"JSON Response : " + serviceResponse.getResponseText ());  
         } 
         // Retrieve the status code, status message and error messages, in 

case of failures


else
         { 


System.out.println(

"Status Code : " + serviceResponse.getStatusCode ());


System.out.println(

"Status Message : " + serviceResponse.getStatusMessage ());


System.out.println(

"Errors : " + Arrays.asList (serviceResponse.getErrors ()).toString ());
         } 
      } 


catch (Exception e) 
      { 


System.out.println (

"Exception: " + e.getMessage());
      } 
   } 
}