8 Working with Server and System Events
This chapter contains the following:
8.1 About Oracle Forms and Server Events
With the exception of timers, most events in Oracle Forms occur from some kind of user interaction. In previous versions prior to 11g, of Oracle Forms, there was no easy support to receive an external event if it could not be bound to the Form's graphical user interface. Forms clients had to use techniques such as polling through a great deal of coding to respond to these events to deal with external events that it did not initiate.
With Oracle Forms 11g and Oracle Database, you can handle external events, such as asynchronous events, by using the database queue. Note that in order to work with database queues in Oracle Forms 12c you must be using Oracle Database 11g Release 2 or later. Oracle Streams Advanced Queuing (AQ), an asynchronous queuing feature, enables messages to be exchanged between different programs. AQ functionality is implemented by using interfaces such as DBMS_AQ, DBMS_AQADM, and DBMS_AQELM, which are PL/SQL packages. For more information about Advanced Queuing, see the Oracle Streams Advanced Queuing User's Guide at http://docs.oracle.com/database/121/STRMS/
In general, the steps required to integrate events and database queues are:
-
Create a queue table: Define the administration and access privileges (AQ_ADMINISTRATOR_ROLE, AQ_USER_ROLE) for a user to set up advanced queuing. Define the object type for the payload and the payload of a message that uses the object type. Using the payload, define the queue table.
-
Create a queue: Define the queue for the queue table. A queue table can hold multiple queues with the same payload type.
-
Start the queue: Enable enqueue/dequeue on the queue.
-
Enqueue a message: Write messages to the queue using the DBMS_AQ.ENQUEUE procedure.
-
Create an event object: Create a new event in the Events node in the Object Navigator in the Form Builder.
-
Subscribe the event object to the queue: The name of the queue is specified in the Subscription Name property.
-
Code necessary notification: Write the event handling function, which is queued up for execution by Forms and is executed when the server receives a request from the client. Write the trigger code for the When-Event-Raised trigger that is attached to the Event node.
-
Run the form and register the subscription
-
Invoke the When-Event-Raised trigger upon event notification
In earlier versions of Forms, handling external events was only possible through custom programming, usually done in Java with the help of Forms' Java Bean support. Beginning in Oracle Forms 11g, it is possible to call into Forms from any technology that can interface with Advanced Queuing (AQ), for example Java Messaging (JMS).
Figure 8-1 shows the flow of events that take advantage of the improved integration of the different components your application might work with. In the left side of the image, the Oracle Forms has two-way communication with the AQ functionality of Oracle Database. In the center of the image, the AQ function of Oracle Database also has two-way communication with the possible outside events that can trigger internal Forms events. In the right side of the image, these external events can include technologies such as files with dynamic content, Web services, mail, JMS, or database content that interact with BPEL processes which in turn interact with AQ. BPEL, however, is not necessary. JMS, as an example, can interact with AQ directly without having to go through BPEL.
Note:
Third party tools such as antivirus and security software may prevent Advanced Queuing from working correctly with Oracle Forms. As a workaround, turn off any third party security tools.
8.2 Creating Events
Oracle Forms Developer provides a declarative environment for creating and managing event objects. For known external events, Forms Developer provides a list of available events that can be subscribed to. The property of the event object can be set at runtime or at design time. The ability to end a subscription to a particular external event is also provided through a dynamic setting of the event object property.
Most of the new event functionality is also available through standard Oracle interfaces. Both client and server-side PL/SQL provide all the necessary functionality to create, subscribe, and publish a database event. Oracle Forms provides a declarative and user-friendly way of registering a database event. Oracle Forms provides a standard way of responding to the event by hiding most of the complexity from end-users.
8.3 Subscribing to Events
The Forms Services gets notified when events it has registered interest in are added to the event queue. Registration is done either when the runtime starts up or when connecting to the database, depending on the type of the event. For database events, the type of the event queue (persistent or non-persistent) is also saved as part of the event creation.
8.4 Event Propagation
Figure 8-2 shows a situation where a Forms client is idle. Since Oracle Forms is driven by the HTTP protocol, which is a request/response protocol only, nothing can change on the client if the client is idle. An applet parameter MaxEventWait, expressed in milliseconds, governs how long the application should wait before checking for an event. In other words, you can specify how often the client should send a request to the server, thus causing the execution of the PL/SQL that is specified as a response to an event.
Note, however, that, on the server-side, Forms Services receives all the events without polling. However, the server does not start running the WHEN_EVENT_RAISED triggers until it receives the notification from the Forms Client (because of the HTTP request/reply paradigm of the Forms Client and hence the need for the MaxEventWait property).
8.4.1 About the When-Event-Raised Trigger
Oracle Forms responds to or fires a trigger in response to a variety of events. For both Forms Developer and internal events, Forms provides entry points in terms of triggers so that an application developer can associate and execute some code in response to an event.
For example, a defined trigger is attached to a specific object in a form. The object to which a trigger is attached defines the scope of the trigger. For example, the WHEN-BUTTON-PRESSED trigger corresponds to the Button Pressed event which occurs when an operator selects a button. The name of the trigger establishes the association between the event and the trigger code. When a user clicks on a button, Forms responds by executing the code in the WHEN-BUTTON-PRESSED trigger.
This new event object has a corresponding trigger defined at the event object level. The WHEN-EVENT-RAISED trigger fires in response to the occurrence of a database event for which it has a subscription. The firing of the new trigger is similar to the internal processing of triggers. However, the source of the event is, in this case, an external event such as a database event (firing as a result of an operation) and not the result of any user interaction with forms or as a result of an internal form processing.
8.4.2 About Trigger Definition Level and Scope
Oracle Forms triggers are usually attached to a specific object, such as an item, block, or Form. The object to which a trigger is attached determines the trigger's definition level in the object hierarchy. A trigger's definition level determines the trigger's scope. The scope of a trigger is its domain within the Forms object hierarchy, and determines where an event must occur for the trigger to respond to it. Although the WHEN-EVENT-RAISED trigger is attached to an event object, it has an application level scope because of the nature of the server-centric events. When the event notification is invoked as a result of an asynchronous callback mechanism for registered database events, any number of forms running within that application and with a subscription for that event receive the notification. This alleviates the need for the application developer to code complex logic to deal with the event.
There is also a Form-level scope so that the event will only be handled if the application is running the specific form from where the event is defined.
8.5 Publishing Database Events
You use the standard PL/SQL interface for publishing a database event from Forms. For example, you can publish the SalaryExceed event by calling the enqueue interface and providing all the necessary arguments. You can also call a stored procedure to perform this task.
The following program unit can be called from a WHEN-BUTTON-PRESSED trigger by passing the queue name. Depending on how you have defined the queue in the database, a commit might or might not be necessary to actually publish the event. The following sample code will not actually publish the event since there is no commit issued.
Declare
msgprop dbms_aq.message_properties_t;
enqopt dbms_aq.enqueue_options_t;
enq_msgid raw(16);
payload raw(10);
correlation varchar2(60);
begin
payload := hextoraw('123');
correlation := 'Jones';
enqopt.visibility := dbms_aq.IMMEDIATE;
msgprop.correlation := correlation;
DBMS_AQ.ENQUEUE( queue, enqopt, msgprop, payload, enq_msgid);
end;
For more information about database events, see Oracle Database PL / SQL Reference.
8.6 About Application Integration Between Forms
Many enterprise applications are made of a large number of forms which are defined to perform specific tasks such as purchasing, accounting, and sales force management. These applications may also interact with other non-Forms based applications as part of performing a task. The need to provide an integration model where an enterprise can easily integrate its applications (including passing data) with those of its partners, suppliers, and distributors is extremely important.
In previous releases, Oracle Forms attempted to integrate loosely coupled applications through mechanisms ranging from using user_exit calls and some polling via timers to using pluggable Java components. These methods are all useful in some limited circumstances, but they do not provide a formal infrastructure for enterprise application integration.
Apart from the deployment concerns and performance issues, the main reason why these methods do not fully integrate applications is that the integration is only provided through Forms Developer as almost all events are bound to Forms visual components. Also, the communication with the Forms Services is always initiated by the Forms client via a request-reply model.
To provide better support for application integration, Oracle Forms 12c supports synchronous and asynchronous server-centric events.
8.6.1 About Synchronous Communication
Synchronous communication follows a request-reply paradigm, where a program sends a request to another program and waits until the reply arrives. HTTP follows this paradigm. This model of communication (also called online or connected) is suitable for programs that need to get the reply before they can proceed with their work. Traditional client-server architectures are based on this model. Earlier releases of Oracle Forms client-server architecture is also an example of this model. One of the drawbacks of the synchronous model of communication is that all the programs must be available and running for the application to work. In the event of network or machine failure, programs cease to function. For example, if the Forms Services dies, the Forms client ceases to function as well. The synchronous communication model is also in use when the Forms Services interacts with other systems such as PL/SQL or the database. The Forms system would be blocked waiting for the current operation to end before continuing with its work. Another drawback of synchronous communication is that the calling program has to wait for a response and unexpected events cannot be handled without first polling for them.
8.6.2 About Asynchronous Communication
Asynchronous communication is when a user or form places a request in a queue and then proceeds with its work without waiting for a reply or when an asynchronous event is received without any initial request. Programs in the role of consumers retrieve requests from the queue and act on them. This model is well-suited for applications that can continue with their work after placing a request in the queue because they are not blocked waiting for a reply. It is also suited to applications that can continue with their work until there is a message to retrieve.
Oracle Forms 12c supports asynchronous communication with the help of database events. A thin queuing mechanism provides the mechanism for asynchronous events. The queue is checked for messages once there are no more current operations to be performed.
For example, an application might require data to be entered or an operation executed at a later time, after specific conditions are met. The recipient program retrieves the request from the queue and acts on it.
8.6.3 Configuring Asynchronous Communication
Oracle Forms uses a polling technique at the application level. The client polls the server for an update after specified intervals of time. The frequency of polling can be modified using the parameters - MaxEventWait and HEARTBEAT. A higher frequency of polling may ensure that a client polls the server more frequently for updates; however, this may result in consumption of considerable resources.
The frequency value for polling is set in formsweb.cfg. The value assigned to this constant is in milliseconds and is a positive number.
In the absence of the configuration file setting, the current Oracle Forms HEARTBEAT setting is used. However, special attention and care should be made with regards setting and using of MaxEventWait. In a default setting where MaxEventWait is not set, the HEARTBEAT mechanism is used for polling. The default delay when the HEARTBEAT mechanism is used is two minutes. You can set the MaxEventWait (which is in milliseconds) to a value smaller than the HEARTBEAT for faster response.
For more information on configuring these parameters using the Enterprise Manager, see Chapter 4, "Managing Parameters".
8.7 System Events
Often it is required to have an application be aware of events that occur on the system hosting it and, have an ability to react to these actions. In most cases, such events are not directly caused by the running Forms application, but knowledge of their occurrence could provide valuable information to it. This is most common on the client tier of an Oracle Forms application. An example of such a system event might be an indication that the end-user has been idle for an extended period of time. Knowledge of such a condition would allow the application developer to react and take appropriate actions. System Events can provide that desired knowledge.
In Oracle Forms 12c, five System Events are available. For all of these Events, little to no administrative configuration is required to use them. In order to use any of these events the application developer will be required to create the appropriate event object and code the WHEN-EVENT-RAISED trigger to perform the desired action. However, a brief description of each will be provided here. More information can be found in the Form Builder Help.
Note:
Because System Events rely on actions outside of Oracle Forms or the successful completion of an action within the application, they should not be used as the only means for implementing application security. If for any reason the action associated with the System Event does not complete successfully or is undetected by the application, the related application trigger may not fire. Although this is likely to be rare, it should be considered when developing with System Events.8.7.1 System Client-Idle
The System Client-Idle event monitors for end-user activity, on the client tier within the running Oracle Forms application. This event can be enabled in one of two ways. One way to enable this event, is for an administrator to set the applet parameter idleTimeout to a whole number. This will represent the time in seconds to wait before raising this event. To use this applet parameter, it must first be added to the appropriate Forms template base.htm file and formsweb.cfg.
This event can also be enabled/disabled programmatically using a new argument added to SET_APPLICATION_PROPERTY, CLIENT_IDLE_TIME. As with the applet parameter, the value of CLIENT_IDLE_TIME is represented in whole seconds. Refer to the Form Builder Help for more details on how to use this in PL/SQL.
Following are some of the limitations:
-
Client-Idle will be ignored while the client applet is waiting on a response from the server or if a modal dialog is open (e.g. Alert, File Open dialog, etc). However, if the server responds immediately before the idle time has lapsed, the event may be raised. Although this condition should be rare, developers should consider this when developing the application. Adjusting the idle time programmatically may be necessary to avoid this condition when it is expected that the server may take an extended period to complete its task.
-
Although the amount of idle time is set in seconds, the application may not react until the next exchange with the server. This is caused by either
HeartbeatorMaxEventWait.
8.7.2 System DB-Idle
The System DB-Idle event monitors activity between the Oracle Forms Runtime and the database to which it is connected. This event will monitor any interaction with the database executed by the associated application. This event can be enabled in one of two ways. The first way is to set the environment variable FORMS_DB_IDLE_TIME to a whole number, which represents the number of seconds to wait before raising this event.
This event can also be enabled/disabled programmatically using a new argument added to SET_APPLICATION_PROPERTY, DB_IDLE_TIME. The value for DB_IDLE_TIME will be a whole number, in seconds. Refer to the Form Builder Help for more details on how to use this in PL/SQL.
Following are some of the limitations:
-
The internal timer for the DB-Idle event begins immediately after completing a database action. This does not include the Forms default login action that occurs during application startup.
-
By default, this event will only be raised one time. For example if a
COMMITis executed then activity against the db no longer occurs and the preset time is reached, this event will be raised. If after that raising of the event, the idle condition remains, the event will not be raised again. To cause this event to continue monitoring, it must be set programmatically by setting the Application propertyDB_IDLE_REPEATtoTRUE.
8.7.3 System Single-Sign-Off
Oracle Forms is not a true single sign-on partner application. Therefore, historically for Oracle Forms applications that are authenticated using SSO were not be able to determine if a sign-off request occurred. With the addition of this System Single-Sign-Off event, this is no longer the case. The sign-off action can occur as a result of the user explicitly logging out of SSO or if the SSO session expires. It may be desirable to have the Oracle Forms application know about such a sign-off condition so it can react to it. Application developers can then decide how to react to this event, if at all.
Following are some of the limitations:
-
The event may not appear to be raised immediately because control may be on server (e.g. due to a long running database query) when logout occurred.
-
The event may not be sent to the server until the next scheduled exchange (e.g. Heartbeat) or user interaction.
8.7.4 System Notification
System Notifications will allow an administrator, from Fusion Middleware Control, to raise various event levels. This will further allow developers to create specific tasks based on the message or notification level received from Fusion Middleware Control. For example, the application may be designed to display a message to the user when Notification level 3 is received. This message may have been predefined to tell users that the system will be shutting down for maintenance and they need to exit the application. Five notification levels are being provided (1-5).
Refer to Chapter 4, Section 4.4, "Managing User Sessions" for more information on how to send User Session Notifications