Oracle Corporation

Authors:
Seshu Adunuthula
Mala Anand

WRB API Overview

The Oracle Web Request Broker (WRB) provides a powerful distributed runtime environment for developing and deploying industrial strength applications for the World Wide Web. The WRB runtime platform enables application developers to write applications that are independent of and work with a number of HTTP Servers.

The Web Request Broker (WRB) API provides a programmatic interface to the Oracle Web Request Broker and enables applications developers to develop their applications (called cartridges in this document) for the WRB. The WRB API provides a higher level API that abstracts away the HTTP protocol while providing the necessary interfaces for application development.

The functionality provided by the WRB API can be divided into the following categories:

Application Callback Interface. The WRB application logic is performed in these callbacks.
Listener Information Interface. This includes information such as CGI environment variables, MIMETypes, Language encodings etc.
Request Response Interface. This includes accessing client's GET and POST data and responding to requests.
Content Management Interface. These are only available when the web server is running of a database. These allow a uniform management of content irrespective of the content existing on the local filesystem, database or a remote database.
Transaction Management Interface. This interface allows multiple requests to be clubbed together into a single transaction.
HTTP Interface. Ability to make HTTP requests from the cartridge.

The WRB API and the runtime system together enable web applications to be run on a scalable, distributed high-performance back-end infrastructure. The following document describes the WRB API in detail.

WRB API Design Goals & Concepts

The WRB API has been designed to address several deficiencies in the current HTTP Server programmatic interfaces and to meet the following goals:

The WRB provides a high performance, distributed and scalable application execution framework. It provides applications developers to transparently run multiple instances of their applications and provides the necessary load balancing and system scaling functionality to meet the load on the system. Application developers who develop their applications as WRB cartridges get these advantages of the WRB infrastructure for free.
The WRB provides a more robust application development environment than NSAPI, ISAPI and other HTTP Server programmatic interfaces:
The WRB API provides a higher application level interface for web application developers rather than hooks into the HTTP protocol at various interception points. WRB-enabled applications do not need to aware of the HTTP protocol. The WRB mediates all client requests to the appropriate cartridges and ensures fairness by protecting and preventing cartridges from intercepting requests to other cartridges.
WRB applications run in their own address space as independent entities. This provides a level of robustness and reliability not possible with other HTTP Server interfaces which require applications to be dynamically linked into the HTTP Server's address space. This can potentially cause applications to clobber each other's memory space and interfere destructively in signal handlers and other operating system resources. WRB-enabled web applications can be managed and taken on-line and off-line with no affect on other WRB-based web applications running on the same WRB.
The WRB provides a high level interface for database access for WRB-enabled applications. This provides the power of the Oracle database for managing configuration and other runtime information in a secure repository, and provides the application with the infrastructure for maintaining distributed application state and persistance management.
Any WRB enabled application can invoke other WRB enabled applications as well as make a HTTP request to any other HTTP Server. The WRB provides the distributed infrastructure and dynamically distributes application loads across the network.
The WRB API provides an easy migration path for current web applications.

Web Request Broker Dispatcher

The WRB Dispatcher is the component of the WRB that provides the interaction with different underlying HTTP Servers. It is responsible for routing HTTP requests to the appropriate web application cartridge over the distributed substrate. The HTTP server, in turn, interacts with the web browser using HTTP. The WRB Dispatcher looks up and locates the appropriate cartridge for a request from the WRB configuration and dispatches the request for execution to that cartridge. The WRB can run multiple instances of the web cartridge, and the Dispatcher selects an appropriate instance based on overall system load to deliver optimum application performance. The WRB Dispatcher also authenticates the request against the WRB configuration if the WRB-enabled application is using WRB Authentication Services.

Web Request Broker Application Engine

