4
Architecture

This chapter describes how OSE handles requests for single-domain and multi-domain Web services. You can follow the logic OSE uses to find the right servlet. The topics we cover are the following:

• HTTP Requests

• Life Cycle of the HTTP Request

• Database Sessions

HTTP Requests

When the first HTTP request is received from a browser, a session is created for the client. Any following requests are routed to the session. The session tracking mechanisms are cookies or URL rewrites.

URLs

The URL is composed of the protocol, the server, and the Uniform Resource Identifier (URI), as such:

<protocol>://<server>/<URI>

The URI is specified by a client in URL request. The URI contains information OSE uses to match against declared virtual paths. The mappings in config objects are used to determine which servlet to employ for a given request. If a servlet cannot be located, the default servlet is employed.

Life Cycleof the HTTP Request

As an HTTP request life-cycle example, we use the URL http://cavist.com:8080/cellar/bordeaux.wine in the multi-domain depicted in Figure 1-3.

The following steps show the progrtess of this cycle:

1. The browser sends an HTTP request.

2. The request is received on port 8080.

3. A database session is created and OSE is given the request.

4. OSE uses a service to listen on port 8080. (Refer to Chapter 6, "OSE Server Configuration" for instruction on how to set up the OSE.)

5. The request is examined by the web service and looks at the IP address, mapping it to the IP domain.

6. The DNS name (cavist.com) is mapped to the JNDI namespace directory (cavist.com).

7. The 10.1.1.20/cavist.com/config object is used to match the URI into a servlet context (the URI virtual path cellar maps to the JNDI namespace entry, winecellar). See Finding the Servlet Context .

8. The servlet context config object is used to match the remaining portion of the URI (bordeaux.wine) to the correct servlet, cavist.com/contexts/winecellar/named_servlets/wine_servlet

9. The servlet, wine_servlet, services the request, http://cavist.com:8080/cellar/bordeaux.wine

10. session terminates. (see Database Session Time-Out .)

Endpoints

Endpoints are the ports which receive the information. Net8 controls the load balancing and connectivity. In order to receive incoming requests, the listener must be configured with an endpoint for each presentation type, using the IP address of the host and a valid port number to be assigned to the listener.

Finding the Web Domain

The Web domain handling requests directly depends on the containing Web service configuration of the OSE.

When a Web service takes the request as a:

• single-domain, there is only one Web domain associated with the service. By default it is contained in the service root.

• multi-domain, the Web domain is tied to the IP address associated with the DNS name of the URL.

  Hint: For a review of multi-domain set ups, see Example 1-2 as an example followed by a multi-domain directory tree figure.

Finding the Servlet Context

OSE searches in the domain config object for the set of properties that maps the virtual paths to servlet context names. OSE then matches the URI of the request against each entry in the config mapping properties. The longest match indicates which servlet context will serve the request. If the requested servlet context is not found, the default servlet context is used. The default servlet context is stored in, /<domain root>/contexts/default.

Example 4-1 HTTP Requests

If the URI is /cellar/bordeaux.wine

and the contents of the contexts group from the config object are:

/cellar=/winecellar
/test=/test

then the partial URI match /cellar
is served by the context, /contexts/winecellar

Finding the Servlet

After the servlet context is identified, the unmatched portion of the URI is matched against the virtual paths in the servlet context config object. OSE ignores the portion in the virtual path corresponding to the servlet context. The remaining portion is matched against entries in the context.servlets properties of the servlet context. The best match indicates which servlet handles the request.

Note: Entries in the context.servlets properties can be paths or wild-names (see the Servlet 2.2 Specification). Partial paths have priority over wild-names. Exact matches have priority over both partial paths and wild-names.

Example 4-2 Request Served by Servlet

Continuing with the scenario from the previous example, 4-1, the named servlet, tastingServlet, is published in winecellar/named_servlets.

In this case, bordeaux.wine is mapped by the servlet context to an entry named servlet, tastingServlet.

Finding for the Default Servlet

