DBA Tips Archive for Oracle

  


Oracle Servlet Engine - (OSE)

by Jeff Hunter, Sr. Database Administrator

Contents

  1. What is Oracle Servlet Engine?
  2. Metalink Notes on OSE Usage and Installation
  3. Connecting to the Oracle Servlet Engine
  4. Non-Shared Server Installation
  5. What are Web Services?
  6. What is a Web Domain?
  7. Web Service endpoint
  8. Configuring OSE Details

What is Oracle Servlet Engine?

Oracle Servlet Engine (OSE) works as a specialized Web server, designed as a scalable servlet server inside the Oracle8i database. The servlet classes are loaded into Oracle8i and Oracle9i (9.0.1 only), and published in a JNDI namespace inside the database. A servlet runner handles HTTP requests, instantiates published servlets in sessions, and invokes servlet methods.

Each session (virtual Java VM) executes the following items:

OSE in Oracle 8.1.7 supports servlets 2.1 and JSPs 1.0.

OSE in Oracle 9.0.1 supports servlets 2.2 and JSPs 1.1.

OSE is no longer supported in Oracle 9.2.0.

Metalink Notes on OSE Usage and Installation

  • Note:174736.1 - Configuring OSE/OJVM, mod_OSE & flying pig
  • Note:190347.1 - Ext/R.R Should I Use JServ or OC4J for My Java Deployment Environment?
  • Note:126083.1 - How to Set Up OSE to Listen and Respond to HTTP Requests
  • Note:126091.1 - How to Setup MOD_OSE to Dispatch Requests to Configured OSE Service
  • Note:136187.1 - How to deploy Business Components JSP Application to Oracle Servlet Engine (OSE)
  • Note:131768.1 - Step by Step Instructions for Configuring Mod_ose with IAS9i and Oracle 8iR3
  • Note:157770.1 - Java APIs Supported in 9iAS

    NOTE: As of Oracle9i, all users are strongly encouraged to use the Oracle Containers for J2EE (OC4J) product for J2EE applications, rather than OSE!

  • Connecting to the Oracle Servlet Engine

    The OSE runs in a virtual JVM inside an Oracle (database) server session. You must be running an Oracle shared server configuration to run the Oracle JVM, and hence to use the OSE. There are three ways that an HTTP client can access a Servlet or JSP in the OSE:

    1. By connecting to an OSE Web service directly through a dispatcher. (Connection Type #2)
    2. By connecting to an Oracle listener that is configured to hand HTTP requests off to an OSE Web service (through a dispatcher). (Connection Type #3)
    3. By connecting to the Oracle HTTP Server (powered by Apache), and routing HTTP client requests through mod_ose to the Oracle Servlet Engine in an Oracle (database) server. (Connection Type #4)

    The first of these possibilities can be useful for debugging, or for quick testing of deployed servlets. But because it does not provide adequate scaling when multiple clients are involved, it should never be used when developing or testing production applications.

    The second possibility can serve when your application consists solely of stateful servlets or JSPs. This, however, is true of few applications.

    The third possibility is the one that Oracle recommends for all applications. Static HTML pages and other static data are served from the Oracle HTTP Server, and requests for dynamic content are routed through mod_ose to the OSE. To set up your application to run in this mode, there are additional configuration steps that you must perform. For example, you must configure the Apache mod_ose configuration file ose.conf to indicate which requests will be routed to the OSE.

    It is also possible to use the Oracle HTTP Server with mod_ose to connect to OSE applications with a server configuration that does not normally use-shared servers

    NOTE: Keep in mind that since OSE has a built-in web server. This web server allows direct access from an HTTP Client to the OSE, calling static HTML pages in the OS file system. In the detailed explanation below, this is considered as "Connection Type #1".

    Non-Shared Server Installation

    The mod_ose module requires a shared server installation to run. It will not run if the database is not configured with any shared dispatchers/servers. However, some users prefer not to run with shared servers as a standard configuration. Oracle recommends the following work around to let you use Apache and mod_ose in a dedicated server environment.

    In the database initialization file (init.ora), create one or more dedicated dispatchers and servers with a specific service name. You can use any service name that follows the init.ora conventions as long as it differs from the database service name. The following examples use "MODOSE":

      mts_dispatchers="(PROTOCOL=tcp)(SERVICE_NAME=MODOSE)"
    
      mts_dispatchers="(PROTOCOL=tcps)(SERVICE_NAME=MODOSE)"
    The connect identifier in the tnsnames entry (tnsnames.ora file) should use this service name rather than the database service name.
    INST1_HTTP.IDEVELOPMENT.INFO =
      (DESCRIPTION =
        (ADDRESS_LIST =
          (ADDRESS = (PROTOCOL = TCP)
                     (HOST = wwwdb3.idevelopment.info)
                     (PORT = 1521)
          )
        )
        (CONNECT_DATA =
          (SERVER = SHARED)
          (SERVICE_NAME = MODOSE)
          (PRESENTATION = http://admin)
        )
      )
    You will now have a shared dispatcher and server that will not be used by other clients--only by mod_ose.

    What are Web Services?

    Oracle Servlet Engine serves one or more Web Services. A WebService is the entry point of your Web Applications, and we can think of it as virtual web server. The most important Web Service parameters are its port and its corresponding JNDI root directory.

    # sess_sh
    --Session Shell--
    --type "help" at the command line for help message
    $ createwebservice -root /iDevWebServer iDevWebServer
    While logged in via Session Shell, (sess_sh), the above example creates a Web Service named iDevWebServer (you will retrieve this name in the /service JNDI directory) with the JNDI root of the service being in the /iDevWebServer directory.

    What is a Web Domain?

    A Web Domain is the contents of its corresponding Web Service. A Web domain contains configuration information stored in an object called config, servlet contexts, realms, logs.

    There are two types of WebService

    The Web domain identification for HTTP requests depends on OSE configuration:

    Single Domain Services

    The address part of the sent URL is actually ignored and the port that is used to connect to OSE solely determines the Web Domain. If that service is a Multi-Domain service, then the address part and server IP used to connect to the server are used to determine which domain to use.
    Multi Domain Services
    This document does not explain Multi-domain service configuration.
    # sess_sh
    --Session Shell--
    --type "help" at the command line for help message
    $ createwebdomain -docroot /u01/app/oracle/oraweb /iDevWebServer
    The above example creates a Web Domain stored in the /iDevWebServer JNDI directory which should already exists as a Web Service root directory. Also, the default physical location of all static pages (-docroot option) will be /u01/app/oracle/oraweb.

    This example is based on a Single Domain Service configuration.

    Web Service endpoint

    A Web Service network entity is called an endpoint and can be associated with one or more HTTP listener or HTTP dispatcher. We need to add at least one endpoint to this service.

    We have following options to connect to Oracle8i OSE using HTTP endpoints:

    Configuring OSE Details

    Pre-configuration Tasks and Setup
    Before diving into the details of configuring OSE, there are a few requirements and installation steps that need to be taken.

    • Make sure JServer is installed in the Oracle database server. This can be accomplished using the following:

      • Set the following instance parameters:
        parallel_automatic_tuning = false
        shared_pool_size          = 200000000
        java_pool_size            = 100000000
      • Run installation script:
        @$ORACLE_HOME/javavm/install/initjvm.sql

    • Oracle HTTP Server (which can be installed as part of Oracle8i or Oracle9i database product set) installed under:
      $ORACLE_HOME/Apache

    • Install correct JDK

      When you install the Oracle HTTP Server, you will be asked for the location of the JDK. This is usually not within the ORACLE_HOME path. We install the JDK in /usr/local/java for Linux and /usr/java for Solaris. All of my testing seems with have worked with Java 2 SDK 1.4.

    • Install Oracle Servlet Engine

      $ORACLE_HOME/javavm/install/init_jis.sql

    • Check and change if necessary the init.ora parameters for the Multi-Threaded Server (MTS) option:
      mts_dispatchers="(PROTOCOL=TCP)(DISPATCHERS=4)(CONNECTIONS=250)"

    • Check and grant if necessary (as user SYS)
      SQL> GRANT JAVAUSERPRIV TO SCOTT;
    Getting the Flying Pig
    At the command prompt, do the following to register endpoint for the admin service:
    # cd $ORACLE_HOME\jis\install
    # sess_sh -s jdbc:oracle:oci8:@ -u sys/change_on_install
    --Session Shell--
    --type "help" at the command line for help message
    $ @serverendp.ssh admin 8080 9090 -register
    $ exit
    • Restart the listener.
    • Restart the database.
    • In the browser go to http://<your_machine name_OR_ip>:8080/
    • This should give you the flying pig page verifying that you could reach the Oracle Servlet Engine.
    Configure Demo Web Service (iDevDemo) for use with the OSE
    This Web Service will be used throughout the remaining examples.

    Here is a list of the variables and locations that will be set:

         Web Service Name           : iDevDemo
         Web Service Root Directory : iDevDemoRoot
    • Invoke the session shell tool on the database server
      # sess_sh -u sys/change_on_install -s jdbc:oracle:oci8:@
    • Create a Web Service and a Root Directory in the JNDI namespace
      sess> createwebservice -root /iDevDemoRoot iDevDemo
    • Change the owners from SYS to SCOTT
      sess> chown -R SCOTT /iDevDemoRoot
    • Define access rights
      sess> chmod -R +rwx SCOTT /iDevDemoRoot
    • Create a Web Domain. The option -docroot defines the path of static HTML pages
      sess> createwebdomain -docroot /u01/app/oracle/oraweb/StaticPages /iDevDemoRoot
    • Create a Context within the Web Domain
      sess> createcontext -virtualpath /iDevDemo -docroot /u01/app/oracle/oraweb/StaticPages /iDevDemoRoot iDevDemoContext
    • Add a new Endpoint to the listener
      sess> addendpoint -port 7788 -register iDevDemo iDevEndpt01
    • Setup access rights for the new objects
      sess> chmod -R +rwx SCOTT /iDevDemoRoot
    Direct Access from HTTP Client to the OSE, calling static HTML page in OS file system (Connection Type #1)
    This type of configuration will allow the user to establish a connection to the Oracle Servlet Engine (OSE) "directly" using an HTTP Client (a Web Browser) to access a static HTML page in the OS file system. No HTTP server is required for this configuration as the OSE uses the built-in Oracle web server. The port used in the connection will be created by the OSE by use of an end-point. In this example, we use 7788 as the end-point.

    Direct Access from HTTP Client to Servlet in the OSE (Connection Type #2)
    This type of configuration will allow the user to establish a connection to the Oracle Servlet Engine (OSE) "directly" using an HTTP Client to access a servlet stored in the Oracle database. No HTTP server is required for this configuration as the OSE uses the built-in Oracle web server. The port used in the connection will be created by the OSE by use of an end-point. In this example, we use 7788 as the end-point.

    Calling Servlet in the Servlet Zone of the Oracle HTTP Server (Connection Type #3)
    This type of configuration will allow the user to establish a connection to the Oracle HTTP Server in order to access a servlet in the server's Servlet Zone. This configuration makes no use of the Oracle Servlet Engine (OSE), but is essential in setting up in order to better troubleshoot problems when trying to use mod_ose to access the OSE.

    In short, this connection method makes use of the Oracle HTTP Server's JServ option for extending the web server and running Servlets and JSPs.

    Instructions on configuring a servlet zone in the Oracle HTTP Server is documented in the article Deploying Java Servlets and JSPs using the Oracle HTTP Server (8i or higher).

    Calling Servlet in the OSE over the Oracle HTTP Server (Connection Type #4)
    This type of configuration will allow the user to establish a connection to the Oracle HTTP Server in order to access a servlet in the Oracle Servlet Engine (OSE). This configuration uses mod_ose through the Apache Web Server in order to access the OSE.

    For this connection type, it is assumed that you have a Typical installation which includes the installation of the Oracle HTTP Server (Apache). You can test your Apache webserver by invoking it at the default port 80, 7777, 7778, or 7779.

    http://<your_machine_name>:80/

    1. For this example, I will reuse the same web service created in the "Configure Demo Web Service (iDevDemo) for use with the OSE" section of this article. This will allow us to focus on the mod_ose specific configuration steps.

    2. Edit the tnsnames.ora:
      INST1_HTTP.IDEVELOPMENT.INFO =
        (DESCRIPTION =
          (ADDRESS_LIST =
            (ADDRESS = (PROTOCOL = TCP)
                       (HOST = wwwdb3.idevelopment.info)
                       (PORT = 1521)
            )
          )
          (CONNECT_DATA =
            (SERVER = SHARED)
            (SERVICE_NAME = MODOSE)
            (PRESENTATION = http://iDevDemo)
          )
        )
      The service name is the name of the database and the presentation is the web service created using createwebservice -root /iDevDemoRoot iDevDemo.

    3. Add an endpoint to listener over Net8 protocol.
      # sess_sh -u sys/change_on_install -s jdbc:oracle:oci8:@
      --Session Shell--
      --type "help" at the command line for help message
      
      $ addendpoint -net8 -register iDevDemo iDevDemoNet8
      NOTE: This step is required when using mod_ose. This command is using the default listener. The option -net8 specifies that the endpoint is configured to accept requests over the Net8 protocol. We in this case are using the default port 80. The option -register specifies that the endpoint should always exist when the listener is started. The above example iDevDemo is the name of the web service and iDevDemoNet8 is the name of the end point.

    4. Restart the TNS listener.

    5. Restart the database.

    6. Edit the mod__ose.conf located under $ORACLE_HOME\Apache\Apache\conf\ Add following:
      <Location /testing/Hello >
        SetHandler aurora-server
      </Location>
      just before the line </IfModule>.

      NOTE: You could just point to <Location /testing/ > to include all servlets and other files in the servlet context.

    7. Restart the Apache web listener.

    8. Invoke the servlet:

      http://<your_machine_name>:80/testing/Hello



    Copyright (c) 1998-2014 Jeffrey M. Hunter. All rights reserved.

    All articles, scripts and material located at the Internet address of http://www.idevelopment.info is the copyright of Jeffrey M. Hunter and is protected under copyright laws of the United States. This document may not be hosted on any other site without my express, prior, written permission. Application to host any of the material elsewhere can be made by contacting me at jhunter@idevelopment.info.

    I have made every effort and taken great care in making sure that the material included on my web site is technically accurate, but I disclaim any and all responsibility for any loss, damage or destruction of data or any other property which may arise from relying on it. I will in no case be liable for any monetary damages arising from such loss, damage or destruction.

    Last modified on
    Monday, 23-Jan-2006 08:49:30 EST
    Page Count: 24226