0200-0202

Previous Table of Contents Next

Page 200

The oracle.html package contains the classes required to format an HTML response. For example, the response to the preceding example might be formatted as follows :

 oracle.html.HtmlStream response = HtmlStream.theStream(); response.println("Content-type: text/html; charset=us-ascii"); response.println(); oracle.html.HtmlHead head = new oracle.html.HtmlHead("Success!"); oracle.html.HtmlBody body =     new oracle.html.HtmlBody("Record successfully inserted"); oracle.html.HtmlPage page = new oracle.html.HtmlPage(HtmlHead, HtmlBody); 

The capabilities of applications written with Java are almost unbounded. Although the PL/SQL cartridge is the mainstay of current Web Application Server development, Java plays an important role in the future of Web development. Using third-party libraries and development tools, you can extend applications using the Java cartridge to access services anywhere on the network, including CORBA-based services. A full discussion of Java programming and the Java cartridge is beyond the scope of this chapter. For additional information on Java programming using the Java cartridge, see Chapter 52, "Oracle Web Programming with Java and Perl." That chapter provides background on the Java language and how it can be used to access CORBA services.

Other Oracle Cartridges

For the vast majority of Web-enabled applications, the PL/SQL, LiveHTML, and Java cartridges provide all the capabilities required to communicate with databases and generate dynamic Web content. For more specific needs, Web Application Server 3.0 introduces three additional cartridges:

• Perl provides an easy migration path for CGI scripts written in Perl and a library (Oraperl) that can be used to access Oracle databases from Perl scripts.
• Oracle Worlds provides dynamic generation of VRML (Virtual Reality Markup Language).
• Open Database Connectivity (ODBC) provides database access (available only with the advanced version). This cartridge allows access to other database servers such as Informix, Sybase, and others.

In addition to the cartridge solutions provided by Oracle, other cartridges are available from third-party vendors , and more will be available in the near future. Visit Oracle on the Web for the latest information on cartridge development.

Developing Cartridges with the WRB API

The WRB API is the C-language interface used to develop cartridge solutions, which are implemented as shared libraries. Although the WRB provides generic services that assist both dispatchers and cartridges in routing requests and responses, cartridges provide the services used to process requests and format responses. This chapter presents an overview of the API used to

Page 201

develop cartridges, the basic structure common to all cartridges, and the means by which specific persistent models are implemented.

The functions that make up the WRB API can be classified into five distinct categories:

• Core APIs: Functions used to read and write configuration information, read requests and parameters, provide cartridge-level authentication, and send responses.
• Content Service APIs: Functions used to maintain document repositories (available only in the advanced version).
• Intercartridge Exchange Service APIs: Functions used to issue and read requests and responses through the intercartridge exchange.
• Transaction Service APIs: Functions used to specify resource managers (DADs) and maintain transactional state across multiple executions.
• Logger Service APIs: Functions used to log standard and cartridge-specific execution information to a file or database table.

The Core APIs provide the bulk of the functions required to build a cartridge. Cartridges use these functions to get cookie data from the request header, read and parse URLs, parse parameter blocks or read name value pairs, send dynamically prepared HTML responses, and so on. Cartridges should also implement support for the intercartridge exchange to maximize component reuse and log execution timestamps, authentication timestamps, and use of errors to support administrative and diagnostic tasks .

Each cartridge should also implement a standard set of functions, including the following:

• Init allocates memory or other resources required to process the request.
• Exec performs the actual processing of the request.
• Authorize performs authorization using the basic or digest scheme (if cartridge-level authorization is required).
• Shutdown frees all resources associated with the instance.
• Version returns a version string to the WRB.
• VersionFree frees memory allocated for the version string.

Of these functions, only Exec is strictly required. This function's name is specified as part of the cartridge configuration, and it provides the entry point for processing a request. After it finishes processing, it is required to return one of three defined values:

• WRB_DONE indicates that the request was processed successfully.
• WRB_ERROR indicates that an error occurred in processing a request (processing was not completed).
• WRB_ABORT indicates that a fatal error occurred and the application must be terminated abnormally.

Page 202

When the Exec function returns, WRB considers the cartridge instance to be available ( assuming that the cartridge is not configured to use the Transaction Service). If more than the minimum number of cartridge instances are loaded and there are no pending requests, the cartridge instance is unloaded. Otherwise, it remains loaded to process subsequent requests.

As mentioned in the architectural overview, cartridges follow one of three general programming models:

• Request-response
• Session
• Transaction

Cartridges implementing the request-response model should not store any state information because each request stands on its own. The session and transaction models both need to store persistent state information, and the differences between the two are somewhat subtle. Both can use the Transaction Services to define transactional boundaries. Note that cartridges based on the transaction model enforce a rigid ordering in the individual procedures that make up the transaction. After processing a request that participates in a transaction, cartridges based on the transaction model must call tx_annotate_path(), informing the Transaction Server of the URL anticipated as the next part of the request. If the next request does not involve the expected URL, it is not considered part of the transaction. However, when using the session model, you can maintain state information indefinitely because cartridges based on the session model service a single client for the life of the instance. This allows developers to build cartridges that support more flexible transaction processing while taking advantage of the Transaction Service when it is convenient to do so.

Summary

This chapter provides a high-level overview of the Oracle Web Application Server, its deployment options, and the flexible component-based development environment it provides. The information presented here barely scratches the surface of its full capabilities; I hope it is enough to demonstrate that Web Application Server is more than an HTTP server with some API extensions. Its distributed processing model, security options, advanced administration features, and reusable cartridge extensions provide the performance, security, scalability, and extensibility required for large-scale deployment of Web-enabled applications.

Previous Table of Contents Next