If no match for the requested URL is found, OSE looks for a servlet named defaultservlet, the servlet context directory. When the default servlet is found, it processes the request.

When a Web domain is created, OSE installs a default servlet in the domain servlet context directory. There is always a default servlet in the Web service, but you can provide a virtual mapping of / to function as your new default servlet.

If the unused portion of the URI does not match or partially match the virtual paths published in a servlet context, then this same URI portion is used by the default servlet. The default servlet looks in the doc_root for an exact match. If a match exists, the page is served. If no exact match is found, OSE generates an error code.

Mappings in the servlet context config object that map error codes to error pages. For example, an error code 404 is mapped to the URI named /system/errors/404.htm. This results in the default servlet serving that error file from the name and location in the doc_root.

Example 4-3 Request Served by the Default Servlet

Continuing from the previous example, 4-2, if no match for the servlet is found, the request is served by service root/contexts/winecellar/defaultservlet. The default servlet is employed, and the results are sent back to the client

Database Sessions

The nature of a database session is one of the differences between OSE and other servlet engines.

Figure 4-1 Single Virtual JVM per Browser Session, Multiple HTTP Session in Database Sessions

User Identity of Database Sessions

By default, the database session is authenticated as the owner of the Web domain. All SQL access, through JDBC or SQLJ, is performed in the schema of the Web domain owner.

If you deploy a set of servlets in a domain owned by SCOTT, they access tables in SCOTT's schema, unless another schema name is prepended to the table name. For example, SYS:HTTP$LOG. In this example, the schema SCOTT needs access rights to the other schema's table.

You can use definer's rights code to change this behavior. Code that executes through classes granted definer's rights, executes as SYS.

Database Sessions

HTTP clients can combine several HTTP session objects in a single database session. The HTTP session is set up for each servlet. If the client activates servlets from two different servlet contexts and each servlet calls getSession(true), then two different HTTP session instances exist in the database session, as shown in Figure 4-1.

Two time-outs are associated with Web server sessions inside Oracle8i:

• the time-out of the database session itself

• the time-out of each HTTP session created in the database session

Database Session Creation, Termination, and Time-OutsThe first time an HTTP client connects to an instance of Oracle8i running OSE, a session is created inside the database. The session is a regular database session that runs its own virtual JVM.

Database Session Time-Out

The database session time-out causes all contained HTTP sessions to terminate. This causes all its Java state information to be discarded and all its non-committed SQL states to be rolled back.

Think of it as the termination of the virtual JVM executing the servlets.

The database session time-out is set by the Web service parameter, service.globalTimeout. The Web service object controls the connection. You can set this parameter when you create the service, or configure it later (see Example 4-4).

Example 4-4 Create Service and Set Global Time-out

createservice   [ -http | -iiop ] [-service className ] [-properties propGroups ] 
-root location [ -globalTimeout secs ] service

The time-out begins to count after an HTTP request returns. If another request comes in before the time-out expires, it will start counting again using the same value after them first request terminates.

When a database session has timed out, a browser cannot connect to it anymore, even if the browser has kept the session cookie. Instead, it is routed to a new session.

Automatic Termination of Database Sessions

A database session will automatically be terminated if there are no more HTTP session objects left. An HTTP session time-out can cause a database session to terminate.

HTTP Session Creation, Termination, and Time-Outs

An HTTP session is created when a servlet in a stateful servlet context invokes the method getSession(true).

Time-out occurs when the preset value is met with no further activity on the connection. This time-out value is defined in units of seconds and is stored in the config object. If the database session ends, the HTTP sessions must end as well.

More than one HTTP session object can exist per database session. Only one database session exists per client, as shown in Figure 4-1.

A stateful session is useful for a dialogue situation between the client and the servlet. A cookie is sent to the client as a method to keep the client information readily available to the server. A stateful session is useful during sessions when the client is engaged in a step-wise set of information exchanges, when the information in the next step is predicated by the information sent in the previous step. If the client does not support cookies, OSE uses URL rewrites.

---