Implementing Verastream Web Services

Providing a web service to your host applications enables rapid reuse of the business logic that exists on these hosts. Web services become reusable objects for creating portals, web applications, and other business solutions. Web services provide a standard method of transferring data and XML formatted component descriptions. And, because Web Services 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 Java proxy objects and sample code for the services.

Web Builder generates the <ProjectName>.wsdl document in the <VHI install folder>\projects\<ProjectName>\wsdl folder. You can open this file in any editor.

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:

For a Java web service, enter: http://localhost:8081/axis/services/<ProjectName>?wsdl
For a .NET web service, enter: http://localhost/<ProjectName>/<ProjectName>.asmx?wsdl

As provider of a web service, you publish the WSDL document to give developers access to your web service. With the WSDL-generation URL, developers can use utilities to generate specific files to locate and consume the web service.

Implementing Java Web Services

Web Builder uses Apache Axis to create proxy objects, stub code, and data types. Axis is both a servlet that publishes web services and a set of .jar files that consume web services.

Java Web Service Client Files

These files are relevant to the functionality of a Verastream web service client and contain information that you can use to create your own web service client.

In the <VHI install folder>\projects\<ProjectName>\client folder, look for these files:

<ProjectName>Client.java
This is the generated main class of the web service client. This file contains an example of how to use a service locator to get a proxy bean and how to execute methods (procedures) on the proxy bean.
axis.jar, commons-logging.jar, jaxrpc.jar
These are the .jar files from Apache Axis that are used to run the web service client. (Redistribution of these files is governed by license agreement, which can be found in AxisLicense.txt.)
proxy folder files
These files provide the service locator, interface, and generated proxy objects for the web service.

Deploying Java Web Services

To deploy a Verastream Java web service into a production environment:

Install Apache Axis into the production servlet runner.
Copy the <ProjectName>.jar file into the <production web server>\axis\WEB-INF\lib folder.
Copy the deploy.wsdd file to the production server.
Integrate the Host Integrator .jar files into the web server. The web server must be able to
access the Host Integrator .jar files.
Restart the Axis server and, if the production environment and the development environment are on different computers, run these commands:
java -CLASSPATH <root>\VHI\tomcat\webapps\axis\WEB-INF\lib java org.apache.axis.client.AdminClient deploy.wsdd

You can use these optional switches, inserted before the deploy.wsdd string:

-h<hostname> Specifies the host name. Example: -hlocalhost

-p<portnumber> Specifies the port number. Example: -p8081

Implementing .NET Web Services

In Visual Studio .NET, add the Verastream web service to your .NET project as a web reference:

Use the Add Web Reference utility to import the Verastream web definition: http://localhost/<ProjectName>/<ProjectName>.asmx?wsdl
In the Solution Explorer, open the Web References node on the tree to access the Verastream web service.

.NET Web Service Files

These files are relevant to the functionality of a Verastream web service client and contain information that you can use to create your own web service client.

In the <VHI install folder>\projects\<ProjectName> folder, look for these files:

\solution\<ProjectName>.sln
Microsoft Visual Studio solution file.
\wsdl\<ProjectName>.wsdl
Verastream WSDL document that describe the operations the service supports, as well as the parameters each operations accepts and returns.

In \Inetpub\wwwroot\<ProjectName> look for these files:

<ProjectName>.asmx files
.NET web service files
\bin
Dynamic Link Library (DLL) files

Deploying .NET Web Services

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

Copy the <ProjectName> folder from the local Inetpub\wwwroot folder to the same location on the production server.
Create the Verastream web service as an application using Internet Services Manager.

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.

-h<hostname>	Specifies the host name. Example: -hlocalhost
-p<portnumber>	Specifies the port number. Example: -p8081