Developed at the

ODRA – Object Database for Rapid Application development

Description and Programmer Manual

by Marcin Daczkowski, Tomasz Pieciukiewicz and the ODRA team

13. Web Services Backend and Frontend

ODRA makes it possible to accept web services as ODRA procedures (backend) and to create new web services at top of ODRA applications (frontend). Actually, all features of web services are hidden from the ODRA programmer. After some adaptation he or she may perceive any web service as an ODRA procedure, being totally unaware of all the XML wrapping and specific web service protocols such as SOAP. This creates a lot of opportunities that in the Web Services terminology are called as “choreography” and “orchestration”. Any composition and any mode of calling web services are possible, including synchronous and asynchronous calls, storing and processing results of services and combining web services with processing on the ODRA side . Moreover, regular ODRA objects can be parameters of web services and any response from a web service is automatically converted to the ODRA store and query result model. ODRA makes it possible to create a new web service. Together with other ODRA functionality, such as queries, imperative constructs, procedures, classes and updaptable views this creates a very powerful mechanism that allows for any composition of web services, virtualisation of web services and many other options that are considered in the literature.

13.1 ODRA Web Services Proxies

ODRA provides native support for consuming web services. The Web Services Proxies mechanism allows to include volatile and external data into a database.

Interaction with remote services is achieved through strongly typed stubs. They are realized as regular database objects. That makes them transparent for database – any its mechanism can be applied to the stubs. For example, they can profit from query, type checking and authorization of database features. That makes remote and local resources interaction very similar from the developer’s point of view.

Currently ODRA proxies support subset of WS-I BP 1.1 compliant web services. They can be used to consume only those of them, which are developed with the “document/literal” style. Both “wrapped” and “bare” dialects are supported and are detected automatically.

13-1. Web services proxy for the Stock Quotes example

In order to create a new proxy module the user needs to use the following DDL command:

add module proxyName as proxy on "contractUrl"

Options for this command are described in the following table:

Table 13-1. Create proxy command options description.

Option name	Allowed values	Description
proxyName	any valid database object name	Name of module which will be created
contractUrl	URL	Determines an object to expose. Currently it can be a procedure or class name.

Because a proxy module (from developer perspective) is a regular database object, the standard module deletion command can be used to remove it:

remove module proxyName

Below we present example of a proxy usage scenario. Consider creating proxy for the stock quote web service:

add module StockProxy as proxy

on "http://www.swanandmokashi.com/HomePage/WebServices/

StockQuotes.asmx?WSDL"

After creating the above, the programmer may use the generated stub to make remote calls. Note that remote calls are mixed with standard query constructs. For example calling:

(GetStockQuotes("MSFT,YHOO,GE").GetQuotesResult.Quote

where (real) StockQuote > 25 ).(CompanyName, StockQuote);

It will end up with a similar result to the following output:

