|Oracle9i Enterprise JavaBeans Developer's Guide and Reference
Release 1 (9.0.1)
Part Number A90188-01
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:
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.
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.
After the Oracle9i installation is complete, the following line is added to your database initialization file:
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:
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:
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
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:
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.
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.
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.
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:
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.
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:
dispatchersconfiguration line in the database initialization file has been removed. Thus, a generic dispatcher is used.
regep. See "Dynamic Listener Endpoint Registration" for more information.
Figure 3-4 shows the dispatcher and listener combination in a hand-off environment.
The client communicates directly with the dispatcher from this point on. The client is never made aware that the socket was handed off.
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:
The attributes for the DISPATCHER are described below:
PROTOCOL (PRO or PROT)
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:
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:
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:
If you choose to configure the port number, the following shows the syntax:
dispatchers="(address=(protocol=tcp | tcps)
The attributes are described below:
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.
Enables support for GIOP. Supply the following value for a GIOP presentation:
The client supplies the port number on its URL, as follows:
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.
You can configure listeners either dynamically through a tool or statically by modifying the configuration files. Both methods are explained below:
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,
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.
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.
The following line dynamically registers a listener on the
SUNDB host on endpoint port number 2241. This tool logs on to the
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
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:
Identifies the presentation and session layer information for a connection.
Identifies a presentation of GIOP for IIOP clients. GIOP supports
Identifies the session layer. There is no specific session layer for IIOP clients.
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:
Taking the configuration shown in the listener.ora file above, your URL would contain the following values:
Whether the listening endpoints are registered dynamically or statically, you can display the current endpoints through the
lsnrctl command, as follows:
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:
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".
The following sections explain how to accomplish these steps.
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:
Modify the listener to accept SSL requests on port 2482.
This brings you to the listening port panel, as shown in Figure 3-5.
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.
Both of these parameters apply to the database and to the listener.
ssl_client_authentication parameter is defaulted to FALSE. The value for this parameter is defined, as follows:
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.
sqlnet.orafiles, the wallet location is specified:
The Oracle Advanced Security Administrator's Guide describes how to set up the SSL wallet with the appropriate certificates.