Oracle8i Enterprise JavaBeans Developer's Guide and Reference Release 3 (8.1.7) Part Number A83725-01 |
Library | Service | Contents | Index

## Advanced Configuration Options

- Database Listeners and Dispatchers

- Dynamic Listener Endpoint Registration

- Direct Dispatcher Connection

- Configuring SSL for EJB and CORBA

### Database Listeners and Dispatchers

Figure 3-3 shows the interaction between the listener and the dispatchers, and also illustrates how an Oracle8i ORB session is activated.

#### Figure 3-3 Listener/Dispatcher Interaction

1. Upon database startup, the dispatcher registers itself with the listener.

2. The client invokes a method, giving the listener's URL address as the destination.

3. The listener sends back a LOCATION_FORWARD response to the client's ORB layer informing it of the dispatcher's address. This redirects the request to the appropriate dispatcher.

   Note: The client is unaware of the redirection logic, which is performed by the ORB runtime layer that supports the client.

4. The underlying ORB runtime layer resends the initial request to the dispatcher. All future method invocations are directed to the dispatcher. The listener is no longer a part of the communication.

The incoming request is examined by the shared server services to see if the request is for an existing session. If so, the request is forwarded to the indicated session. If not, the service creates a new database session for the request and activates the ORB in the session. This session is very similar to the database sessions created for incoming Net8 connections. In the session, the ORB reads the incoming IIOP messages, authenticates the client, finds and activates the corresponding server-side objects, and sends IIOP messages as needed to reply to the connected client. Subsequent messages from the client are directed to the existing session.

When you configure a listener, you need to configure separate ports as listening endpoints for both Net8 and IIOP connections. Similarly, if you want any endpoint to use the secure socket layer (SSL), you will also need a separate endpoint for an SSL-enabled IIOP endpoint. See "Using the Secure Socket Layer" for more information about connecting using IIOP and SSL.

#### Handling Incoming Requests

The administrator for your database configures an MTS server with a dispatcher that is GIOP enabled. In addition, the administrator configures a listener that this dispatcher registers with upon database startup.

When the database does start up, all dispatchers register with all listeners configured within the same database initialization file. However, when an IIOP client invokes a request, the listener will only redirect the request to a GIOP dispatcher or hand off to a generic dispatcher.

These are discussed fully in the following sections:

- Redirect to GIOP Dispatcher

- Hand Off to Generic Dispatcher

##### Redirect to GIOP Dispatcher

The listener recognizes the IIOP protocol and redirects the request to a registered GIOP dispatcher.

#### Figure 3-4 IIOP Listener Redirect to GIOP Dispatcher

1. GIOP dispatcher registers itself with the listener.

2. IIOP client--an EJB or CORBA client--invokes a method, giving the address of the listener. For redirection to occur, the listener must be statically configured to receive IIOP requests.

3. The listener sends back a response to the client informing it of the GIOP dispatcher's address.

   The listener redirects if a GIOP dispatcher is configured. If no GIOP dispatcher is configured, the listener can hand off the request to a generic dispatcher. See "Hand Off to Generic Dispatcher" for more information.

4. The underlying ORB runtime layer on the client resends its initial request to the GIOP dispatcher. All future method invocations are directed to the dispatcher. The listener is no longer a part of the communication.

##### Hand Off to Generic Dispatcher

If there is no GIOP dispatcher statically configured, but there is a generic dispatcher configured, the listener can hand off the request to this dispatcher. The only restrictions are that the listener and dispatcher must exist on the same node in order for the hand off to occur and that the listener must be either statically or dynamically configured to receive an IIOP request.

For hand off to occur, the listener forfeits the socket to the dispatcher. Thus, this can only occur within a single node.

Figure 3-5 shows the dispatcher and listener combination in a hand off environment.

#### Figure 3-5 Hand Off to Dispatcher

1. When the database starts, the generic dispatcher registers itself with the configured listener.

   Note: The listener must be configured to receive IIOP requests. You can either statically configure the listener through the Net8 configuration, or you can dynamically configure the listener through a dynamic registration tool, `regep`. See "Dynamic Listener Endpoint Registration" for more information.

2. The client sends a request to the listener.

3. The listener hands off the request to the generic dispatcher. The listener negotiates with the generic dispatcher on a separate channel. On this channel, the socket is handed off to the dispatcher through the operating system mechanisms.

   The client communicates directly with the dispatcher from this point on. The client is never made aware that the socket was handed off.

### Dynamic Listener Endpoint Registration

As discussed in "Hand Off to Generic Dispatcher", a listener will hand off the socket to an existing generic dispatcher. In order for a hand off to occur for an IIOP incoming request, the listener must have an IIOP endpoint registered. You can register any listening endpoint through either of the following:

- static configuration--configured by the Net8 configuration tool

- dynamic configuration--registered by the dynamic registration tool, `regep`

The dynamic registration tool, `regep`, adds any type of listening endpoint to your listener. This includes an IIOP listening endpoint. The following describes how to use the dynamic registration tool for an IIOP listening endpoint.

The restrictions for this scenario are as follows:

- Both the listener and generic dispatcher always exist on the same node.

- A GIOP configured dispatcher cannot exist.

  Note: If a GIOP configured dispatcher does exist, the listener will redirect the request, rather than hand off the request, to the configured dispatcher.

The advantage for dynamically registering a listener endpoint is that you do not need to restart your database for this listener to be IIOP enabled. The listening endpoint is active immediately.

For full details on the `regep` tool, see the Oracle8i Java Tools Reference Guide.

#### Example 3-1 Dynamically Registering a LIstener at Port 2241