bag{

struct{

"MICROSOFT CP"

"30.49"

}

struct{

"GEN ELECTRIC CO"

"38.12"

}

13.2 Web Services Dynamic Invocation Interface

ODRA includes the support for stubless, dynamic invocation of web services. Realized as a part of an external method call interface, it allows the user to create a document that is sent to a webservice during runtime, creating any valid XML structure. Returned results may be consumed like results of any other SBQL query.

Currently the interface supports a subset of WS-I BP 1.1 compliant web services. They can be used to consume only those of them that are developed with the “document” style. Utilization of the interface requires knowledge of the web service’s interface.

In order to make a DII call, the user has to initialize a new web service object first:

external new_webservice (namespace,endpoint_url,wsdl_url, operation_name);

The addfield_webservice function adds a new tag to the document. It accepts three parameters: integer identifier of the service object, integer identifier of the parent tag (the document tag has ID=100) and the name of the added tag. It returns the integer identifier of the added tag. For example:

external new_webservice ("http://sample/","http://localhost:8080/SampleApp/

SampleService", "http://localhost:8080/SampleApp/SampleService?wsdl", "sampleOperation");

This function returns an integer identifier of service object, which should be recorded for future use. If the web service accepts parameters, a document containing the parameters should be constructed. There are three functions which are used to create such a document:

external addfield_webservice(service_id,parent_object,field_name);

external addfield_webservice(100,100,"sampleparameter");

The second function is used to add attributes:

external addattr_webservice(service_id,parent_object,attribute_name, attribute_value);

The addattr_webservice function adds an attribute to a tag in the document It accepts four parameters: an integer identifier of the service object, an integer identifier of the parent tag (the document tag has ID=100), a name of the added parameter and a value of the added parameter. For example:

external addattr_webservice(100,101,"type","xs:string");

The third function is used to add text to tags:

external addtxt_webservice(100,101,text_to_add);

The addtxt_webservice function adds a text value to a tag in the document. It accepts three parameters: integer identifier of the service object, integer identifier of the parent tag and string added as a text value to the tag. For example:

external addtxt_webservice(100,101,"sample text");

After the document is created, the web service may be invoked:

external invoke_webservice(service_id);

The invoke_webservice function accepts a single parameter – the id of a service object to be invoked. It returns the return message from the webservice converted to an ODRA result. For example:

external invoke_webservice(100);

Document assigned to a service object may be reset, e.g. if after a call another call to the same web service, but with a different set of parameters has to be made. It may be reset with the reset_webservice function, which accepts a single parameter – the id of the service object. For example:

external reset_webservice(100);

When the service object is no longer necessary, it should be deleted using the delete_webservice function. It accepts the id of the service object. For example:

external delete_webservice(100);

13.3 Web Services Endpoints

ODRA provides the native support for exposing web services. This feature allows for external applications to take advantage of the ODRA features through the web services interface.

There are three kinds of web services endpoints in ODRA: generic, procedure and class based. Each of them works in the context of a special web service user account. All kinds of endpoints are designed to met WS-I BP 1.1 compliance.

Web services endpoints access interface may be customized to meet exact deployment expectations. The endpoints specific configuration parameters are described in next subsections.

13.3.1 Generic Web Service Endpoint

A generic endpoint provides unlimited and flexible access to database resources through a web service. Due to its usage characteristics there are no DDL commands to manipulate it. There can be at most one such endpoint in a database. It can be configured (i.e. enabled or disabled) in a database configuration file.

13-2. Web Service endpoint

Because of high dynamicity of possible generic endpoint response results, its WSDL contract is static. It exposes one remote method Execute, which takes two string parameters:

· sbql – any valid SBQL program,

· module name (global name) – indicates the context of the above program execution.

A generic web method response is an XML fragment, which is serialization of provided SBQL program result. If any error occurs during the processing (i.e. an incorrect SBQL code, non-existing module usage), it is delivered through the standard web service error reporting mechanisms.

13.3.2 Procedure and Class based Web Service Endpoints

Additionally to previously described generic endpoints, a typed endpoint is available in ODRA. Its instances are attached to regular objects in a database. Currently a global procedure and a class are supported. In the first case a web service contains only one remote method (connected to a local procedure). In the second case it has as many methods as the class being exposed.

For this endpoint type, the input and output shape is known in advance. This allows fine-grained remote interaction, because all type information may be included in a web service contract. A WSDL document is build dynamically. Its shape depends on a type of the exposed object and user provided options. All exposed services are compliant with WS-I BP 1.1 and use “wrapped” version of “document/literal” SOAP encoding/style.

13-3. Web Service remote calls

In order to create a new endpoint the following DDL command is to be executed:

add endpoint endpointName on objectName

with

(
state={started|stopped},

path="relativePath",

service="serviceName",

port="portName",

ns="namespaceURI"
)

The options for this command are described in the following table:

Table 13-2. Create endpoint command options description.

Option name	Allowed values	Description
endpointName	any valid database object name	Provides name, which may be further used to refer to this endpoint.
objectName	any valid database object name	Determines the object to expose. Currently it can be procedure or class name.
state	started or stopped	Indicates whether endpoint processes incoming requests (started) or skips them (stopped).
path	relative URL starting from /	Determines web service endpoint access URL. Relative within HTTP embedded server domain.
serviceName	Any non empty combination of letter, digits and '.', '-', '_' and ':’	Provides name, which will be used as Service name in generated WSDL document.
portName	Any non empty combination of letter, digits and '.', '-', '_' and ':’	Provides name, which will be used as PortType name in generated WSDL document.
ns	URI	Provides namespace, which will be used as target namespace in generated WSDL document.

In order to remove an endpoint, the user needs to use a dedicated DDL command:

remove endpoint endpointName

Additionally there may be a need to stop request processing for a given endpoint but without really removing it. It can be accomplished by:

suspend endpoint endpointName

After the previous command is executed the following one can be used for bring endpoint back to live:

start endpoint endpointName

Below we present an example of a class based web service endpoint usage scenario. We assume that a database is placed on the machine available at address http://egov-bus.org and that an embedded HTTP server is configured to use the 8888 port. We will expose the following module, which provides simple auction implementation. The user may acquire list of offered items and make a bid. The topmost bids are kept in the global variable “items”.

module AuctionModule {

type Item is record {

id : integer;

name: string;

description: string;

price: real;

}

items:Item[0..*];

class AuctionClass {

instance Auction: { }

getItems():Item[0..*] {

return items;

}

makeBid(itemId:integer; newBid:real):Item {

price:integer;

name:string;

price = (items where id = itemId)[0].price;

name = (items where id = itemId)[0].name;

if price < newBid then {

(items where id = itemId).price := newBid;

}

return (items where id = itemId)[0];

}

Before going further we need to pre populate auction items with some example data:

create permanent items(1 as id, "mercedes" as name,
"brand new" as description, 15.5 as price);

create permanent items(2 as id, "audi" as name,
"4 years old" as description, 12.5 as price);

In order to make it available as a web service we need to run the following command in the AuctionModule context:

add endpoint AuctionEndpoint on AuctionClass

with (state=STARTED, path="/Auction", service="AuctionService",

port="AuctionPort", ns="http://www.egovbus.org/endpoints/tests")

After executing the above command the web service will be immediately available. Its contract may be found at http://www.egov-bus.org:8888/Math?wsdl. Any web service platform, which supports WS-I BP 1.1 compliant web services may be used to interact with Auction web service.

Please note that the topmost bids are kept between subsequent web service calls. The presented example shows how it is easy to create stateful web services in ODRA. Web services created in ODRA may be stateless as well.

13.3.3 Configuration

There are several parameters, which determine web services an endpoints operation. They are placed in the main database configuration file. Options directly connected with endpoints are listed in the following table.

Table 13-3. Web services endpoints feature configurable parameters

Option name	Allowed values	Description
Endpoints specific options(ws.endpoints)
server.address	URL		Determines base server address, which will be used to host web services endpoints
server.port	1 - 65535		Determines base server port, which will be used to host web services endpoints
context.username	any valid database user name		Determines user context of web service endpoints execution.
generic.enabled	yes/no		Indicates whether generic web service endpoint functionality should be enabled.
generic.path	relative URL starting from /		Determines web service endpoint access URL. Relative within HTTP embedded server domain.
generic.servicename	Any non empty combination of letter, digits and '.', '-', '_' and ':’		Provides name, which will be used as Service name in generated WSDL document.
generic.portname	Any non empty combination of letter, digits and '.', '-', '_' and ':’		Provides name, which will be used as PortType name in generated WSDL document.
generic.namespace	URI		Provides namespace, which will be used as target namespace in generated WSDL document.

Last modified: July 2, 2008