Using WS-I Web Services

Providing a Web service to your host applications enables rapid reuse of the business logic that exists on these hosts. Web services provide reusable APIs for creating portals, Web applications, and other business solutions. And, because they are technology independent, they can run on any platform.

Using the WSDL Document

The Web Service Description Language (WSDL) document describes the interface to the Web service, the data types it uses, and the location of the service. Developers use this document to identify inputs, outputs, and methods needed to consume the Web service. Web services generation utilities use the WSDL document to create proxy objects and sample code for the services.

To view a WSDL document in a browser, enter the service’s URL and append ?wsdl. For example, to access the WSDL document generated by Web Builder:

To give developers access to your Web service, you must publish the WSDL location. With the WSDL-generation URL, developers can use utilities to generate specific files to locate and consume the Web service.

Web Builder saves a copy of the WSDL to disk when a service is first deployed. This file, located in <VHI install folder>\projects\<ProjectName>\wsdl, is for reference only. It is a copy of the deployed WSDL and is not used.

Using Java Web Services

Web Builder uses Apache Axis version 1.2.1 to create Java Web services. Axis is an open-source XML-based Web services framework.

Deploying Java Web Services

When you generate a Java Web service, Web Builder automatically deploys the service to the local test server (Verastream Host Integrator Web Server).

To deploy one of these services into a production environment:


NOTE:  Steps 1 and 2 only need to be completed once per production server.
  1. Install Apache Axis v1.2.1 into the production application server. The Apache Axis documentation is available on their Web site.

    —or—

    You can use the Verastream Host Integrator Web Server as your application server. See Tech Note 10067.

  2. Configure the application server. The following jar files must be added to your application server's CLASSPATH:

    You should consult the documentation for your application server. It may be necessary to restart the server after these changes have been made.

  3. On the Web Builder computer, locate <VHI install folder>projects><ProjectName>\webservice and copy <ProjectName>.jar and deploy.wsdd to <appserver>\<webappsdir>\axis\WEB-INF\lib on the production server.

  4. Restart your application server.

  5. Use the Axis AdminClient to register the service with Axis. Run the command in the same directory that contains the deploy.wsdd file.

    A sample deployment batch file might look like this:

    <form name="sample_deploy">
    <textarea rows="20" cols="80" readonly="readonly">
    
    set AXISWEBAPPLIB=C:\Progra~1\VHI\tomcat\webapps\axis\WEB-INF\lib
    set  AXISADMINLIB=C:\Progra~1\VHI\tomcat\server\webapps\admin\WEB-INF\lib
    set AXISSERVERLIB=C:\Progra~1\VHI\tomcat\server\lib
    
    set AXISCLASSPATH=%AXISWEBAPPLIB%\activation.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISWEBAPPLIB%\axis.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISWEBAPPLIB%\axis-ant.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISWEBAPPLIB%\commons-discovery-0.2.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISWEBAPPLIB%\commons-discovery.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISWEBAPPLIB%\commons-logging-1.0.4.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISWEBAPPLIB%\commons-logging.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISWEBAPPLIB%\jaxrpc.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISWEBAPPLIB%\log4j-1.2.8.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISWEBAPPLIB%\mail.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISWEBAPPLIB%\saaj.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISWEBAPPLIB%\wsdl4j-1.5.1.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISWEBAPPLIB%\wsdl4j.jar
    
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISADMINLIB%\catalina-admin.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISADMINLIB%\struts.jar
    
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISSERVERLIB%\catalina.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISSERVERLIB%\servlets-common.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISSERVERLIB%\servlets-default.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISSERVERLIB%\servlets-invoker.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISSERVERLIB%\servlets-webdav.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISSERVERLIB%\tomcat-coyote.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISSERVERLIB%\tomcat-http11.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISSERVERLIB%\tomcat-jk2.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISSERVERLIB%\tomcat-jk.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISSERVERLIB%\tomcat-jni.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%AXISSERVERLIB%\tomcat-util.jar
    
    java -cp %AXISCLASSPATH% org.apache.axis.client.AdminClient -lhttp://localhost:8081/axis/services/AdminService deploy.wsdd
    </textarea>
    </form>
    

    You can specify a port number (other than the default 8080) with the -p<port> argument after org.apache.axis.client.AdminClient.

  6. To verify that the service is deployed, view the list of Axis services in your Web browser. This URL typically has the form, http://<host>:<port>/axis/servlet/AxisServlet.