The following line dynamically registers a listener on the `SUNDB` host on endpoint port number 2241. This tool logs on to the `SUNDB` host.

    regep -pres oracle.aurora.server.SGiopServer -host sundb -port 2241

### Direct Dispatcher Connection

If you want your client to go to a dispatcher directly, bypassing the listener, you direct your client to the dispatcher's port number. Do one of the following to discover the dispatcher's port number:

- Configure a port number for the dispatcher by adding the ADDRESS parameter that includes a port number.

- Discover the port assigned to the dispatcher by invoking `lsnrctl` `service`.

If you choose to configure the port number, the following shows the syntax:

    mts_dispatchers="(address=(protocol=tcp | tcps)

    	(host=<server_host>)(port=<port>))

    	(presentation=oracle.aurora.server.SGiopServer)"

The attributes are described below:

Attribute | Description
--- | ---
ADDRESS (ADD or ADDR) | Specifies the network address that the dispatchers will listen on. The network address may include either the TCP/IP (TCP) or the TCP/IP with SSL (TCPS) protocol, the host name of the server, and a GIOP listening port, which may be any port you choose that is not already in use.
PRESENTATION (PRE or PRES) | Enables support for GIOP. Supply the following value for a GIOP presentation: `oracle.aurora.server.SGiopServer` for session-based GIOP connections. This presentation is valid for TCP/IP and TCP/IP with SSL.

The client supplies the port number on its URL, as follows:

    session_iiop://<hostname>/:<portnumber>

Notice that the URL excludes a SID or service name. The dispatcher does not need the SID instance or service name because it is a directed request.

### Configuring SSL for EJB and CORBA

Oracle8i also supports the use of authentication data such as certificates and private keys required for use by SSL in combination with GIOP. To configure your transport to be SSL-enabled with GIOP, do the following:

1. Enable the MTS_DISPATCHERS to be SSL-enabled.

2. Specify the SSL wallet to be used when configuring both the listener and database.

3. Configure the listener to accept SSL.

The following sections detail how to accomplish these three steps.

#### Enable the MTS_DISPATCHERS for SSL

You must edit the database initialization file to add an SSL-enabled dispatcher. Uncomment the MTS_DISPATCHERS parameter in the database initialization file that defines the TCPS port. During installation, the Database Configuration Assistant always includes a commented out line for SSL TCP/IP. This line is as follows:

    mts_dispatchers="(protocol=tcps)(presentation=oracle.aurora.server.SGiopServer)"

#### Configure the Wallet Location through Net8 Assistant

Modify the listener to accept SSL requests on port 2482.

1. Start Net8 Assistant.

   - On UNIX, run `netasst` at `$ORACLE_HOME/bin`.

   - On Windows NT, choose Start > Programs > Oracle - HOME_NAME > Network Administration > Net8 Assistant.

2. In the navigator pane, expand Local > Profile.

3. From the pull-down list, select Oracle Advanced Security > SSL.

   This brings you to the listening port panel, as shown in Figure 3-6.

   #### Figure 3-6 IIOP listening port configuration

4. On the "Configure SSL for:" line, select the "Server" radio button.

5. Under "Wallet Directory", enter the location for the wallet.

6. If you desire a certain SSL version, choose the appropriate version on the SSL version pulldown list.

7. If you want the client to authenticate itself by providing certificates, select the "Require Client Authentication" checkbox.

8. Choose File > Save Network Configuration.

These steps will add wallet and SSL configuration information into both the listener and database configuration files. The SSL wallet location must be specified in both the listener and database configuration files. Both entities must locate the wallet for certificate handshake capabilities.

##### The `listener.ora` file:

    ssl_client_authentication=false
    ssl_version=undetermined

The default is for the database to authenticate the client. If you want the listener to authenticate the client, change the `ssl_client_authentication` parameter to true.

##### The database's `sqlnet.ora` file:

    ssl_client_authentication=true
    ssl_version=0
    sqlnet.crypto_seed=<seed_info>

If you did not request client authentication, the `ssl_client_authentication` parameter will be false. The default value is for client authentication to be true. In addition, you can specify a specific SSL version number, such as 3.0, in the `ssl_version` parameter. The `ssl_version` value of 0 means that the version is undetermined and will be agreed upon during handshake.

##### Within both the listener's `listener.ora` and database's `sqlnet.ora` files, the wallet location is specified:

    oss.source.my_wallet=

       (source=
          (method=file)
          (method_data=
            (directory=wallet_location)))

The Oracle Advanced Security Administrator's Guide describes how to set up the SSL wallet with the appropriate certificates.

#### Configure an SSL-Enabled Listener through Net8 Assistant

1. Back in the navigator pane, expand Local > Listener.

   This brings you to the listener location panel, as shown in Figure 3-2.

   #### Figure 3-7 IIOP listening port configuration

2. Select a listener.

3. From the list in the right pane, select Listening Locations. If none of the current listening addresses are feasible for your SSL listening address, you can add a new address by clicking on the "Add Address" button.

4. Select the TCP/IP with SSL protocol from the Protocol list.

5. Enter the host name of the database in the Host field.

6. Enter port 2482 in the Port field.

7. Click "Dedicate this endpoint to IIOP connections".

8. Choose File > Save Network Configuration.

This places the following in the `listener.ora` file: it modifies the listener to specify TCPS --instead of TCP--as the protocol with port number 2482. The following shows an example of an SSL-enabled listener on the `sales-server` host.

    listener=
      (description_list=
       (description=
          (address=(protocol=tcps)(host=sales-server)(port=2482))))
          (protocol_stack=
            (presentation=giop)
            (session=raw)))

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index