(c) Oracle Corporation 2004
Taking it from customer meetings and recent posts submitted to the Forms discussion forum on OTN (otn.oracle.com), there exists a requirement for a functionality that detects and reports user inactivity in a Forms application. This functionality is required for application security reasons, where an application should lock itself, requiring the user to re-authenticate after exceeding a pre-defined time span of inactivity, or shut down to save system resources. User activity can mean different things and are captured through Java events on the Forms client. Events that can be captured by the Forms TimeoutPJC are of type mouse event, key event and focus event.
With this bean comes a Oracle Forms demo module that showcases the timoutPJC bean. When launching the demo form in the Browser (please read the readme.txt file for setup instructions) there are three control areas visible. The first area is to start and stop the timer. Stopping the timer means that though the expiry condition hasn't occured, the timer will be stopped. Starting the timer allows you to specify the time in minutes that a user can stay inactive in a form without the bean bringing this to the programmers attention.
The second control area allows you to define which events make the user activity. By default all events are tracked. If you check the debugging check box and open the JInitiator console then you get an idea of the internal bean communication caused by this event tracking. Note that all bean communication happens on the client and that there is no network round trip required unless the timer expires due to user inactivity.
The third control area allows you to determine the frequency in which the timer checks for the expiry condition. So if having the maximum user inactivity defined as 60 minutes, you can check this condition e.g. every 10 seconds, or every minute or every 10 minutes and so on.
Now run it: After pressing the Forms button to start the timeout, move the mouse for a few seconds and then wait. If you didn't specify another maximum inactivity than what is set by default, then after 60 seconds an alert should appear informing you that the maximum time of inactivity has been exceeded. The alert is a Forms alert, meaning that the control is passed back from the bean to Forms.
The Forms TimeoutPJC bean registers itself with the Forms applet and adds Java event listeners for mouse actions, key actions and focus actions. Having the bean registering with the Java Applet instead of the canvas where it is located on allows you to use one bean instance to handle the timeout within a whole application.
The timeout functionality can be started and stopped from a Form trigger. The maximum duration of user inactivity is defined when starting the timer. The frequency in which the timer checks if the user's inactivity has exceeded the pre-defined duration can be set and changed before and during the timer runtime. In addition, the events that are used to record user inactivity can be customized in that they can be switched on and off from a trigger in Forms. The default setting is that all events are recorded for registering user activity within a Forms application. A debugging option is provided to track and protocol the PJC working. The bean is tested and an example Forms module is provided for Oracle Forms, however the bean's Java code should work unchanged with the Web version of Oracle Forms6i too.
Limitation: Because the bean register s with the Forms Java Applet and does not spider through all components that are in a Forms canvas, alphanumeric key cannot be recorded if entered into a text field of text area. The reason for this is that key events on text areas and text items are not bubbling up to the upper layers and thus are out of reach for the timeoutPJC. The following keys are captured even if performed on a text item: shift, ctrl, tab, blank, function keys etc. This limitation does not apply for all other Forms widgets like list boxes, buttons etc.
You can skip this section if you don't care about how it works but simply enjoy that it works.
The call to set_custom_property('<block>.<bean item>',1,'START_TIMER','<time in minutes>'); starts a separate Java thread in the timeoutPJC class, which is the base class of this bean. The thread does not expire by itself but requires a specific break condition to occur to be stopped. The specific condition is reached whenever the time defined as the maximum inactivity is exceeded, which is determined by substracting the time of last user inactivity from the curren system (client) time. The frequency in which this break condition is checked is configurable by a call to set_custom_property('<block>. <bean item>',1 ,'TIMER_SLEEP_TIME','<time in seconds>');.
The default setting for the timer check frequency, the timer sleep time, is 60 seconds. The timer frequency also determines the maximum allowed tolerance the timer has. If, for example, the maximum user inactivity time is set to 60 minutes and the timer check frequency is defined as every 60 seconds, the maximum time after which the timer expires is 61 minutes (the minimum time is 60 minutes).
set_custom_property('<block>.<bean item>',1,'START_TIMER','10') starts the timer thread with a maximum allowed user inactivity of 10 minutes. The value of 10 minutes is stored in an instance variable of the bean. Setting the maximum frequency to 10 seconds, set_custom_property('<block>.<bean item>',1,'TIMER_SLEEP_TIME','10'), makes the timer thread doing the following computation every 10 seconds
loop
if (get_current_time - stored_last_user_activity_time > maximum_inactivity){
raise_custom_event;
break_out-of_loop_and_stop_timer;
}
end loop;
The timer expiry only stops the extra Java thread, the Java Bean instance still is active in Forms and can be used.
This section describes the setup that is required to use the TimeoutPJC
set_custom_property('<block>.<bean item>',1,'START_TIMER','<time
in minutes>');
set_custom_property('<block>.<bean item>',1,'END_TIMER','');
set_custom_property('<block>.<bean item>',1,'RECORDING_EVENTS','<list
of events>');
set_custom_property('<block>.<bean item>',1,'TIMER_SLEEP_TIME','<time
in seconds>');
set_custom_property('<block>.<bean item>',1,'ENABLE_DEBUGGING','<boolean>');
DECLARE
eventName varchar2(30) := :system.custom_item_event;
BEGIN
IF (eventName='MAX_INACTIVITY_EXCEEDED') THEN
< your expiry logic here >
END IF;
END;
The timeout functionality is not active by default but requires you to explicitly start it. Also, once the timer has expired and reported the user inactivity to the Forms application, the timer is stopped automatically. If you need the timer to work repeating then you need to start the timer each time after a previous expiration.
set_custom_property('<block>.<bean item>',1,'START_TIMER','<time
in minutes>');
The argument passed when starting the timer determines the duration of user inactivity that when exceeded initiates the custom event raised by this bean.
set_custom_property('<block>.<bean item>',1,'END_TIMER','');
Ending the timer does not end the Bean TimeoutPJC instance. To learn how to re-start the timer, please read on.
The recording events are all mouse, key and focus events that can be captured by the TimeoutPJC to recognize user activity in a form. By default all events are used to stop the timer from expiring. However, in some situations you may want to disable an event from being captured (note that capturing an event doesn't mean to block it)
set_custom_property('<block>.<bean item>',1,'RECORDING_EVENTS','<list
of events>');
The following list of events can be used as an argument passed to the RECORDING_EVENTS:
It is possible to use more than one parameter as an argument by concatenating them together using the '|' character. The following argument makes the timeoutPJC capturing focus events, key events and mouse enter events:
set_custom_property('<block>.<bean item>',1,'RECORDING_EVENTS','focus|key|enter');
By default all events are used to determine user activity so that this function does not necessarily need to be called.
This function defines the frequency with which the TimeoutPJC bean checks if the maximum user inactivity time has been exceeded. By default this frequency is set to 1 minute. The more often the expiry condition is checked, the less tolerance an application has. For example, a maximum inac tivity duration is set to 60 minutes, the user stopped working 59 minutes before. The following timer frequencies report the expiry at this time:
frequency at 30 minutes : reports the incident in 31 minutes (maximum
tolerance 30 minutes)
frequency at 10 minutes : reports the incident in 11 minutes (maximum tolerance
10 minutes)
frequency at 1 minute : reports the incident in 2
minutes (maximum tolerance 1 minute)
frequency at 10 seconds : reports the incident in 1 minute and 10
seconds (maximum tolerance 10 seconds)
frequency at 1 second : reports the incident in 1
minute and 1 second (maximum tolerance 1
second)
The minimum timer checking frequency is 1 second, but its up to the application's security requirements how much tolerance is given to the user. The TIMER_SLEEP_TIME is defined in seconds:
set_custom_property('<block>.<bean item>',1,'TIMER_SLEEP_TIME','10');
The following steps describe what needs to be done to deploy the Cookie Handler Bean in a Forms Services application
For MSIE and Netscape with JInitiator
[<application name>]
form=<forms application module>
archive_jini=frmall_jinit.jar, timeout.jar
......
There is an option that will write debug messages showing in the Java console.
set_custom_property('<block>.<bean item>',1,'ENABLE_DEBUGGING','<boolean>');
Allowed debug options are "true" and "false", where false is the default.
Run the Oracle Forms example module that comes with this demo.