Previous | Table of Contents | Next

Page 408

The WRB API can be quite extensive in terms of auxiliary methods or functions it contains. Some of these methods are discussed later in this chapter. These methods may be invoked directly from the three basic callbacks mentioned earlier.

Oracle's open approach to product development means that customers and solution providers/partners are jointly developing the WRB API. This cooperative effort means that the API should provide maximum openness and interoperability between Oracle Web Application Server and third-party applications such as cartridges.

Examining the Web Application Server SDK

The Oracle Web Application Server Developer's Kit (SDK) consists of two cartridges—a system cartridge that executes system functions or methods and a programmable cartridge that's a runtime interpreter for applications.

On the Web

VeriFone also created a cartridge called the Virtual Point of Sale cartridge (VPOS). VeriFone cartridges are part of VeriFone's expansion of electronic commerce capabilities on the Web. You can get more information about the VPOS cartridges at http://www.verifone.com.

The Web Application Server SDK is a set of PL/SQL routines and sample applications that help users quickly create Web applications with Oracle Web Server. With some simple modifications to include text and graphics specific to a user's site, these samples can be quickly and easily customized for a particular site.

Each WRB API function can be thought of as a method within WRB, although it appears as though each method really doesn't belong to any particular object.

The WRB Logger API

Given Web Application Server's tight coupling with the Oracle database, you should become more familiar with the WRB APIs related to database connections. The WRB Logger API functions offers such routines:

Page 409

Listing 17.1 shows the WRB_LOGopen method's implementation.

Listing 17.1 The Syntax for the WRB_LOGopen() Method

WAPIReturnCode WRB_LOGopen( dvoid *WRBCtx,
ub4 *logHdl,
WRBLogType type,
WRBLogDestType dest,
text *MyFileName );
Parameters
Return Values
[Returns WAPIReturnCode]

Invoke this method from your cartridge component to open a file or initiate a database connection. The WRB application engine passes the WRBCtx pointer to your calling method in your cartridge. WRBCtx points to the WRB context object. LogHdl is a handle that indicates the type of object contained in the connection object: file or database. type indicates the type of entry in the log. The entry can be a client attribute or a message. dest indicates whether to log the transaction in a flat file or a database. MyFileName is simply the string name of the file. It can also be NULL when you're logging information to the database.

The method in Listing 17.2 writes a system message to the persistent storage specified by the value of logHdl.

Listing 17.2 WRB_LOGWriteMessage() Method Syntax

WAPIReturnCode WRB_LOGWriteMessage( dvoid *WRBCtx,
ub4 logHdl,
text *component,
text *msg,
sb4 severity);
Parameters
Return Values
Returns WAPIReturnCode.

Invoke this method from your cartridge to write a system message to the persistent storage specified by the value in logHdl. The WRB application engine passes the WRBCtx pointer to your calling method in your cartridge. WRBCtx points to the WRB context object. logHdl is a handle that indicates the type of object contained in the connection object: file or database. type indicates the type of entry in the log. It can be a client attribute or a message. component points to the text description to identify the type of cartridge, such as "java". msg is the text you want to log. Messages can't exceed 2K in length. The backquote character (`) is used as a delimiter; if you need to incorporate this interesting character in your message, you must specially tag it with a backslash (that is, \`). severity is just the severity of the message.

The code in Listing 17.3 writes a client-defined attribute to the storage specified by logHdl.

Page 410

Listing 17.3 The WRB_LOGWriteAttribute() Method Syntax

WAPIReturnCode WRB_LOGWriteAttribute( dvoid *WRBCtx,
ub4 logHdl,
text *component,
text *name,
text *value);
Parameters
Return Values
Returns WAPIReturnCode.

Invoke this method from your cartridge to write client-defined attributes to the persistent storage specified by the value in logHdl. The information that is stored is useful for seeing how your custom cartridge responds to system messages. Tracking error and exception handling is critical when developing components. The WRB application engine passes the WRBCtx pointer to your calling method in your cartridge. WRBCtx points to the WRB context object. logHdl is a handle that indicates the type of object contained in the connection object: file or database. type indicates the type of entry that is in the log. It can be a client attribute or a message. component points to the text description to identify the type of cartridge, such as "ODBC". msg is the text you want to log. name is a text item that identifies a particular attribute you want to log. value provides additional text to qualify the attribute you named. See Listing 17.4 for the syntax for WRB_LOGclose() method.

Listing 17.4 The WRB_LOGclose() Method Syntax

WAPIReturnCode WRB_LOGclose( dvoid *WRBCtx, ub4 logHdl);
Parameters
Return Values
Returns WAPIReturnCode.

Invoke the WRB_LOGclose() method from a method in your cartridge to close the file or shut down a database connection as specified by the value in logHdl.

The WRB application engine passes the WRBCtx pointer to your calling method in your cartridge. WRBCtx points to the WRB context object. logHdl is a handle that indicates the type of object contained in the connection object: file or database. This handle was created in the WRB_LOGopen() method.

Understanding Cartridges and ICX

The cartridge provides the openness that Oracle has really pushed for with Web Application Server 3.0. It's also the third major subsystem type in the Web Application Server architecture. Cartridges are components that provide specialized services that augment the overall behavior of Web Application Server. Not only are there built-in cartridges, you or some company can also develop cartridges for a specific need.

ICX, which stands for Inter-Cartridge Exchange, is a mechanism supported by the Web Application Server that facilitates communications between cartridges. ICX provides load-balancing for

Previous | Table of Contents | Next