Java Web Service Client Files

Web Builder also generates a command-line Java application that can be used to test the Web service- on the development machine, and may also be used as the basis for a fully functional Web service client.

The client application can be found on the Web Builder machine in the <VHI install folder>\ projects\<ProjectName>\client folder. See Readme.txt in the client folder for more information.

Using .NET Web Services

Web Builder uses the .NET Framework version 2.0 to create .NET Web services. It also generates a solution file for Visual Studio 2005, but Visual Studio is not required.

Deploying .NET Web Services

When you generate a .NET Web service, Web Builder automatically deploys the service to the local IIS server.

To deploy a Verastream .NET Web service into a production environment:

  1. Copy the <ProjectName> folder from the local Inetpub\wwwroot folder to the same location on the production server.

  2. Create the Verastream Web service as an application using Internet Services Manager.

  3. To verify that the service is deployed, view the service summary at http://localhost/<ProjectName>/<ProjectName>.asmx.

Alternatively:

  1. Using Visual Studio 2005, open the solution in <VHI install folder>\projects\<ProjectName>\solution.

  2. Using Visual Studio, publish the service to the production server.

  3. To verify that the service is deployed, view the service summary at http://localhost/<ProjectName>/<ProjectName>.asmx.

Testing .NET Web Services

.NET Web services have some limited built-in testing abilities. In a Web browser, you can view the service summary at http://localhost/<ProjectName>/<ProjectName>.asmx. The available operations are listed at the top of the page. When you click an operation, an HTML form displays that you can use to interact with the service.

Using .NET Web Services In Visual Studio

Using .NET Web services in Visual studio is very easy. Simply add the Verastream Web service to your .NET project as a Web reference:

  1. Use the Add Web Reference utility to import the Verastream Web definition: http://localhost/<ProjectName>/<ProjectName>.asmx?wsdl.

  2. In the Solution Explorer, open the Web References node on the tree to access the Verastream Web service.

Extended Error Information

Using the standard Java and .NET connectors, a Java error is returned as an ApptrieveException and a .NET error is returned as a HostIntegratorException. However, a web service error is sent as a Soap Fault. The error message list must be extracted from the details element of the Soap Fault. Verastream Host Integrator puts both the message list and a stack trace in the Soap Fault details.

This is an example of the contents of the Soap Fault details:

<messageList>
<message>User-defined error detected: No account exists with the specified account number.</message>
<message>Procedure GetAccount on table Accounts failed.</message>
<message>Caught VHI Exception in PerformTableProcedure(Accounts, GetAccount, )</message>
</messageList>

<stackTrace> at WRQ.Verastream.HostIntegrator.Utils.HandleCOMException(AppConnRejuvenationSessions, COMException ce)
at WRQ.Verastream.HostIntegrator.HostIntegratorSession.PerformTableProcedure(String tableName, String procedureName, IDictionary inputValues, IDictionary filterValues, Boolean filterIsCaseSensitive, IList outputColumnNames, Int32 maxRows)
at WRQ.Verastream.HostIntegrator.HostIntegratorSession.PerformTableProcedure(String tableName, String procedureName, IDictionary filterValues, Boolean filterIsCaseSensitive, IList outputColumnNames, Int32 maxRows)
at CICSAccts2.CICSAccts2Service.GetAccount(Int32 AcctNum)
</stackTrace>

In order to extract this information on the client side, using .NET, catch a System.Web.Services.Protocols.SoapException and access the Details field. If Apache Axis is used to consume the Java Web service, catch an org.apache.axis.AxisFault and call getFaultDetails() on it. The generated client for Java contains an example of how to use the AxisFault class.

 

 

 

  Attachmate