Forms Java Cookie Handler Bean

(c)  Oracle Corporation 2004

Description

Cookies are common for Web based applications to store memorable user data so that they are present the next time you revisit a site. This is seen as a security issue by some, because of the ability to spoof user information, and useful by others. If your application wants to share context information across applications that are coming from a specific Website then cookies are a channel to do this, if no shared database is involved. Be aware of that a cookie always is written in plain ASCII , not adding any encryption to messages. 

Running the generic Forms applet in A browser, downloaded from <host>:<port>/forms\/frmservlet?=<application> doesn't allow you by default to set or read cookies. Using the "Cookie Handler" bean allows your Forms application to read and set Cookie messages from and to the user Browser. Cookie message can be encrypted if the message gets encrypted before the cookie is set. On the way back, after reading the cookie, the message needs to be decrypted again using the same mechanism that was used to encrypt it. This can be an issue if you don't have access to the same encryption algorithm from all applications using the cookie. The Oracle database offers an  encrypt/decrypt facility, the dbms_obfuscation package, which can be accessed by PL/SQL.

When would it make sense to use Cookies in Forms? Coming from client/server your users are used to their local printer when printing an Oracle Reports from Forms. Since the Web is server based you don't know about the user's printer, even if the server knows about the printers network address. Having the user specifying his printer the first time he runs an application and then storing this information in a cookie allows local printing with no additional questions asked. I am sure that you will have your own ideas on how to leverage this functionality that works the same on IE5 and Netscape (note that cookies set i Netscape cannot be read in Internet Explorer).

How does the Bean work

Writing cookies

For your convenience a program unit has been created in the sample file, taking care of building a valid message string and setting the cookie into the browser 

The package "cookie" in the cookie.fmb file contains the following signatures, handling all possible parameter combination

setCookie(beanarea varchar2,cookiename varchar2,cookievalue varchar2, cookieexpiry number,cookiepath Varchar2, cookiedomain varchar2);
setCookie(beanarea varchar2,cookiename varchar2,cookievalue varchar2,cookiepath Varchar2, cookiedomain varchar2);
setCookie(beanarea varchar2,cookiename varchar2,cookievalue varchar2, cookieexpiry number);
setCookie(beanarea varchar2,cookiename varchar2,cookievalue varchar2);

Custom item events 

The Bean raises a custom item event when a malformed value for the domain is entered. A domain name must have at least two periods like in ".oracle.com".

Reading Cookies

You can only read the value of one cookie per each read request. This means that there is no function like "read all " and that you must know the name of the cookie that you are interested in. A program unit is provided in the "cookie" package of the sample form, making it easy to read a cookie.

    getCookie(beanarea varchar2,cookiename in varchar2) RETURN VARCHAR2;

Custom item events 

A custom item event is raised whenever a cookie is not available. 

Requirements

Implementation

The Cookie Handler Bean uses the JSObject class, whic h is a creation by Netscape, allowing you to communicate from Java to Javascript. Settng and retrieving cookies is all handled behind the scenes by Javascript calls to the Browser document. Jinitiator 1.3 and similar plugIns contain the JSObject classes so that the size of the additional Java package downloaded to the client is reduced to the frmCookieHandler.class itself. To use the Cookie Handler Bean in other environments require you to repackage the archive including the JSObject classes.

As there are Browser differences the Cookie Handler Beans treats each Browser individually.

Usage

This section describes the setup that is required to use the Cookie Handler Bean

Forms configuration

  1. In the Forms module, create a Bean container that has at least a size of 1x1 pixel. The container mustn't be visible on the canvas but has to be there to initialize the Java Bean. Mustn't be visible in this context means that you can color it so that it cannot be spotted when running the application.
  2. set the implementation class property of the Bean Container to oracle.forms.demos.beans.CookieHandler
  3. Use the functions and procedures provided in the "cookie" package of the Forms sample module

    setCookie(beanarea varchar2,cookiename varchar2,cookievalue varchar2, cookieexpiry number,cookiepath Varchar2, cookiedomain varchar2);
    setCookie(beanarea varchar2,cookiename varchar2,cookievalue varchar2,cookiepath Varchar2, cookiedomain varchar2);
    setCookie(beanarea varchar2,cookiename varchar2,cookievalue varchar2, cookieexpiry number);
    setCookie(beanarea varchar2,cookiename varchar2,cookievalue varchar2);

    getCookie(beanarea varchar2,cookiename in varchar2) RETURN VARCHAR2;

     

  4. create a when-custom-item-event trigger either on the block or Forms level

