|Oracle8i JDBC Developer's Guide and Reference
Release 3 (8.1.7)
Part Number A83724-01
This section describes some of the basics of working with Oracle JDBC applets, which must use the JDBC Thin driver so that an Oracle installation is not required on the client. The Thin driver connects to the database with TCP/IP protocol.
Aside from having to use the Thin driver, and being mindful of applet connection and security issues, there is essentially no difference between coding a JDBC applet and a JDBC application. There is also no difference between coding for a JDK 1.2.x browser or a JDK 1.1.x browser, other than general JDK 1.1.x to 1.2.x migration issues discussed in "Migration from JDK 1.1.x to JDK 1.2.x".
This section describes what you must do for the applet to connect to a database, including how to use the Oracle8 Connection Manager or signed applets if you are connecting to a database not running on the same host as the Web server. It also describes how your applet can connect to a database through a firewall. The section concludes with how to package and deploy the applet.
The following topics are covered:
For general information about connecting to the database, see "Open a Connection to a Database".
To see a sample applet, refer to "Sample Applet".
The most common task of an applet using the JDBC driver is to connect to and query a database. Because of applet security restrictions, unless particular steps are taken an applet can open TCP/IP sockets only to the host from which it was downloaded (this is the host on which the Web server is running). This means that without these steps, your applet can connect only to a database that is running on the same host as the Web server.
If your database and Web server are running on the same host, then there is no issue and no special steps are required. You can connect to the database as you would from an application.
As with connecting from an application, there are two ways in which you can specify the connection information to the driver. You can provide it in the form of
host:port:sid or in the form of a TNS keyword-value syntax.
For example, if the database to which you want to connect resides on host
prodHost, at port
1521, and SID
ORCL, and you want to connect with user name
scott with password
tiger, then use either of the two following connect strings:
String connString="jdbc:oracle:thin:@prodHost:1521:ORCL"; conn = DriverManager.getConnection(connString, "scott", "tiger");
using TNS keyword-value syntax:
String connString = "jdbc:oracle:thin:@(description=(address_list= (address=(protocol=tcp)(port=1521)(host=prodHost))) (connect_data=(sid=ORCL)))"; conn = DriverManager.getConnection(connString, "scott", "tiger");
If you use the TNS keyword-value pair to specify the connection information to the JDBC Thin driver, then you must declare the protocol as TCP.
However, a Web server and an Oracle database server both require many resources; you seldom find both servers running on the same machine. Usually, your applet connects to a database on a host other than the one on which the Web server runs. There are two possible ways in which you can work around the security restriction:
These options are discussed in the next section, "Connecting to a Database on a Different Host Than the Web Server".
If you are connecting to a database on a host other than the one on which the Web server is running, then you must overcome applet security restrictions. You can do this by using either the Oracle8 Connection Manager or signed applets.
The Oracle8 Connection Manager is a lightweight, highly-scalable program that can receive Net8 packets and re-transmit them to a different server. To a client running Net8, 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 Net8 packets to an Oracle server running on a different host.
Figure 18-1 illustrates the relationship between the applet, the Oracle8 Connection Manager, and the database.
Using the Oracle8 Connection Manager requires two steps, described immediately below:
There is also discussion of how to connect using multiple connection managers.
You must install the Connection Manager, available on the Oracle8 distribution media, onto the Web server host. You can find the installation instructions in the Net8 Administrator's Guide.
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 this 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) )
Note that the Java Net8 version inside the JDBC Thin driver does not have authentication service support. This means that the
AUTHENTICATION_LEVEL configuration parameter in the
CMAN.ORA file must be set to
After you create the file, start the Oracle8 Connection Manager at the operating system prompt with this command:
To use your applet, you must now write the connect string for it.
This section describes how to write the connect string in your applet so that the applet connects to the Connection Manager, and the Connection Manager connects with the database. In the connect string, 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 18-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 connect string in TNS keyword-value format:
Connection conn = DriverManager.getConnection ("jdbc:oracle:thin:" + "@(description=(address_list=" + "(address=(protocol=tcp)(host=webHost)(port=1610))" + "(address=(protocol=tcp)(host=oraHost)(port=1521)))" + "(source_route=yes)" + "(connect_data=(sid=orcl)))", "scott", "tiger");
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.
Notice that you can also write the same connect string in this format:
String connString = "jdbc:oracle:thin:@(description=(address_list= (address=(protocol=tcp)(port=1610)(host=webHost)) (address=(protocol=tcp)(port=1521)(host=oraHost))) (connect_data=(sid=orcl)) (source_route=yes))"; Connection conn = DriverManager.getConnection(connString, "scott", "tiger");
When your applet uses a connect string such as the one above, it will behave exactly as if it were connected directly to the database on the host
For more information on the parameters that you specify in the connect string, see the Net8 Administrator's Guide.
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. See the Net8 Administrator's Guide for more information about
In either a JDK 1.2.x-based browser or a JDK 1.1.x-based 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:
If you are using Netscape, then your code would include a statement like this:
This site provides information on obtaining and installing a certificate.
For more information on writing applet code that asks for permissions, see Netscape's Introduction to Capabilities Classes at:
For information about the Java Security API, including signed applet examples under JDK 1.2.x and 1.1.x, see the following Sun Microsystems site:
Under normal circumstances, an applet that uses the JDBC Thin driver cannot access the database through a firewall. In general, the purpose of a firewall is to prevent unauthorized clients from reaching the server. In the case of applets trying to connect to the database, the firewall prevents the opening of a TCP/IP socket to the database.
Firewalls are rule-based. They have a list of rules that define which clients can connect, and which cannot. Firewalls compare the client's hostname with the rules, and based on this comparison, either grant the client access, or not. If the hostname lookup fails, the firewall tries again. This time, the firewall extracts the IP address of the client and compares it to the rules. The firewall is designed to do this so that users can specify rules that include hostnames as well as IP addresses.
You can solve the firewall issue by using a Net8-compliant firewall and connection strings that comply with the firewall configuration. Net8-compliant firewalls are available from many leading vendors; a more detailed discussion of these firewalls is beyond the scope of this manual.
An unsigned applet can access only the same host from which it was downloaded. In this case, the Net8-compliant firewall must be installed on that host. In contrast, a signed applet can connect to any host. In this case, the firewall on the target host controls the access.
Connecting through a firewall requires two steps, described in the following sections:
The instructions in this section assume that you are running a Net8-compliant firewall.
Java applets do not have access to the local system--that is, they cannot get the hostname or environment variables locally--because of security limitations. 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 two things to the firewall's list of rules:
__jdbc__" never appears in the firewall's 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 Oracle's JDBC Thin driver will be able to go through your firewall.
By not including the Thin driver's hostname, the firewall is forced to do an IP address lookup and base its access decision on the IP address, instead of the hostname.
To write a connect string that allows 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 connect string:
Connection conn = DriverManager.getConnection ("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=(sid=orcl)))", "scott", "tiger");
To connect through a firewall, you cannot specify the connection string in
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.
Notice that you can also write the preceding connect string in this 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=(sid=orcl)) (source_route=yes))"; Connection conn = DriverManager.getConnection(connString, "scott", "tiger");
When your applet uses a connect string similar to the one above, it will behave as if it were connected to the database on host
For more information on the parameters used in the above example, see the Net8 Administrator's Guide. For more information on how to configure a firewall, please see your firewall's documentation or contact your firewall vendor.
After you have coded your applet, you must package it and make it available to users. To package an applet, you will need your applet class files and the JDBC driver class files (these will be contained in either
classes12.zip, if you are targeting a browser that incorporates a JDK 1.2.x version, or
classes111.zip, for a browser incorporating a JDK 1.1.x version).
Follow these steps:
classes111.zip) to an empty directory.
If your applet will connect to a database with a non-
US7ASCII and non-
WE8ISO8859P1 character set, then also move the
nls_charset11.zip file to the same directory.
classes111.zip(and required class files from
nls_charset11.zipif the applet requires NLS)
Additionally, if you are using
DatabaseMetaData entry points in your applet, include the
oracle/jdbc/driver/OracleDatabaseMetaData.class file. Note that this file is very large and might have a negative impact on performance. If you do not use
DatabaseMetaData methods, omit this file.
You can now make the applet available to users. One way to do this is to add the
APPLET tag to the HTML page from which the applet will be run. For example:
<APPLET WIDTH=500 HEIGHT=200 CODE=JdbcApplet ARCHIVE=JdbcApplet.zip CODEBASE=Applet_Samples </APPLET>
You can find a description of the
HEIGHT parameters in the next section.
APPLET tag specifies an applet that runs in the context of an HTML page. The
APPLET tag can have these parameters:
HEIGHT to specify the name of the applet and its location, and the height and width of the applet display area. These parameters are described in the following sections.
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
WIDTH parameters to specify the size, measured in pixels. This size should not count any windows or dialogs that the applet opens.
APPLET tag must also specify the name of the file that contains the applet's compiled Applet subclass--specify the file name with the
CODE parameter. Any path 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 Applet's compiled applet subclass:
If you use this form of the
CODE tag, then the classes for the applet and the classes for the JDBC Thin driver must be in the same directory as the HTML page.
Notice that in the
CODE specification, you do not include the file name extension "
CODEBASE parameter is optional and specifies the base URL of the applet; that is, the name of the directory that contains the applet's code. If it is not specified, then the document's URL 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
The entry CODEBASE="." indicates that the applet resides in the current directory (
my_Dir). If the value of
codebase was set to
Applet_Samples, for example:
This would indicate that the applet resides in the
ARCHIVE parameter is optional and specifies the name of the archive file (either a
.jar file), if applicable, that contains the applet classes and resources the applet needs. Oracle recommends using a
.zip file or
.jar file, which saves many extra roundtrips to the server.
.jar) 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