Application developers develop their cartridges as shared libraries (on Solaris) and register them with the WRB Dispatcher. The cartridges are loaded in by the WRB Application Engine when a request for that cartridge is received by the WRB Dispatcher. The WRB Application Engine provides the runtime environment for WRB-enabled applications. It enables WRB-enabled applications to receive and send data to the client, as well as the ability to call other cartridges, which may be located on the same WRB or may be distributed across WRB's and other HTTP Servers.

Application Programming Interface

The WRB API provides application developers with a comprehensive set of calls to build applications independent of the underlying http daemons used. The API is organized as follows:

WRB Application Callbacks

Cartridge developers need to provide the following WRB Application Callbacks that the WRB Application Engine will invoke as described below upon receiving a request from a client for a given cartridge. The bulk of processing by the WRB cartridge is done in the Exec Callback where the callback function responds to the listener request and creates a response.

The Init Callback

WRBReturnCode WRB_Init( void **clientCtx );

This callback is invoked by WRB Application Engine on its initialization. The WRB cartridge initializes its context in this routine which is then made available to the cartridge on subsequent call backs.

The Exec Callback

WRBReturnCode WRB_Exec( void *WRBCtx, void *clientCtx );

This callback is invoked by WRB Application Engine upon receiving a HTTP Request. The WRB cartridge is responsible for creating the response that is written back to the Listener in this callback .

The Shutdown Callback

WRBReturnCode WRB_Shutdown( void *WRBCtx, void *clientCtx);

The WRB Application Engine invokes this call back to provide an graceful exit for the WRB Client. Any memory allocated in the client context during the init callback should be deallocated here.

The Reload Callback

WRBReturnCode WRB_Reload(void *WRBCtx, void *clientCtx);

This callback is not required, but is recommended. The WRB Application Engine invokes this call back whenever the Web Listener has been signalled to reload its own configuration files. The Web Listener halts all new incoming connections, allows existing transactions to complete, and then signals each running WRB cartridge to execute its reload callback (if one exists). If your application uses configuration information from the OWS_APPFILE then you should call WRBGetAppConfig again, as these values may have.

Version Callback

char *WRB_Version();

The version callback enables the cartridge to return a character string with information about the version of that cartridge. This callback is made by the ""wlctl2" utility

WRB Listener Information Functions

The following Listener Information functions provide cartridge developers with information, if required, from the client as well as the underlying HTTP Server. All functions return pointers to WRB Application Engine memory which the WRB client should not modify.

WRB Get URL && WRB Get URI

char *WRBGetURL( void* WRBCtx );
char *WRBGetURI( void* WRBCtx );

Returns the URL/URI received from the HTTP Server. The cartridge developers may extract additional information from the URI/URL if required.

WRB Get Environment Variable

char *WRBGetEnvironmentVariable( void *WRBCtx, char *szEnvVar );

Returns the value of an environment variable. This provides a way for the WRB client to access CGI Environment variables. Returns NULL if szEnvVar points to a invalid environment variable.

WRB GetEnvironment

char **WRBGetEnvironment(void *WRBCtx );

Returns the HTTP Listener environment as an array of null terminated strings with the syntax varname=varvalue. Returns NULL in case of an error.

WRB Get Content

char *WRBGetContent( void *WRBCtx );

Returns either the Query String or the POST data content depending on the type of the request method. Returns NULL in case on an error.

WRB Get Language

char *WRBGetLanguage( void *WRBCtx );

Returns the WRB Application Engine Language preferences. Returns NULL in case of an error. On success, returns a comma delimited list of the "Accept" languages.

WRB Get Character Encoding

char *WRBGetCharacterEncoding( void *WRBCtx );

Returns the WRB Application Engine Character Encoding preferences. Returns NULL in case of an error. On success, returns a comma delimited list of the "Accept" encodings

WRB Get Parsed Content

WRBReturnCode WRBGetParsedQueryString(void *WRBCtx, WRBEntry
					**WRBEntries, int *numEntries);

typedef struct { 
   char 	*name; 
   char 	*value;
} WRBEntry;

