VisiBroker for C++ Developer’s Guide : Web Services Overview

Web Services Overview
A Web Service is an application component that you can describe, publish, locate, and invoke over a network using standardized XML messaging. Defined by new technologies like SOAP, Web Services Description Language (WSDL), and Universal Discovery, Description and Integration (UDDI), this is a new model for creating e-business applications from reusable software modules that are accessed on the World Wide Web and also providing a means for integration of older disparate applications.
Web Services Architecture
The standard Web Service architecture consists of the three roles that perform the web services publish, find, and bind operations:
The Service Provider registers all available web services with the Service Broker
The Service Broker publishes the web services for the Service Requestor to access. The information published describes the web service and its location. Apart from publishing the web service, it also co-ordinates in hosting the web service.
The Service Requestor interacts with the Service Broker to find the web services. The Service Requestor can then bind or invoke the web services.
The Service Provider hosts the web service and makes it available to clients via the Web. The Service Provider publishes the web service definition and binding information to the Universal Description, Discovery, and Integration (UDDI) registry. The Web Service Description Language (WSDL) documents contain the information about the web service, including its incoming message and returning response messages.
The Service Requestor is a client program that consumes the web service. The Service Requestor finds web services by using UDDI or through other means, such as email. It then binds or invokes the web service.
The Service Broker manages the interaction between the Service Provider and Service Requestor. The Service Broker makes available all service definitions and binding information. Currently, SOAP (an XML-based, messaging and encoding protocol format for exchange of information in a decentralized, distributed environment) is the standard for communication between the Service Requestor and Service Broker.
Figure 40
VisiBroker Web Services Architecture
There are two aspects to the architecture:
The first aspect is achieved by using a Web Service development tool that converts an IDL interface to a WSDL document using the standard as specified by OMG’s CORBA to WSDL/SOAP Inter-working specification. Service Requestors or Web Services clients to make invocations can use the generated WSDL using SOAP over HTTP/HTTPS as transport.
To provide a Web services runtime, VisiBroker uses Apache Axis technology to handle the intricacies of a Services Broker. Using a proprietary type-specific bridge (generated by the tool), deployed stateless CORBA objects can be made accessible. The type-specific bridge instances act as the Service Providers bringing forward the functionality of the CORBA object back end to the Service Requestors.
Web Services Artifacts
The figure below explains the Web Services development tool provided with VisiBroker that generates the WSDL document and the Bridge code from an IDL file. The WSDL document is useful for the Services Requesters and along with the service description; it also provides the SOAP binding information, which allows any SOAP compliant client to make invocation.
The generated bridge artifact is actually a language/type-specific service provider component that gets deployed in the Service Broker (Axis runtime) and an instance of this is responsible for adapting the incoming SOAP message from the Service Requester to a bound CORBA object.
Figure 41
Web Service Runtime
To explain the runtime behavior, the figure below shows a SOAP client making use of the generated WSDL to make SOAP/HTTP or SOAP/HTTPS invocations on three CORBA objects exposed as Web Services in VisiBroker for C++, VisiBroker for Java, and a pre 7.0 VisiBroker process.
VisiBroker process comes with the infrastructure for a HTTP/SOAP listener (internally Apache Axis Technlogy), which is by default turned off. By setting the command line property vbroker.ws.enable=true, this runtime infrastructure can be started. Once the infrastructure is started, the Service providers (bridge) for the CORBA objects can be deployed using Axis’s WSDD mechanism. Using few VisiBroker proprietary CORBA object binding related WSDD elements, the deployed bridge instances can be bound to CORBA objects and any SOAP invocations on the bridge is adapted to an in-process CORBA invocation. The bridge in reality is a morph of the Axis’s server side generated code, with each web service implementation skeleton mapped to a method on a type specific CORBA object stub. Because the bridge is generated directly from IDL, all the type-safety and fidelity of IDL types is inherently built in. Also, because the bridge is loaded in the same process as the CORBA objects, all invocation on the CORBA object from the bridge is optimized because of VisiBroker’s “inprocess” bidder.
In the figure the cloud “Ax” depicts the Axis + HTTP listener component loaded into the VisiBroker process. “Ob” cloud depicts a CORBA object inside the ORB. The association between the “Ax” and “Ob” cloud as shown by the two small circles between them indicates the deployment of a bridge on the Axis runtime exposing the CORBA object to Service Requesters. Existing CORBA clients can continue making GIOP over IIOP invocations through the GIOP/IIOP listener as usual without any impact.
Figure 42
To support exposing CORBA objects in Pre 7.0 VisiBroker deployments, the bridge can be deployed on an Axis instance running externally to the VisiBroker process. The only difference in this case is that that SOAP to GIOP adaptation will be remote and hence will be over the wire. In the above figure, this is shown by deploying the bridge on Axis for Java embedded in Apache Tomcat. The cloud “Ob” indicates the CORBA object instance running on a remote Pre 7 VisiBroker Process and the request from the bridge comes in through the GIOP/IIOP end point.
The figure below explains the components inside a VisiBroker process. The “Axis runtime” cloud contains the Axis runtime, the HTTP listener along with the SOAP request dispatcher. A CORBA object inside the process is exposed as a Web Service by deploying its Service provider or the bridge as a Web Service using the Axis WSDD mechanism. When a SOAP client makes an invocation on the Web Service, the HTTP listener picks up the SOAP request and the request is passed to the dispatcher. The dispatcher invokes on the Axis runtime passing in the SOAP request. The Axis runtime decodes the SOAP request and makes invocation on an instance of the deployed Service provider (bridge). The bridge then makes use of the binding information provided in the WSDD to bind to the actual CORBA object and make the CORBA invocation.
Figure 43
In the above context, the Service Broker includes only a SOAP node on a HTTP transport. Other services needed for a Web Services deployment such as a UDDI service etc are not provided. Various implementations of these are available and can easily be used.
Exposing a CORBA object as Web Service
To expose a CORBA object as a Web Service in VisiBroker for C++, the following steps need to be performed.
Development:
1
2
3
Deployment:
This section illustrates an example provided in the "vbroker/ws/bank" sub directory of examples directory. This example is an adaptation of the "vbroker/basic/bank_agent" example and consists of two interfaces Account and AccountManager. The AccountManager allows for creation of new named accounts. If an account for a particular name already exists, the account is retrieved without creating a new account. Account interface allows for querying of balance in the account. The Server sets up a POA under the root POA and activates an object implementing the AccountManager interface. On making the open operation on this object, separate objects implementing Account interface are created, stored and returned. The code sample shown below illustrates the two interfaces.
// Bank.idl
module Bank {interface Account {    float balance();
  };
  interface AccountManager {    Account open(in string name);
  };
};
In this example, it will be shown how this stateful application can be enhanced to support SOA using Web Services. As a first step in the development, the stateful operations need to be converted to a coarser grained abstraction suitable for SOA. The interface shown below is one such example. This interface as shown, supports a single operation that opens a named account if the account does not already exist and returns the balance in the account.
// BankWebService.idl
module BankWebService {
  interface AccountManagerWebService {
 
