Events and Event Handlers

The following is intended as a reference for implementing plugin event handlers to provide custom logic in response to events being fired at defined points throughout the execution cycle in both the Web Determinations Interview Engine and Web Determinations platform.

Go to:

Events

Platform events

Implementing Event Handlers

Do's and don'ts

Examples

Events

This section describes the specific engine and platform events - providing details about the objects contained by the events (accessible and modifiable by associated event handler implementations) and the mapping between the events and the event handler interfaces to be implemented by plugin classes in order to be registered as valid event handlers for the respective events.

Interview Engine events

These events are tied to an instance of the InterviewEngine. They allow subscribers to be notified when a rulebase has been added, removed or otherwise modified. This is particularly useful when using a Rulebase Resolver plugin that is capable of dynamically reloading rulebases (also known as, hotswapping).

Event	Encapsulated objects	Description	Event Handler Interface
OnRulebaseAddedEvent	InterviewRulebase object that has just been added.	Fired immediately after the RulebaseService has notified the InterviewEngine that a rulebase has been added.	OnRulebaseAddedEventHandler
OnRulebaseRemovedEvent	InterviewRulebase object that has just been removed.	Fired immediately after the RulebaseService has notified the InterviewEngine that a rulebase has been removed.	OnRulebaseRemovedEventHandler
OnRulebaseUpdatedEvent	InterviewRulebase object that has just been updated.	Fired immediately after the RulebaseService has notified the InterviewEngine that a rulebase has been updated.	OnRulebaseUpdatedEventHandler

Interview Session events

These events are tied to an instance of the InterviewSession:

Event	Encapsulated objects	Description	Event Handler Interface
OnSessionCreatedEvent	The InterviewSession object that has just been created.	Fired immediately after an interactive session is created, with the InteractiveEngine object as the sender. This is the chance to inject data into the session or perform any other custom initialization logic required.	OnSessionCreatedEventHandler
BeforeSessionDestroyedEvent	The InterviewSession object about to be destroyed.	Fired just before a Web Determinations session is to be destroyed, with the InterviewSession as the sender. This is the last chance to extract the session data out of the session and persist it somewhere, clean up any resources created/opened during the session's lifetime, and so on.	BeforeSessionDestroyedEventHandler
OnValidateControlEvent	The InputControlInstance that has just been validated. The entity instance on which the control's attribute is located. The data model encapsulating the entity instances that currently exist on the current Web Determinations session. An object encapsulating the current status of the data submission transaction into the Web Determinations session. This object contains the errors, warnings and events raised during the submission process.	Fired immediately after an input control is validated by the core validation logic, with the Web Determinations Engine ControlInstance as the sender. Custom validation may be applied here and errors and/or warnings attached to the transaction result object.	OnValidateControlEventHandler
OnValidateScreenEvent	The InterviewScreen that has just been validated. The data model encapsulating the entity instances that currently exist on the current Web Determinations session. An object encapsulating the current status of the data submission transaction into the Web Determinations session. This object contains the errors, warnings and events raised during the submission process.	Fired immediately after an Interview screen is validated by the core validation logic, with the Web Determinations Engine InterviewScreen object as the sender. Custom validation may be applied here and errors and/or warnings attached to the transaction result object.	OnValidateScreenEventHandler
BeforeSubmitDataEvent	The data model encapsulating the data to be submitted into the Web Determinations session. An object encapsulating the current status of the data submission transaction into the Web Determinations session. This object contains the errors, warnings and events raised during the submission process.	Fired immediately before data (encapsulated in an InterviewUserData object instance) is to be submitted into an Web Determinations session, with the InterviewSession object as the sender. Event handler implementations that handle this event have the ability to cancel the submission by appending an error to the transaction result object.	BeforeSubmitDataEventHandler
OnCommitEvent	The data model encapsulating the data that has just been committed into the Web Determinations session. An object encapsulating the current status of the data submission transaction into the Web Determinations session. This object contains the errors, warnings and events raised during the submission process.	Fired immediately after data submitted into an Web Determinations session is committed to the rulebase session, with the InterviewSession object as the sender. If this event fires, it means that the data submitted has been attached to the underlying rule session and is safe to work with, persist, export, and so on. Some sort of auto-save functionality could be implemented as a handler of this event.	OnCommitEventHandler
OnSubmitRollbackEvent	The data model encapsulating the data submitted during the submission operation. An object encapsulating the current status of the data submission transaction into the Web Determinations session. This object contains the errors, warnings and events raised during the submission process.	Fired immediately after a failed submit data operation was rolled back, with the InterviewSession object as the sender. If this event fires, it means that the data submitted has not been committed to the underlying rule session	OnSubmitRollbackEventHandler
OnSubmitDataEvent	The data model encapsulating the data submitted during the submission operation. An object encapsulating the current status of the data submission transaction into the Web Determinations session. This object contains the errors, warnings and events raised during the submission process.	Fired immediately after the submit operation, regardless of whether the operation was successful and the data submitted was committed or the operation failed and the operation was rolled back. Note that this event will not fire if the transaction result contained errors immediately after the call to handleEvent on all the BeforeSubmitDataEventHandler implementations - the submission operation is aborted in this case and the BeforeSubmitDataEvent is the only submission event fired.	OnSubmitDataEventHandler
OnGenerateDocumentEvent	The document type of the document being generated An object encapsulating the document-generation parameters, and attributes for Decision Reports of this specific document-generation action.	Fired when the user submits a document generation action. The event handler receives the document type and other various document-generation parameters in the event object. The event handler also has access to the InterviewSession object from the sender input argument. The event handler has the option of generating a document of its own and providing it to the event object (as a 'replacement document'). The Web Determinations Server will use the replacement document and bypasses normal Document Generation steps.	OnGenerateDocumentEventHandler