DECLARE
  eventName varchar2(30) := :system.custom_item_event;
  eventValues ParamList;
  eventValueType number;
  tempString varchar2(100);
BEGIN
IF (eventName='ERROR') THEN
  eventValues := get_parameter_list(:system.custom_item_event_parameters);
  get_parameter_attr(eventValues,'ERROR_MESSAGE',eventValueType, tempString);
  <use tempString to handle the error message text in Forms>
END IF;
END;

 

Forms Deployment configuration

The following steps describe what needs to be done to deploy the Cookie Handler Bean in a Forms Services application

  1. Copy cookies.jar Forms directory matching the codebase virtual directory. The default installation has  /forms/java as the location of the Java archive files.
  2. Change the base html files, allowing the applet to send script messages to the Browser. This doesn't open up your Browser for security attacks as it only allows the Forms Applet to send scripting messages.

    For MSIE and Netscape with JInitiator

    Open the basejini.htm file located in the forms/server directory and add the following content, highlighted in bold letters, to the specified locations

    <OBJECT classid="%jinit_classid%"
    codebase="/forms\/jinitiator/%jinit_exename%"
    WIDTH="%Width%"
    HEIGHT="%Height%"
    HSPACE="0"
    VSPACE="0">
    <PARAM NAME="MAYSCRIPT" VALUE="true">
    <PARAM NAME="TYPE" VALUE="%jinit_mimetype%">

    ...

    <EMBED SRC="" PLUGINSPAGE="%jinit_download_page%"
    TYPE="%jinit_mimetype%"
    ...

    WIDTH="%Width%"
    HEIGHT="%Height%"
    HSPACE="0"
    VSPACE="0"
    MAYSCRIPT="true& quot;

    ...

    Create a custom application entry in your fomsweb.cfg file located in forms/server

For MSIE and Netscape with JInitiator

[<application name>]
form=<forms application module>
archive_jini=frmall_jinit.jar, cookies.jar
...

...

How to debug

There is an option that will write debug messages showing in the Java console.

SET_CUSTOM_PROPERTY (<beanarea>,1,'DEBUGMESSAGES',<debugoption>);

Allowed debug options  are "true" and "false", where false is the default. A function setdebug is available in the "cookie" package of the form.

setdebug(beanarea varchar2,debugoption varchar2);

The first information of the debug message is the line number of the Beans Java code, helping developers to identify possible problem areas more easily.

How to test it

With the Forms sample there is a HTML test form shipped with this sample. The HTML form allows you to set and read cookies from a client Browser. If the HTML file gets downloaded from the same host as the Forms applet, using /forms as a virtual path, then the cookie created by Forms can be read. Here is a step by step test for
you to perform.

Setting a Cookie to read from Forms

  1. Copy "cookieTestForm.html" and the associated files from the extra directory to a physical directory that is accessible by /forms. If you don't have /forms virtual path mapped then create one.
  2. Run "cookieTestForm.html" from this path and enter a cookie name and a cookie value
  3. Start the Forms sample file
  4. Enter the cookie name into the cookie name field and press the get cookie button
  5. This should show the same value that you created in step 2

Set a cookie in Forms to and read it from the HTML page

  1. Create a virtual path "webdev" and copy the "cookieTestForm.html" and the associated files from the extra directory to the mapped physical directory
  2. Run the forms sample application and create a cookie

    Name:         FormsCookie

    Value:          I love Forms

    Domain:       .<your name>.<your com>

    Path:            /webdev

    Expiration:    2

     

  3. Close Forms, the too Browser if you want, and start the "cookieTestForm.html" form from the <hostname>/webdev/ virtual directory.
  4. Type FormsCookie into the read cookie name field.
  5. Press fetch
  6. This should show what you do: You love Forms