Oracle Forms Server 6i 

GetClientInfo JavaBean

Author:  Oracle Forms Product Management Team
Creation Date:  03-NOV-1999
Last Updated:  20-FEB-2000
Version:  1.0
Copyright (C) 2000 Oracle Corporation
All Rights Reserved


Change Record

Date Author Version Comments
03-NOV-1999 PM Team 0.5 initial creation
20-FEB-1999  PM Team 1.0 update for 6i release


Overview

This Oracle Forms 6i JavaBean component provides an example of the type of code and infrastrcuture required to obtain information from the client machine on which the Forms Java applet is running. This information is able to be retrieved from the client and returned to a Form application running on Oracle Forms Server machine. The JavaBean allows the Form to query the client machine to find the name of the user who is logged into the machine*, the hostname of the client machine and the IP address of the client machine. It is possible to further extend the JavaBean to query for other information that is available via the Java runtime engine.

This JavaBean must reside in a signed JAR file at deployment time since it performs an operation that is outside of the Java sandbox for non trusted code. This distribution ships with a signed version of the JAR file as well as some utiltiies that will aid you in signing your own JAR files.

The Distribution

This distribution contains the following directories:
Directory Contents
.\src The Java source files for the JavaBean.
.\classes The compiled classes for the JavaBean that can be used in an Oracle Forms application.  This directory contains a JAR file and also a signed JAR file. The signed JAR file has a .sig suffix.
.\doc The Javadoc generated documentation from the JavaBean source file. This documents the method and attributes used within the JavaBean. Click here to view the documentation. 
.\misc Contains miscellaneous elements required for the JavaBean and to help sign the JAR file used to deploy the application. The JAR file signing utilities have been developed for use on a Windows operating system but should be easily ported to other operating systems. The digital certificate used to sign the JAR file (JavaBean.x509) is also stored in this directory.
.\forms Contains example Forms which use the component and demonstrate how to work with the JavaBean from the Forms environment. 

Deployment

You should perform the follwing steps to install and configure the JavaBean for development and deployment in an Oracle Forms Server application:

        <ARCHIVE = "f60all.jar, getclientinfo.jar.sig">

Using the GetClientInfo JavaBean

The fully qualified name for this JavaBean is oracle.forms.demos.GetClientInfo (note that Java is case sensitive).

This JavaBean must be added to a Form application using the BeanArea item. Place the BeanArea item on a canvas and then set the implementation class property to be the fully qualified name for the GetClientInfo JavaBean. You do not need to add the .class suffix.

The JavaBean must be set to visible in your application otherwise it will not be initialized and therefore will not work. You can hide the JavaBean by making it 1x1 in size and setting the background property to the same color as the canvas on which it is placed.

This JavaBean supports the following properties which can be programatically manipulated to modify the behavior of the Rollover Button.

With Oracle Forms Server 6i, the JavaBean can be directly queried and return data directly to the Form through the use of the GET_CUSTOM_PROPERTY builtin. This builtin will send a predefined property to the JavaBean for which it wishes to know the value. The JavaBean returns the data value directly as the return value of the builtin. There is no need to create and dispatch a CustomEvent to return the data. This is a far simpler approach and will make the use of JavaBeans far easier and more flexible.


PL/SQL Property Parameter Type Usage
USERNAME not required This property is used to indicate to the JavaBean that it should return the value of the USERNAME property to the running Form application.

Forms 6i Usage

username := GET_CUSTOM_PROPERTY(hBean,1,'USERNAME');
HOSTNAME not required This property is used to indicate to the JavaBean that it should return the value of the HOSTNAME property to the running Form application.

Forms 6i Usage

hostname := GET_CUSTOM_PROPERTY(hBean,1,'HOSTNAME');
IPADDRESS not required This property is used to indicate to the JavaBean that it should return the value of the IPADDRESS property to the running Form application.

Forms 6i Usage

