6 Features Specific to JDBC Thin

Using the Oracle Connection Manager

The Oracle Connection Manager is a lightweight, highly-scalable program that can receive Oracle Net packets and re-transmit them to a different server. To a client running Oracle Net, the Connection Manager looks exactly like a database server. An applet that uses the JDBC Thin driver can connect to a Connection Manager running on the Web server host and have the Connection Manager redirect the Oracle Net packets to an Oracle server running on a different host.

Figure 6-1 illustrates the relationship between the applet, the Oracle Connection Manager, and the database.

Figure 6-1 Applet, Connection Manager, and Database Relationship

Description of "Figure 6-1 Applet, Connection Manager, and Database Relationship "

Using the Oracle Connection Manager requires two steps:

• Install and run the Connection Manager.

• Write the connection string that targets the Connection Manager.

Installing and Running the Oracle Connection Manager

You must install the Connection Manager, available on the Oracle distribution media, onto the Web server host.

On the Web server host, create a CMAN.ORA file in the ORACLE_HOME/NET8/ADMIN directory. The options you can declare in a CMAN.ORA file include firewall and connection pooling support.

Here is an example of a very simple CMAN.ORA file. Replace web-server-host with the name of your Web server host. The fourth line in the file indicates that the Connection Manager is listening on port 1610. You must use the same port number in your connect string for JDBC.

cman = (ADDRESS_LIST = 
       (ADDRESS = (PROTOCOL=TCP) 
       (HOST=web-server-host)
       (PORT=1610)))

cman_profile = (parameter_list = 
       (MAXIMUM_RELAYS=512) 
       (LOG_LEVEL=1) 
   (TRACING=YES) 
       (RELAY_STATISTICS=YES) 
       (SHOW_TNS_INFO=YES) 
       (USE_ASYNC_CALL=YES) 
       (AUTHENTICATION_LEVEL=0)
       )

After you create the file, start the Connection Manager at the operating system prompt with the following command:

cmctl start

To use your applet, you must now write the connect string for it.

Writing the URL that Targets the Connection Manager

The following text describes how to write the URL in your applet, so that the applet connects to the Connection Manager and the Connection Manager connects with the database. In the URL, you specify an address list that lists the protocol, port, and name of the Web server host on which the Connection Manager is running, followed by the protocol, port, and name of the host on which the database is running.

The following example describes the configuration illustrated in Figure 6-1. The Web server on which the Connection Manager is running is on host webHost and is listening on port 1610. The database to which you want to connect is running on host oraHost, listening on port 1521, and SID ORCL. You write the URL in TNS keyword-value format:

String myURL = 
   "jdbc:oracle:thin:@(description=(address_list=
   (address=(protocol=tcp)(port=1610)(host=webHost))
   (address=(protocol=tcp)(port=1521)(host=oraHost)))
   (connect_data=(INSTANCE_NAME=orcl))
   (source_route=yes))";
   OracleDataSource ods = new OracleDataSource();
   ods.setURL(myURL);
   ods.setUser("scott");
   ods.setPassword("tiger");
   Connection conn = ods.getConnection();

The first element in the address_list entry represents the connection to the Connection Manager. The second element represents the database to which you want to connect. The order in which you list the addresses is important.

When your applet uses a URL, such as the preceding one, it will function exactly as if it were connected directly to the database on the host oraHost.

Connecting through Multiple Connection Managers

Your applet can reach its target database even if it first has to go through multiple Connection Managers. For example, if the Connection Managers form a proxy chain. To do this, add the addresses of the Connection Managers to the address list, in the order that you plan to access them. The database listener should be the last address on this list.

Using Signed Applets

In a Java Development Kit (JDK) 1.2.x-based or later browser, an applet can request socket connection privileges and connect to a database running on a different host than the Web server host. In Netscape 4.0, you perform this by signing your applet, that is, writing a signed applet. You must follow these steps:

1. Sign the applet. For information on the steps you must follow to sign an applet, refer to the Signed Applet Example at:

   http://java.sun.com

2. Include applet code that asks for appropriate permission before opening a socket.

   If you are using Netscape, then your code would include a statement like this:

   netscape.security.PrivilegeManager.enablePrivilege("UniversalConnect"); 
   OracleDataSource ods = new OracleDataSource();
   ods.setURL("jdbc:oracle:thin:scott/tiger@dlsun511:1721:orcl");
   Connection conn = ods.getConnection();
   

3. You must obtain an object-signing certificate. Refer to the Object-Signing Resources page at:

   http://developer.netscape.com/software/signedobj/index.html

This site provides information on obtaining and installing a certificate.

For more information on writing applet code that asks for permissions, refer to Introduction to Capabilities Classes at:

http://developer.netscape.com/docs/manuals/signedobj/capabilities/contents.htm