Interview Portlet events

These events allow developers to customize the behavior of the Interview Portlet:

Event	Description	Event Handler Interface
OnPortletRequestEvent	This event fires when the interview portlet receives either a doView, processAction or serveResource request and provides access to the PortletRequest object. It is fired immediately prior to request being processed by Web Determinations. The PortletRequest object can be useful, for example, for adding additional parameters to the portlet session.	OnPortletRequestEventHandler
OnPortletWriteResponseEvent	This event provides access to the PortletResponse and Web Determinations Response objects. It is fired after the Portlet / Web Determinations has processed the request but prior to any response being written to the response stream. This event allows the developer to modify the Web Determinations Response object, for example, to add a custom heading to a page programmatically.	OnPortletWriteResponseEventHandler
OnDecodeParamEvent	This event provides access to the parameters contained in PortletRequest.getParameterMap(), just before these parameters are URLUTF8-decoded and passed to Web Determinations. This event allows the developer to modify the parameter name and value by using the setParamName and setParamValue methods. Note: You can find a detailed Javadoc API of the portlet event in the Oracle Policy Automation installation's help\api directory.	OnDecodeParamEventHandler
OnAfterProcessActionEvent	This event is fired after the Portlet / Web Determinations has processed the request in the action phase but prior to the portlet entering the render phase. The event provides access to the portlet's ActionRequest and ActionResponse objects, as well as the Web Determinations Session Context and the Response about to be rendered. Third parties can use the ActionResponse to, for example, send events to external portlets.	OnAfterProcessActionEventHandler

Web Determinations servlet events

These events are tied to an instance of the Web Determinations WebDeterminationsServlet. They are designed to provide access to the native HTTP Request, Response, and Session objects. Unlike other events the encapsulated objects differ with regards to the .NET and Java implementations.

Event	Encapsulated objects	Description	Event Handler Interface
OnRequestEvent	Java The HttpServletRequest being processed. The SessionContext relating to the current request A string indicating the type of request currently being processed. This will either be either "GET" or "POST".	Fired on receipt of either a HTTP Get or Post request, immediately prior the request being processed by Web Determinations.	OnRequestEventHandler
	.NET The HttpRequest being processed. - The HttpSessionState associated with this request. The SessionContext relating to the current request A string indicating the type of request currently being processed. This will either be either "GET" or "POST".
OnWriteResponseEvent	Java The HttpServletResponse that the response will be written to The Response to be written The WebDeterminationsServletContext associated with this event	Fired after Web Determinations has processed the request but prior to any response being written to the response stream.	OnWriteResponseEventHandler
	.NET The HttpResponse that the response will be written to The Response to be written The WebDeterminationsServletContext associated with this event

