3
Configuring IIOP Applications

Configuring IIOP-based applications, whether EJB or CORBA applications, involves configuring the appropriate listener and dispatcher for session-based IIOP communications. The process for configuring IIOP-based applications can include both database and network configuration. These elements are discussed in the sections below:

• Overview

• Oracle9i Database Templates For Default Configuration

• Advanced Configuration

Overview

Clients access EJB and CORBA applications in the database over an Internet Inter-Orb Protocol (IIOP) connection. IIOP is an implementation of General Inter-Orb Protocol (GIOP) over TCP/IP. All CORBA or EJB connections with the database must have IIOP configured on the dispatcher and the Oracle Net Services listener. The database dispatcher and Oracle Net Services listener are automatically configured, during installation, to accept IIOP requests. See Oracle9i Database Templates For Default Configuration for more information.

Note: For security concerns, you must decide if your IIOP connection will be Security Socket Layer (SSL) enabled. See "Using the Secure Socket Layer" for information on SSL. See "SSL Configuration for EJB and CORBA" for information on how to configure SSL.

Oracle9i Database Templates For Default Configuration

During the database template setup, you can choose the Oracle JVM option (as Figure 3-1 shows). This ensures that the Oracle JVM is installed and configured for you. You automatically receive a configuration for a shared server database with session-based IIOP connections through a Oracle Net Services listener, using non-SSL TCP/IP.

Figure 3-1 Choosing the Oracle JVM Option

Text description of the illustration jvm.gif

After the Oracle9i installation is complete, the following line is added to your database initialization file:

dispatchers="(protocol=tcp)(presentation=oracle.aurora.server.SGiopServer)"

