How to Create VBI Web Services

This is a brief overview of the VBI Web Services, with a focus on how to create clients for Java and .NET. Web services being what they are, you are not limited to Java and .NET; any modern language will have tools for creating Web service clients.

Getting Started

The VBI Web Service is described by a WSDL (Web Services Description Language) document. A good portion of the WSDL defines reusable data types, messages, and port types in the form of XML Schema. The interesting part of the WSDL is the definition of the operations that define the service. Each operation can have inputs and outputs that are defined as request types and response types, respectively. The WSDL is complete enough that tools can generate code that will interact with the Web service.

Where to get the WSDL

When you use VBI's Transaction Studio to access host transactions, the project generated is JAX-WS compliant. Verastream Process Designer R5n SP1 contains a Web services container that exposes any JAX-WS standard Java Web service. You can simply create a VBI project, drop your generated VBI JAR file (project_name.jar) along with the BridgeAPI.jar into the Process Designer Web services container, <install location>/ProcessServer/services/wscontainer/lib, and restart the Process Server.

You can then use the Web service's WSDL to generate Web service Java or .NET clients. To access the required WSDL you would enter a URL like this: http://vpdserver:9999/<project_name>Service?wsdl

Generating Java Code from the WSDL

To create Java code from a WSDL, you need to use JAX-WS (Java API for XML Web Services). The Reference Implementation of the JAX-WS (JAX-WS RI) is developed as part of an open source project called GlassFish. At the time of this writing, 2.1.4 was available for download here:

The download is an executable JAR file that extracts the JAX-WS RI binaries, documentation, and samples to a directory named jaxws-ri. In the bin subdirectory, is the wsimport tool, which generates Java portable artifacts from the WSDL.

The JAX-WS RI is now part of Java SE 6, but GlassFish includes additional documentation that you might find useful. The GlassFish installation also includes support for running wsimport as an Ant task. At this writing, 2.1 JAX-WS tool documentation can be found here: Generate code by running the wsimport tool: wsimport WebSvcBridgeAPI.wsdl

Generating .NET Code from the WSDL

The example code shown in this chapter was written and tested with .NET Framework 2.0. At the time of this writing, version 3.0 and 3.5 have been released. In these releases, there are improvements to Web services development that have not been explored in this document.

Generation of Web services code is done automatically by Visual Studio when you add a Web reference to your project. However, you can use WSDL.exe to generate code explicitly. In Visual Studio, when you import a Web reference, you may not see the newly generated code, by default. You must click Show All Files in the Solution Explorer and expand the Web reference to see the datasource files and Reference.cs. However, typically you won't need access to these files.