Web Determinations session events

These events are tied to an instance of the Web Determinations SessionContext:

Event	Encapsulated objects	Description	Event Handler Interface
OnInvestigationStartedEvent	The SessionContext of the current user session. The GoalInstance object encapsulating the goal to be investigated	Fired immediately after an investigation on a particular goal attribute is started.	OnInvestigationStartedEventHandler
OnInvestigationEndedEvent	The SessionContext of the current user session. The GoalInstance object encapsulating the goal that has just been investigated.	Fired immediately after an investigation on a particular goal attribute is concluded (that is, the goal becomes known).	OnInvestigationEndedEventHandler
OnGetScreenEvent	The Platform Screen object of the screen to be rendered for display response	Fired after the Platform Screen is generated from the InterviewScreen, and before it is rendered to HTML. The Screen object can be a native or custom screen. The sender object is the SessionContext object for the current session.	OnGetScreenEventHandler
OnRenderScreenEvent	The string HTML of the rendered Platform Screen object for display response	Fired after the HTML is generated from the Platform Screen object, and before the HTML is set back as a Response. The sender object is the SessionContext object for the current session.	OnRenderScreenEventHandler
OnSaveEvent	The SessionContext of the current user session.	Fired when the user clicks on the Save button to save the current interview data, and before the DataAdaptor 'save' is called. The handler can provide a Case ID for the save - poor man's data adaptor, and a quick way to auto-generate CaseID for save (avoiding the 'Get CaseID from user' screen'). The handler can also raise an error and halt the save process.	OnSaveEventHandler
OnRequireSessionEvent	The SessionContext of the current user session The request URI object of the current Request	Fired if the current Interview request requires an InterviewSession to have already been started, and the current InterviewSession is null. The handler can provide the InterviewSession to be used by the Interview request. The handler can use the URI object, which contains various details about the current request such as the rulebase, locale, request action, and so on. Note: This event will not fire on a StartSession request since having an existing active session is not a pre-requisite for starting a new session.	OnRequireSessionEventHandler
OnApplyTemplatesEvent	The ScreenTemplate to be used to render the screen. The StyleTemplate to be used to style the screen. The TemplateContext to which the templates are to be applied	The event that fires before the Velocity template is applied to the screen. This method can be used to push additional parameters to the velocity template or modify the template used to render the screen.	OnApplyTemplatesHandler
OnInterviewSessionCreatedEvent	The SessionContext of the current user session The request URI object of the current Request The newly created InterviewSession	Fired immediately after a new InterviewSession is created in Web Determinations. It provides the opportunity for handlers of this event to perform additional post session configuration such as load reference data. Additional parameters that are passed in on the query string to the StartSession Action can be accessed via the provide URI object. The sender object is the SessionContext object	OnInterviewSessionCreatedEventHandler

Implementing Event Handlers

Along with the requirements placed upon plugin implementations, event handler implementations must conform to the following:

The handleEvent(event : Event, sender : Object) : void method must be implemented. When an event of the type(s) that the event handler implementation is a handler of is fired, the event handler implementation's handleEvent method is called, with the fired event and the object in which this event was fired as the parameters.
Note: One event handler implementation may implement multiple event handler interfaces, marking itself as an event handler for multiple event classes. In this case, it is the responsibility of the event handler implementation to check the runtime type of the event parameter and casting it as necessary before determining what to do with it.

Do's and don'ts

It is possible to register multiple handlers for the same instance of an event, however, no assumptions can be made about the order in which those events will be called.
It is not permissible for event handlers alter the state of the sender object.
Event handlers are not permitted to alter the state of the system, unless the event itself provides provision for doing so; for example, the OnValidateControl event provides the ability to perform additional validation and mark a control as being valid or invalid when it might not have otherwise been the case.

Examples

Follow the links below to view the event handler examples contained in the Oracle Policy Automation Developer's Guide:

Interview Engine

Custom Control Validator

Custom Screen Validator

Web Determinations

Plugins - Data Adaptor - sample code (Autosave with Derby)

Example: Use the OnInterviewSessionCreatedEvent to pre-seed data into a newly created session

Interview Portlet

Example: Encode the Interview Portlet's response

Example: Extract the username in the Interview Portlet

Example: Send external events to other portlets