username := GET_CUSTOM_PROPERTY(hBean,1,'IPADDRESS');

Running the Sample

The sample form that ships with this distribution uses the GetClientInfo JavaBean. The sample form has no dependencies on a database. To run the sample form you must perform the following steps:

Building the Java Classes

This distrubution contains the Java source code for the JavaBean so you can make any changes you wish to the way the component works for your applications.
Java Source File Notes
GetClientInfo.java The source file for the GetClientInfo JavaBean. It is defined to be in the oracle.forms.demos package. 
Utils.java The source file for the utility methods used by the JavaBean. This utility class contains common functions that can be used by different JavaBeans. 

To compile the GetClientInfo JavaBean you will need to have the following software components installed and configured on your computer :

A batch script (for Windows NT) has been provided in the src directory that will compile the GetClientInfo.java and Utils.java source files into the classes directory. This batch file also recreates the JAR file using the newly compiled classes and regenerates the Javadoc documentation.

To run the batch file the following environment variables must be set:
   
Environment Variable Notes
ORACLE_HOME Specifies the location of the Oracle software installation. In the case where more than one Oracle home exists, it should specify the location where Oracle Forms Server is installed.
JDK_HOME Specifies the location where a Java Development Kit is installed. This should point to the top level directory only.

Signing the JAR File

As always, if you have questions relating specifically to Java security and signing you should check the JavaSoft website for more details.

The GetClientInfo JavaBean performs opererations that are not permitted by the Java sandbox security model for non trusted Java code. This means that the GetClientInfo JavaBean must be signed so that it can be trusted by the client. The getclientinfo.jar.sig file is a pre-signed JAR file containing the GetClientInfo JavaBean. You do not need to perform any additional signing operations if you use the JAR file as is. If you make changes to the Java code then you must recompile the Java classes, place them in a JAR file and then sign the JAR file.

The Java signing model signs objects at the JAR file level. All objects to be signed must be placed in a JAR file and the JAR file itself if then signed using the private key of a Java signing identity. As part of the process of creating the Java signing identity, a digital certificate is created which can be used to validate any JAR file that has been signed by the given signing identity.

Signing JAR files can be a tricky business if you've not done it before. To help with the signing process, a set of batch utilities have been provided that can be used to create the signing identity and then to sign the JAR files.


Signing Utility Notes
cert-maker.bat

This utility will create a Java signing identity, the public and private key pair and the digital certificate. The utility uses a file called certdirective to get information about the identity it is to create and what to place into the digital certificate.

To use the utility create a new subdirectory under the misc directory for the user identity you wish to use (the shipped identity is JavaBean).

Copy the certdirective and signingdiretive file examples from the JavaBean directory into the new subdirectory

Modify the certdirective and signingdirective files to reflect the data for the identity you wish to create

Run the cert-maker.bat file with the name of the identity directory as the first parameter. This will execute the required javakey commands and will result in :

  • A new signing identity being created in your security database.
  • A public/private key pair being created which enables JAR files to be signed.
  • A digital certificate being created which is used by client machines to verify the integrity of a signed JAR file. This certificate needs to be imported into the same Java identity on each client machine that will be using the JAR file.

Remember that anytime you create a new signing identity and sign a JAR file with that identity, the client machines need to create the same identity as a trusted user and must import the identity's digital certificate.

jarfile-signer.bat This utility will sign a given JAR file using a given Java signing identity. The process will result in a new JAR file being created with the .sig suffix appended to the original name.

To sign a JAR file you must have already run the cert-maker.bat utility to create the signing identity.

Run the jarfile-signer.bat file with the name of the Java signing identity you created as the first parameter and the name of the JAR file you wish to have signed (this JAR file does not need to be in this directory but if it is not you must provide the full path to the file).

The jarfile-signer utiliy will execute the required javakey commands and will result in a new JAR file being created in the same directory as the utility with the .sig suffix appended to the origian name.

Dependencies

This JavaBean has been tested with the following software components: