Page 411
the server. It permits communications across different machines, especially when using a Java-based cartridge.
Cartridges are components that extend the Web Application Server. They can be developed by third-party companies or by an in-house development staff. Cartridges can share computation modules.
WRB CartridgesEach cartridge follows an architecture/model type. Cartridge developers should be aware of only three such design models:
The Request-Response ModelAlmost as if in a knee-jerk reaction, WRB cartridges process individual client requests and issue a request per expected response. After the expected response is dispatched, the cartridge has "amnesia," where no data is associated with the client and the request is persistently stored anywhere. If you're familiar with the lack of state information tracked by regular HTTP requests, this should be quite familiar. So, your cartridge's Exec method would receive the request as an argument, and return relevant information without keeping track of any state data.
The Session ModelIn WRB terms, a session is established between a client and a particular cartridge instance in execution (also known as WRBXs). A cartridge, then, uses the WRB sessions mechanism to maintain a persistent association between the two. You determine how long this association persists. The timeout period you specify determines how long the WRBX remains. The cartridge's Exec method would then state information related to the client that initiated the request. The Exec method stores this state information in the context structure of the application that owns the instance of the cartridgethat is, the application responsible for creating an instance of the cartridge (instantiating the cartridge). By instance, I mean the runtime object copy of the designtime cartridge.
NOTE |
For more information on the differences between a cartridge's designtime architecture and its runtime architecture, refer to works on object-oriented methodologies by Grady Booch, Jim Rumbaugh, or Ivar Jacobson. |
The sessions mechanism makes sure that there's an association between a client and an executed cartridge instance (WRBX). This association provides the cartridge a specialized focus between itself and a client. This instance specialization is where the differences between runtime and designtime architectures make sense. At any given time, many instances of a cartridge can be in execution, each containing state and data specific to a particular client. That is, if you have a cartridge that managed many checking accounts for a particular bank branch, one instance of a cartridge may have a balance of $5,000, another instance may have $230.98, another may have $1,209, and so on, all in execution as tellers reconcile their batches at the end of the day. Data integrity isn't compromised because each cartridge instance is concerned only with the information related to one account. You would then save the state information
Page 412
related to each account in the application context structure so that such information survives the current user session.
The Transaction ModelIf, in your analysis and design, you realize that your cartridge will need to concentrate on handling database transactions, the transaction model is for you. The Exec method would assume the role of a transaction processor. Several states are normally involved in the implementation of this model:
Transactions don't necessarily have to be made in one call (invocation of Exec method). Some transactions can span several invocations of the cartridge's Exec method. The caveat here is that the cartridge's Exec method must determine which of the preceding states applies to the current scenario. This model allows you to support requests independent of any transaction, if your design calls for this feature. (For more information, refer to your WRB Transaction Service API Reference on designing cartridges.)
If you were savvy enough to have purchased the Advanced version of Web Application Server, you can get additional API help from the Transaction Service library. (These services aren't included in the Basic version of Web Application Server.) With this library, you or your development staff can perform any number of database transactions from your cartridge. Oracle based the WRB Transaction Service on the TX interface as it was defined by the X/Open Company.
NOTE |
If you want more information on the background of this helpful feature, refer to X/Open's Distributed Transaction Processing: The TX (Transaction Demarcation) Specification. |
With advanced transaction services, your cartridge can perform database transactions that span several HTTP requests. The actual access to the database is established through database-access APIs such as OCI or ProC, in addition with the transaction service. Trans-action functions such as commit and rollback aren't done through these services. To make the transaction services accessible to your cartridge, you'll have to enable the TRANSACTION service for it. Refer to your Transaction Service documentation for more details.
Looking at ICXThe WRB Intercartridge Exchange Service API allows one WRB cartridge to issue HTTP requests to another WRB cartridge. For an overview of the WRB cartridge architecture, refer to the earlier section "WRB Cartridges."
Using ICX helps system architects design cartridges that provide specialized behavior for an application or enterprise domain. ICX permits cartridges to be located on different machines, thus improving the performance of Web Application Server and providing valuable
Page 413
load-balancing for the network. This also means increased storage space (all the application's components don't reside on one machine) and a more scalable architecture. Coupled with good class and object models, ICX makes maintaining many interactive cartridges relatively easier.
Table 17.1 shows all the methods in the WRB Intercartridge Exchange Service API.
Table 17.1The ICX API Methods
Method | Description |
WRB_ICXcreateRequest() | Creates a request object |
WRB_ICXdestroyRequest() | Destroys a request object |
WRB_ICXfetchMoreData() | Gets more data when WRB_ICXmakeRequest() returns the structure WRB_MOREDATA |
WRB_ICXgetHeaderVal() | Gets the value of a specific response header |
WRB_ICXgetInfo() | Gets information about a request |
WRB_ICXgetParsedHeader() | Gets response headers |
WRB_ICXmakeRequest() | Issues a request |
WRB_ICXsetAuthInfo() | Sets the authorization headers for a specific request |
WRB_ICXsetContent() | Sets the content data for a specific request |
WRB_ICXsetHeader() | Sets the headers for a specific request |
WRB_ICXsetMethod() | Sets the HTTP method to use in a specific request |
WRB_ICXsetNoProxy() | Specifies domains for which the proxy server shouldn't be used |
WRB_ICXsetProxy() | Specifies a proxy server |
Two enumerated types are also supported in the ICX API:
The following sections describe each method.
WRB_ICXcreateRequest()This method allocates and returns a handle to an opaque request object, which encodes the request specified by a given URL. Listing 17.5 shows the code necessary to create a request object.
Listing 17.5 Creating a Request Object with WRB_ICXcreateRequest()
dvoid * WRB_ICXcreateRequest(void *WRBCtx,