Returns an array of name-value pairs after parsing the query string/POST data.

WRB Get Named Entry

char *WRBGetNamedEntry( char *entryName, WRBEntry *WRBEntries, int numEntries);

Returns a name/value pair from a list of entries generated by a call to WRBGetParsedContent. Returns NULL on error

WRB Get ORACLE_HOME

char *WRBGetORACLE_HOME( void *WRBCtx );

Returns the ORACLE_HOME which was set when the Web Listener was started

WRB Get Application Config

char **WRBGetAppConfig( void *WRBCtx );

Returns the configuration information for the current application. The structure of the return value is a pointer to an array of pointers to character strings. These character strings are of the form "name=val". The information is retrieved from the OWS_APPFILE at the time the Web Listener starts up. An example might be:

[MyCartidge]
myparam1 = val1
myparam2 = val2

WRB Get Application Config Value

char *WRBGetConfigVal( void *WRBCtx, char *name );

Returns a named item for the application's configuration. The information is retrieved from the OWS_APPFILE at the time the Web Listener starts up.

WRB Response Functions

These functions are invoked by the WRB cartridge to respond to an incoming client request.

WRB Client Read

ssize_t WRBClientRead( void *WRBCtx, char *szData, int *nBytes );

The WRB Client invokes this function to read the POST data of a HTTP request from the WRB Application Engine. In the current implementation, if a client is going to read POST data it must do so bwfore sending any data (through WRBClientWrite) back to the Web Listener. The return value is the number of bytes read.

WRB Client Write

ssize_t WRBClientWrite( void *WRBCtx, char *szData, int nBytes);

The WRB cartridge invokes this function to send data to the client. The return value is the number of bytes written.

WRB Return HTTP Error

ssize_t WRBHTTPReturnError( void *WRBCtx, WRBErrorCode, nErrorCode, 
				 char *szErrorMesg, boolean close);

Invoked by the WRB client when it would like a standard HTTP error sent back to the browser. This call must occur before any other calls to WRBClientWrite, as it is a wrapper which sends : Status <nErrorCode> <szErrorMesg> The "close" flag set to false indicates that you wish to send additional HTTP header information and that you will close the HTTP header explicitly with a call to WRBCloseHTTPHeader.

WRB Client Call Cartridge

WRBReturnCode WRBCallCartridge( void *WRBCtx, char *request);

The WRB client calls this function to invoke a request which could be satisfied by a cartridge running on the local WRB, or by a remote HTTP Server or WRB.

WRB Client Set Timeout Call

WRBReturnCode WRBClientSetTimeOut( void *WRBCtx, int nTimeOut, 
		WRBReturnCode (*WRBClientCleanUP)( *void WRBCtx ) );

This function can be called by the WRB client to set a time out for long running calls. If WRB Client makes this call the WRB Application Engine sets up a timer to interrupt processing a HTTP request and return to the LIstener with a timedout error response. The WRB client can set a callback WRBClientCleanUp to clean up the client in case of a timeout. WRB Application Engine discards any response from the WRB client once the timeout has happened. If no callback is provided a default callback is used.

WRB Return HTTP Redirect

ssize_t WRBReturnHTTPRedirect( void *WRBCtx, char *szURI, boolean close);

Invoked by the WRB client when it would like a standard HTTP error sent back to the browser. This call must come before any other calls to WRBClientWrite, as it is just a wrapper which sends : Status: <nErrorCode> <szErrorMesg>

The "close" flag set to FALSE indicates that you wish to send addition HTTP header information and that you will close the HTTP header explicitly with a call to WRBCloseHTTPHeader.

WRB Close HTTP Header

ssize_t WRBCloseHTTPHeaer( void *WRBCtx );

Invoked by the WRB client when it would like to close an HTTP header. Generally used after calls to WRBReturnHTTPError or WRBReturnHTTPRedirect with the "close" flag set to FALSE.