This configures a dispatcher that is GIOP-enabled. If, instead, you install the Advanced Security Option and you want the SSL-based TCP/IP connection, then edit your database initialization file to replace the previous line by removing the hash mark (#) from the following line:

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

Note: The (protocol=tcps) attribute identifies the connection as SSL-enabled.

In addition, an Oracle Net Services listener is configured with both a TTC and IIOP listening endpoints. TTC listening endpoints are required for Oracle Net Services requests; IIOP listening endpoints are required for IIOP requests. If you require an SSL-enabled IIOP listening endpoint, you must add this endpoint to your existing listener. See SSL Configuration for EJB and CORBA for more information.

After installation, you must unlock the following three users:

• AURORA$JIS$UTILITY$

• OSE$HTTP$ADMIN

• AURORA$ORB$UNAUTHENTICATED

By default, all database users are locked. These three users must be unlocked by a system administrator in order for Servlets, EJB, or CORBA applications to work correctly.

Once the installation is completed, both the dispatcher and listener are ready for IIOP requests. Your client application must know the host and port number for the listener that it is directing its request towards. You can discover what port the listener is listening on through the Oracle Net Services lsnrctl tool.

The client directs its request to a URL that includes the host and port, which identifies the listener, and either the SID or database service name, which identifies the database. The following shows the syntax for this request:

sess_iiop://<hostname>/:<portnumber>/:<SID | service_name>

Advanced Configuration

Both the listener and dispatcher are configured automatically for IIOP requests. However, you may have an environment that requires changing the default configuration. This section educates you on how listeners and dispatchers work together and how you can modify that behavior.

• Overview of Listeners and Dispatchers

• Handling Incoming Requests

• Configuring The Dispatcher Through Editing Initialization Files

• Configuring the Listener

• SSL Configuration for EJB and CORBA

Overview of Listeners and Dispatchers

During installation, the listeners and dispatchers were configured for you in a manner where all IIOP requests are redirected from the listener to the dispatcher. Each dispatcher listens on a random port number assigned to it when it is initiated. Each port number is guaranteed to be unique per database instance. The listener is configured with two listening endpoints: one for TTC requests, and one for IIOP requests.

Note: However, 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.

Once configured, the listeners redirect all IIOP requests to the dispatchers as shown in Figure 3-2.

Figure 3-2 Listener and Dispatcher Interaction

Text description of the illustration config2.gif

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.

Handling Incoming Requests

When the database starts up, all dispatchers register with all listeners configured within the same database initialization file. This is how the listeners know where each dispatcher is and the port that the dispatcher listens on. When an IIOP client invokes a request, the listener will either redirect the request to a GIOP-specific dispatcher, or hand off to a generic dispatcher.

Both methods are discussed in the following sections:

• Redirect to GIOP Dispatcher

• Hand Off to Generic Dispatcher

Redirect to GIOP Dispatcher

A client sends a request to the listener (by designating the host and port for the listener in the sess_iiop URL). The listener recognizes the IIOP protocol and redirects the request to a registered GIOP dispatcher. This is the default behavior that is configured during installation.

Figure 3-3 IIOP Listener Redirect to GIOP Dispatcher

Text description of the illustration iiopdsp.gif

1. The GIOP dispatcher registers itself with the listener.

2. The IIOP client--an EJB or CORBA client--invokes a method, giving the address (host, port, and SID) of the listener. You can determine the port number of the listener through the lsnrctl tool.

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

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

Handoff is when a listener forfeits the socket to the dispatcher when an incoming request arrives. This can only occur when the following is true:

• Both the listener and the dispatcher exist on the same node.

• No GIOP dispatcher is configured. That is, the dispatchers configuration line in the database initialization file has been removed. Thus, a generic dispatcher is used.

• A listener has been configured to receive IIOP requests. That is, it contains an IIOP listening endpoint. The Oracle JVM installation creates an IIOP listening endpoint on a listener. Although, you can also dynamically configure an IIOP listening endpoint on an existing listener through the dynamic registration tool, regep. See "Dynamic Listener Endpoint Registration" for more information.

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

Figure 3-4 Hand Off to Dispatcher

Text description of the illustration noniiop.gif

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

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.

Configuring The Dispatcher Through Editing Initialization Files

The database supports incoming requests through a presentation. Note that the presentation discussed in this chapter is not the same as the presentation layer in the OSI model. Both the listener and the dispatcher accept incoming network requests based upon the presentation that is configured. For IIOP, you configure a GIOP presentation.

You configure the IIOP connection in the database initialization file by modifying the PRESENTATION attribute of the DISPATCHERS parameter. To configure an IIOP connection within the database, manually edit the database initialization file.

The following is the syntax for the DISPATCHERS parameter:

dispatchers="(protocol=tcp | tcps) 

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

The attributes for the DISPATCHER are described below:

Attribute	Description
PROTOCOL (PRO or PROT)	Specifies the TCP/IP or TCP/IP with SSL protocol, for which the dispatcher will generate a listening endpoint. Valid values: TCP (for TCP/IP) or TCPS (for TCP/IP with SSL)
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.

Note: If you configure several DISPATCHERS within your database initialization file, then each dispatcher definition must follow the other. Do not define any other configuration parameters between the DISPATCHER definitions.

For example, to configure a shared server for session-based IIOP connections through the listener, using non-SSL TCP/IP, add the following within your database initialization file:

dispatchers="(protocol=tcp)(presentation=oracle.aurora.server.SGiopServer)"

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:

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 on which the dispatchers will listen. 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 the Listener

You can configure listeners either dynamically through a tool or statically by modifying the configuration files. Both methods are explained below:

• Dynamic Listener Endpoint Registration

• Static Configuration of the Oracle Net Services Listener

• Displaying Current Listening Endpoints

Dynamic Listener Endpoint Registration

In order for a listener to receive an IIOP incoming request, the listener must have an IIOP endpoint registered. You can register any type of listening endpoint through the dynamic registration tool, regep.

The advantage of dynamically registering a listener endpoint is that you do not need to restart your database for the listener to be IIOP enabled. The listening endpoint is active immediately. For full details on the regep tool, see the Oracle9i Java Tools Reference.

Note: If you statically configure a listener with IIOP endpoints, you must restart your database. See "Static Configuration of the Oracle Net Services Listener" for more information.

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

Static Configuration of the Oracle Net Services Listener

If you statically configure a listener, you need to configure separate ports as listening endpoints for both TTC and IIOP connections. The default listener that is configured by the Oracle JVM install is configured for both TTC and IIOP listening endpoints.

You can configure each listener to listen on a well-known port number, and the client communicates with the listener using this port number. To configure the listener manually, you must modify the listener's DESCRIPTION parameter within the listener.ora file with a GIOP listening address. The following example configures a GIOP presentation for non-SSL TCP/IP with port number 2481. You use port 2481 for non-SSL and port 2482 for SSL.

For GIOP, the PROTOCOL_STACK parameter is added to the DESCRIPTION when configuring an IIOP connection to sales-server:

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

The following table gives the definition for each of the GIOP parameters:

Attribute	Description
PROTOCOL_STACK	Identifies the presentation and session layer information for a connection.
(PRESENTATION=GIOP)	Identifies a presentation of GIOP for IIOP clients. GIOP supports oracle.aurora.server.SGiopServer, using TCP/IP.
(SESSION=RAW)	Identifies the session layer. There is no specific session layer for IIOP clients.
(ADDRESS=...)	Specifies a listening address that uses TCP/IP on either port 2481 for non-SSL, or port 2482 for SSL. If non-SSL, define the protocol as TCP; for SSL, define the protocol as TCPS.

After configuration, the client directs its request to a URL that includes the host and port, which identifies the listener, and either the SID or database service name, which identifies the database. The following shows the syntax for this request:

sess_iiop://<hostname>/:<portnumber>/:<SID | service_name>

Taking the configuration shown in the listener.ora file above, your URL would contain the following values:

sess_iiop://sales-server/:2481/:orcl

Displaying Current Listening Endpoints

Whether the listening endpoints are registered dynamically or statically, you can display the current endpoints through the lsnrctl command, as follows:

% lsnrctl
> set display to normal
> status

SSL Configuration for EJB and CORBA

Oracle9i 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:

Note: The SSL listening endpoint is automatically registered with a listener. To verify that an SSL endpoint is registered with your listener, follow the directions given in "Displaying Current Listening Endpoints".

1. Enable the DISPATCHERS to be SSL-enabled.

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

The following sections explain how to accomplish these steps.

Enable the DISPATCHERS for SSL

You must edit the database initialization file to add an SSL-enabled dispatcher. Uncomment the 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:

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

Configure the Wallet Location through Oracle Net Manager

Modify the listener to accept SSL requests on port 2482.

1. Start Oracle Net Manager.
   • On UNIX, run netmgr at $ORACLE_HOME/bin.

   • On Windows NT, choose Start > Programs > Oracle - HOME_NAME > Network Administration > Oracle Net Manager.

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-5.

   Figure 3-5 IIOP listening port configuration

   
   
   Text description of the illustration ssl2.gif
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. You must specify the SSL wallet location 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 

Both of these parameters apply to the database and to the listener.

The ssl_client_authentication parameter is defaulted to FALSE. The value for this parameter is defined, as follows:

• FALSE--The server-side always authenticates itself to the client using a certificate. The client only authenticates itself to the server with username and password.

• TRUE--Both the client and server authenticate to each other using certificates.

The sqlnet.ora database file:

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

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. SSL version 2.0 is not supported.

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.