For information about the Java Security API, including signed applet examples, see the following Sun Microsystems site:

http://java.sun.com/security

Configuring a Firewall for Applets that use the JDBC Thin Driver

The instructions in this section assume that you are running an Oracle Net-compliant firewall.

Java applets do not have access to the local system. Because of the security limitations, applets cannot access the hostname or environment variables on the local system. As a result, the JDBC Thin driver cannot access the hostname on which it is running. The firewall cannot be provided with the hostname. To allow requests from JDBC Thin clients to go through the firewall, you must do the following to the list of firewall rules:

• Add the IP address, and not the hostname, of the host on which the JDBC applet is running.

• Ensure that the hostname, "__jdbc__", never appears in the firewall rules. This hostname has been hard-coded as a false hostname inside the driver to force an IP address lookup. If you do enter this hostname in the list of rules, then every applet using the JDBC Thin driver will be able to go through your firewall.

Writing a URL to Connect through a Firewall

To write a URL that enables you to connect through a firewall, you must specify the name of the firewall host and the name of the database host to which you want to connect.

For example, if you want to connect to a database on host oraHost, listening on port 1521, with SID ORCL, and you are going though a firewall on host fireWallHost, listening on port 1610, then use the following URL:

OracleDataSource ods = new OracleDataSource();
ods.setURL("jdbc:oracle:thin:" +
      "@(description=(address_list=" +
      (address=(protocol=tcp)(host=<firewall-host>)(port=1610))" +
      "(address=(protocol=tcp)(host=oraHost)(port=1521)))" +
      "(source_route=yes)" +
      "(connect_data=(SERVICE_NAME=orcl)))");
);
ods.setUser("scott");
ods.setPassword("tiger");
Connection conn = ods.getConnection();

String connString =
   "jdbc:oracle:thin:@example.us.oracle.com:1521:orcl";

OracleDataSource ods = new OracleDataSource();
ods.setURL(connString);
ods.setUser("scott");
ods.setPassword("tiger");
Connection conn = ods.getConnection();

The first element in the address_list represents the connection to the firewall. The second element represents the database to which you want to connect. Note that the order in which you specify the addresses is important.

You can also write the preceding URL in the following format:

String connString = 
      "jdbc:oracle:thin:@(description=(address_list=
      (address=(protocol=tcp)(port=1600)(host=fireWallHost))
      (address=(protocol=tcp)(port=1521)(host=oraHost)))
      (connect_data=(INSTANCE_NAME=orcl))
      (source_route=yes))";
OracleDataSource ods = new OracleDataSource();
ods.setURL(connString);
ods.setUser("scott");
ods.setPassword("tiger");
Connection conn = ods.getConnection();

When your applet uses a URL similar to the preceding URL, it will behave as if it were connected to the database on host oraHost.

CODE, HEIGHT, and WIDTH

The HTML page that runs the applet must have an APPLET tag with an initial width and height to specify the size of the applet display area. You use the HEIGHT and WIDTH attributes to specify the size, measured in pixels. This size should not count any windows or dialogs that the applet opens.

The APPLET tag must also specify the name of the file that contains the compiled applet. Specify the file name with the CODE attribute. Any path specified must be relative to the base URL of the applet. The path cannot be absolute.

In the following example, JdbcApplet.class is the name of the compiled applet:

<APPLET CODE="JdbcApplet" WIDTH=500 HEIGHT=200> 
</APPLET>

If you use this form of the CODE attribute, then the classes for the applet and the JDBC Thin driver must be in the same directory as the HTML page.

CODEBASE

The CODEBASE attribute is optional. It specifies the base URL of the applet, that is, the name of the directory that contains the code of the applet. If it is not specified, then the URL of the document is used. This means that the classes for the applet and the JDBC Thin driver must be in the same directory as the HTML page. For example, if the current directory is my_Dir:

<APPLET WIDTH=500 HEIGHT=200 CODE=JdbcApplet CODEBASE="."
</APPLET>

The attribute, CODEBASE=".", indicates that the applet resides in the current directory, my_Dir.

Now, consider that the value of CODEBASE is set to Applet_Samples, as follows:

<APPLET WIDTH=500 HEIGHT=200 CODE=JdbcApplet CODEBASE="Applet_Samples"
</APPLET>

This would indicate that the applet resides in the my_Dir/Applet_Samples directory.

ARCHIVE

The ARCHIVE attribute is optional. It specifies the name of the archive file that contains the applet classes and resources the applet needs. Oracle recommends using an archive file, which saves many extra round-trips to the server.

The archive file will be preloaded. If you have more than one archive in the list, separate them with commas. In the following example, the class files are stored in the archive file, JdbcApplet.zip:

<APPLET CODE="JdbcApplet" ARCHIVE="JdbcApplet.zip" WIDTH=500 HEIGHT=200>
</APPLET>