WRB Log Message

void WRBLogMessage( void *WRBCtx, char *szMessage, int nSeverity );

Logs the message szMessage to a file ?/ows2/log/wrb_<pid>.c where ? is the ORACLE_HOME and pid is the processid of the Web Request Broker. Currently nSeverity is not used and reserved for future versions.

Content Management Interface

The Content Management Interface provides a uniform interface for the content either in the file system or the database. A file system like access to the content in the database is provided using the Large Object support in the database. The Web authentication schemes Basic/Digest are used for the content protection. NOTE: The content management interface is in the process of being defined and the prototypes given below are subject to change

WRB Create Object

int WRB_CMICreateObject( void *WRBCtx, char *fileName, int fMode );

An entry for the object is created which is identified by the full virtual path to that object. If the cartridge does not have the necessary permissions to create the object then an error is returned. Error information can be obtained by WRB_GetError. On success an object descriptor is returned which is used by the subsequent calls in the interface. WRB_CreateObject does an implicit open on the object. The object can be opened in either read or write mode.

WRB Open Object

int WRB_CMIOpenObject (void *WRBCtx, char *fileName, int fMode );

An object descriptor is returned for the object. The fMode determine the mode in which the object is opened. The object descriptor is used by the subsequent calls to manage the object.

WRB Get Attribute

char  *WRB_CMIGetAttribute( void *WRBCtx, int nObjDescriptor, int nAttrib);

The attributes currently defined on the object are:

Path to access the object
Object type (FS, DB, Cache, ...)
Content type (text, image, ...)
Modified Date
Created Date
Expiry Date
Author
Owner
Title
Copyright
Language
CharacterSet
Object Location (NULL for DB object)

The attribute of the object nObjDescriptor is returned on success. On failure a NULL is returned.

WRB Set Attribute

int WRB_CMISetAttribute( void *WRBCtx, int nObjDescriptor, 
		         int nAttribute, char *szAttribValue );

The attributes of an object can be changed by the cartridge if it has the right permissions to do so. Not all attributes can be modified. An error value is returned if the cartridge tries to modify an attribute with permissions or an attribute that cannot be modified.

WRB Read

int WRB_CMIRead( int nObjDescriptor, unsigned char *sBuffer, int nBufSize );

Read nBufSize bytes from the location pointed to by the nObjDescriptor into sBuffer. The actual number of bytes read is returned. An error value is returned on failure.

WRB Write

int WRB_CMIWrite( int nObjDescriptor, unsigned char *sBuffer, int
	       nBufSize );

Writes nBufSize bytes from sBuffer into the location pointed to by the nObjDescriptor. An error value is returned on failure. Information on the error can be obtained by making a call to WRB_GetError

WRB Copy

int WRB_CMICopy( int nSourceDesc, int nDestDesc, int nMode);

The source object is copied to the destination object. Copy has three different modes associated with it.

Make an actual copy of the source object
Create a link to the source object
Move the source object to the destination.

Trancastion Model Interface

The Transaction model allows multiple requests to be clubbed together into a single transaction allowing these requests to share the same state. The interface defines the following calls.

WRB Init Transaction

int WRB_TMIInitTransaction ( void *WRBCtx, void *xactionState );

A cartridge can initiate a transaction by making this call and providing the xactionState which can be accessed by subsequest requests to the same cartridge.

WRB Get Transaction State

void *WRB_TMIGetXactionState( void *WRBCtx );

Returns the state set by a call to WRB_TMIGetXactionState

WRB Set Transaction State

void *WRB_TMISetXactionState( void *WRBCtx );

Sets the state by a call to WRB_TMISetXactionState

WRB End Transaction

int WRB_TMIEndTransaction( void *WRBCtx );

Ends the transaction.

HTTP Interface

This interface allows the cartridge writer to embed the response from a HTTP request into the response for the request. The details for this interface are still in the process of being worked out.