Websydian v6.1 online documentationOnline documentation - Websydian v6.5

Implementing the SessionControl Pattern



This implementation page shows how to use the SessionControl pattern in a Websydian application.  The examples used are elaborations of the Websydian Tutorial.

Inherit from the SessionControl Pattern

First, you must create a local Session entity in your application model that inherits from the SessionControl pattern in the WSYSESS library.

MySession is a ENT SessionControl

The local MySession entity will now scope the pattern to implement Session Control for the application.

Example:

Structure of Session entity

Inheriting from the SessionControl pattern provides the structure of a Session entity including a number of abstract patterns and the necessary server functionality to read and update the Session records (not seen on figure).

Session is a RelationalTable

If running on a relational database, you need to declare the Session entity as a RelationalTable

MySession.Data.Session is a ENT RelationalTable

Getting the Next SessionID

Getting the next SessionID is not a part of the inherited Session functionality.  However, this is easily done by using the Surrogate patterns:

Numerator is a ENT SurrogateSystem
RelationalTable
MySession.Data.Session is a ENT Surrogate
replaces ENT
...by ENT
SurrogateSystem
Numerator
replaces FLD
...by FLD
Surrogate
SessionID

Using the Abstract Patterns

Included in the Session library are three abstract web functions.  These patterns all inherit from the basic Websydian patterns - the Dispatcher, the Event Handler, and the Page Generators - and augment those to incorporate the Session functionality.  In this way, the enhanced Dispatcher function will include validations of incoming Session ID's, the Event handler functions will have the Session ID defined as a hidden field etc.

The Session patterns are all scoped by the Abstract entity scoped under the MySession entity.  By inheriting from these patterns instead of the original Websydian patterns, the code of the Dispatcher, Page Generator, and Event Handler patterns in your application will automatically include calls to the relevant Session handling functionality.

Modifications to the Dispatcher Function

All requests from web users to the web server go through the Dispatcher function.  Therefore, the Dispatcher function has been modified to include Session validation functionality.  The derived Dispatcher function expects a SessionID coming along with each web user request.

To implement the Session functionality for the web application's Dispatcher function, you must make your application Dispatcher function inherit from the Session Dispatcher pattern.

Example:

Modifications to Dispatcher function

Session functionality will be implemented for the Dispatcher function by letting it inherit from EventDispatcher pattern in Session Abstract instead of inheritance from the EventDispatcher pattern in WSYBASE.

The Abstract.EventDispatcher pattern itself contains a call to the ErrorPage function.  This call should be replaced by a call to an application specific Error Page function.

Example:

MySession.Abstract.EventDispatcher replaces FNC
...by FNC
ErrorPage
TutErrorPage

Modifications to the Page Generator Functions

The PageGenerator pattern should be used by the Page Generator functions of the application.  This pattern includes the SessionID field in the WsyDetails and the WsyGrid regions.

Example:

Change inheritance of Page Generator functions

All Page Generator functions in the web application must inherit from the PageGenerator pattern scoped under the Abstract entity.  Inheritance from the PageGenerator pattern is not necessary if specified for the abstract Page Generator instead.

The PageGenerator pattern must remain in the inheritance path of each Page Generator function in order to include a Document Template Generator function.  This can be specified by having the Abstract.PageGenerator pattern inherit from PageGenerator.

Example:

MySession.Abstract.PageGenerator is a FNC PageGenerator

Modifications to the Event Handler Functions

Finally, the Event Handler functions in the model must also be modified to inherit from the Abstract.EventHandler pattern.  This will add the SessionID field to the WebInput and the Hidden variables of the Event Handler functions:

Example:

Change inheritance of Event Handler functions

All Event Handler functions in the web application must inherit from the Abstract.EventHandler pattern.  Existing inheritance triples may be kept.

Existing inheritance triples for the Event Handlers should be kept in the model, if they provide additional functionality not included by the Session Event Handler pattern.

Applying the WebEndUserSession Event Handler

The Services.WebEndUserSession function is a pre-defined Event Handler function that calls the EndSingleSession server process.  By including the WebEndUserSession function on an HTML page, the web user will have the possibility to actively end his Session in the application.

Example:

The WebEndUserSession event is added to the WebListArticlesPage function, but not to the WebEntryPage:

WebListArticlesPage comprises FNC MySession.Services.WebEndUser Session
TutorialDispatcher calls FNC MySession.Services.WebEndUser Session
MySession.Services. WebEndUserSession name NME End Session
EndPage is a FNC PageGenerator

The last triple defines a Page Generator function generating an empty HTML page to be shown when the Session has been ended.  This HTML page contains no events, but its Document Template may be modified to provide a message to the web user.

Remember, an Event Handler function must always call a Page Generator function.

Example:

.Call blank End page

The Services.WebEndUserSession function is used to implement the End Session event.  The event will result in an empty HTML page sent to the web user.

Generate and Build Objects

Model triples have been added and replaced and functions have been modified.  Now, it is time to regenerate and rebuild the relevant source objects.  First, a small number of internal functions used by the Session library must be generated and built:

Generate and build the functions included in the SessionObjectsToGenAndBuild subject area.

Generate and build the objects scoped by the Session Control pattern entity:

Generate and build the tables, the views and the server functions scoped under the Data.Session entity (implementation names may be assigned to the table and to the view objects).

Also, generate and build the Services.WebEndUserSession function.

Then generate, build, and move the modified web functions:

Generate and build the Dispatcher function, the Page Generator functions, the Document Template Generators and the Event Handler functions (do not generate and build the functions scoped under the _DocumentTemplateGenerator functions).

Move the compiled program objects to the program folder (WebtutorCGI for the Tutorial) at the web server.

The enhanced web functions scoped under the Abstract entity should not be compiled.  These are abstract patterns and should only be used for inheritance.

Prepare the HTML Document Templates

The SessionID field has been added as a hidden field to the HTML forms of the Document Templates.  So these have to be regenerated by running the Document Template Generator functions from the Generate and Build window.

If layout and design work has been made on copies of the generated HTML Document Templates then it should be considered to add the SessionID field to the Document Templates manually.  Otherwise run the Document Template Generator functions for those Page Generator functions that have been modified.

Example:

Document Templates to be regenerated

The figure points out the Document Template Generator functions to be re-run from the Generate and Build window.

Next, move the generated (or manually modified) Document Templates from the HTML folder in the Gen library to the HTML folder at the web server:

Running the Application with the New Session Functionality

If you have followed the guidelines and examples presented in this document, you are now ready to run your application enhanced with the new Session functionality.

Try for instance to end a Session, step backwards in the browser and see that it is no longer possible to post a form for that Session.  You may choose to generate and build Windows functionality to follow the creation and updating of the Session records.