    // opens account if not already opened, and returns balance
    float openAndQueryBalance(in string name);
  };
};
A CORBA object is then implemented which implements this interface, which internally uses the Account and AccountManager interfaces and activated on a known POA with a well known object ID.
Once the server has been enhanced to for stateless operations, web service support can be implemented as illustrated in the following sections.
Development
Generating WSDL from IDL
The idl2wsc compiler (idl2wsc.exe on Windows) generates WSDL document for the IDL file according to OMG’s CORBA to WSDL/SOAP Inter-working specification. Running the compiler as below for the BankWebService.idl generates a WSDL document named BankWebService.wsdl. This WSDL document can then be published through external means to potential Web Service clients or Client development teams.
prompt> idl2wsc BankWebService.idl
Generating the C++ interface type specific bridge
Using the idl2wsc compiler with –gen_cpp_bridge option, the C++ Bridge for a particular interface type can also be generated. The following command will generate the bridge code in file named BankWebService_ws_s.cpp and BankWebService_ws_s.hh. This code is opaque to the applications and should not be changed.
prompt> idl2wsc –src_suffix cpp –gen_cpp_bridge BankWebService.idl
Please note that the above two commands can be combined.
The generated C++ Bridge needs to be then packaged as a shared library linked in with the stub code of BankWebService.idl to be deployed as a Web Service.
For a complete list of the options available, see “idl2wsc”.
Deployment
Creating the deployment WSDD
The first step to deploy is to edit the Axis WSDD document for the bridge or the service provider. WSDD or Web Service Deployment Descriptor is a standard Axis means to instruct on deployment related information. A template WSDD for the bridge is created during the bridge creation. A sample WSDD is shown below which aims to deploy a Web Service hosted in a CORBA object with object id "BankManagerWebService" in a poa with name "bank_agent_poa". The object reference to this object is bound using osagent.
<deployment xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:CPP="http://xml.apache.org/axis/wsdd/providers/CPP">
<service
name="BankWebService.AccountManagerWebServiceService"
provider="CPP:RPC"
description="VisiBroker C++ web service">
<parameter
name="className"
value="[PATH]/libbridge.so"/>
<parameter
name="allowedMethods"
value="openAndQueryBalance"/>
<parameter
name="objectName"
value="BankManagerWebService"/>
<parameter
name="locateUsing"
value="osagent"/>
<parameter name="poaName" value="/bank_agent_poa"/>
</service>
</deployment>
Using the created WSDD to deploy
During initialization, Axis C++ reads a configuration file named axiscpp.conf, which is located in $AXISCPP_DEPLOY/etc on Unix or %AXISCPP_DEPLOY% on Windows, to let the user specify preferences such as parser library to be used and the location of deployment descriptor file.
In the configuration file, WSDDFilePath has to be defined so that Axis knows where to find the WSDD and what services are deployed. XMLParser is only required when the user wants to use a different parser from which is shipped with VisiBroker. VisiBroker WSRT has its own transport implementation, so the settings for transport and the channel are not used.
A sample axiscpp.conf file
# The comment character is '#'
#
# WSDDFilePath: The path to the WSDD
# XMLParser: Axis XML parser library
 
WSDDFilePath: /usr/local/VisiBroker/etc/server.wsdd
There are two ways to deploy a service:
Note
Because AdminClient depends on the Axis C++ client side libraries, which are not shipped with VisiBroker for C++, to use the tool; one has to get the tool and the required libraries from Apache Axis. (AdminClient is not available in Axis C++ 1.5)
Web Services Runtime Configuration
Create a property file server.prop to set up the Web Service runtime. Following is a sample property file. The following properties configure the Service Broker to start up a HTTP server on host 143.186.141.54 at port 19000. The connection manager is set up to allow maximum of 30 concurrent connections with 300 seconds to mark the connection idle time. The thread pool to service the incoming SOAP request is setup to have maximum of 300 threads with thread idle time set to 300 seconds. For a complete list of configurable properties, see “Web Services Runtime Properties”.
vbroker.ws.enable=true
vbroker.ws.listener.host=143.186.141.54
vbroker.ws.listener.port=19000
vbroke.ws.keepAliveConnection=true
vbroker.ws.connectionMax=30
vbroker.ws.connectionMaxIdle=300
vbroker.ws.dispatcher.threadMin=0
vbroker.ws.dispatcher.threadMax=300
vbroker.ws.dispatcher.threadMaxIdle=300
Run the Server as follows:
prompt> Server –ORBpropStorage server.prop
WSDD Reference
You may go to http://www.oio.de/axis-wsdd/ for the details of the WSDD.
The parameters used by VisiBroker include:
osagent: The object is assumed to be in osagent. The bind() method is used to locate the object. If poaName is also specified, objectName is located under that POA. This is the default value of the parameter.
nameservice: The object is assumed to be in Naming Service. The resolve() method on the root context is used to locate the object. The objectName must be the full name of the object starting from root context.
ior: The objectName provided is assumed to be an IOR. The string_to_object() method on the ORB is used to obtain the object. The IOR can be in standard form. For example:
corbaname::xxx
IOR:xxx
corbaloc::xxx
A sample of the service element in WSDD:
<service
   name="AServiceBankWebService.AccountManagerWebServiceService"
   provider="CPP:RPC " description="VisiBroker C++ web service">
  <parameter name="className"
value="/usr/local/VisiBroker/servies/libaccount_manager.so"/>
<parameter name="allowedMethods" value="openAndQueryBalance"/>
<parameter name="objectName" value="BankManagerWebService" />
<parameter name="locateUsing" value="osagent" />
<parameter name="poaName" value="/bank_agent_poa">
  </parameter>
</service>
Limitations
Because of some Axis limitations, the following restrictions apply in the current version.
SOAP/WSDL compatibility
SOAP version 1.1 and WSDL version 1.1 is supported.