Copyright © 2006 Together Teamlösungen EDV-Dienstleistungen GmbH
Enhydra Application Framework (EAF) is a collection of Java classes, which provide the runtime infrastructure for Enhydra applications. It implements the Enhydra "super-servlet", provides dynamic URL-JSESSIONID rewriting, PO caching, session-, database-, logging-, configuration- and XMLC API's.
The Enhydra application framework includes:
1. Presentation Manager
2. Session Manager
3. Database Manager
4. Configuration
5. Logging
In general, the application framework includes all the classes in the com.lutris.appserver.server.*
packages, which provide the infrastructure that Enhydra applications use at
runtime.
The presentation manager handles the loading and execution of presentation objects in the context of an Enhydra application. The presentation manager transforms the name of the presentation object into a URL, uses the specified class loader to load the presentation object, and then executes the presentation object by executing its run() method. There is one instance of a presentation manager per Enhydra application. The presentation manager can also cache presentation objects in memory and any associated files that are part of the application.
Each application has a Presentation Manager that is an instance of the class: HttpPresentationManager . The presentation manager is contained within an instance of HttpPresentationServlet class. This design allows a servlet to have multiple presentation objects managed by the presentation manager. The presentation manager also manages the resources necessary to execute the presentation objects.
The presentation manager also provides the key with which the session manager
uses to locate a session. The key either is a cookie or generated by URL rewriting.
The com.lutris.appserver.server.httpPresentation package contains classes and interfaces that the Presentation Manager
and presentation objects use.
The SessionManager is one part of the Enhydra Application Framework. The framework automatically issues users a cookie and creates a Session object. The cookie is a secure, opaque identifier. All the application data is kept safely inside the application. Every request the user makes, when it is given to the presentation objects, contains the user's session object. Inside the session object is a SessionData object. This is a totally flexible container for whatever the application wants to store.
The session manager and session objects provide a flexible, lightweight mechanism that enables stateful programming on the Web. EAF provides a general implementation of session management that serves as a basis for more sophisticated state models (a session is a series of requests from the same user that occur during a time-period). Session management gives servlets and other server-side applications the ability to keep state about a user as the user moves through the application. EAF maintains user state by creating a Session object for each user. These Session objects are stored and maintained on the server. When a user first makes a request to an application, the user the session manager assigns a new Session object and a unique session ID. The session ID matches the user with the Session object in subsequent requests. The Session object is then passed as part of the request to the servlets that handle the request. Servlets can add information to Session objects or read information from them. After the user has been idle for more than a certain period, the user's session becomes invalid and the Session Manager destroys the corresponding Session object.
Different implementations of the session manager have been developed. The class that implements the one used with each of the applications is to be stated in the configuration file, for example:
SessionManager.Class=com.lutris.appserver.server.sessionEnhydra.SimpleServletSessionManager
If the SessionManager.Class is not specified, the old com.lutris.appserver.server.sessionEnhydra.StandardSessionManager is used (it is kept for compatibility reasons, but it's use is not encouraged).
The available session manager adapters are:
com.lutris.appserver.server.sessionEnhydra.SimpleServletSessionManager - this is a simple session manager which interconnects the servlet container sessions and enhydra sessions by using the same session keys (generated by session container) - placed in eafstdsessions.jar file.
com.lutris.appserver.server.sessionContainerAdapter.ContainerAdapterSessionManager - simple session manager to be used with servlet container capable of managing their sessions - placed in eafsession-containerAdapter.jar file. It uses HttpSession to keep the session data. The sessions are completely managed by the session container and are configured in the servlet container configuration files. Any session configuration parameters defined in the application configuration file are ignored (except sessionManager.Class). The persistence across restarts of the application and container is relised by the appropriate servlet container mechanisms.
com.lutris.appserver.server.sessionContainerAdapter.JmxContainerAdapterSessionManager - Tomcat specific session manager, extends ContainerAdapterSessionManager, by using JMX MBeans to obtain some session information from the session container - placed in eafsession-containerAdapter.jar file.
com.lutris.appserver.server.sessionContainerAdapter.TomcatContainerAdapterSessionManager - Tomcat specific session manager, extends ContainerAdapterSessionManager, witch interacts directly with (wraps) Tomcat Session Manager - placed in eafsession-containerAdapter.jar file.
NOTE: For the last two containers, session data must be serializable in order to fully utilize the persistence obtained by the session container.
Any data that is application-wide (shared across all pages and all users) should be kept in the application object. Any data that is user-wide (needed across all URLs a user goes to, but one copy per user) should be kept in SessionData. Any data that is page-specific (only needed by one page, but shared across all accesses to the page) should be stored as static fields of the presentation object.
Example of various settings in the web.xml:
<env-entry> <env-entry-name>SessionManager/Class</env-entry-name> <env-entry-value>com.lutris.appserver.server.sessionEnhydra.StandardSessionManager</env-entry-value> <env-entry-type>java.lang.String</env-entry-type> </env-entry>
The Database Manager is another (optional) part of the Enhydra Application Framework. The database management object interface, com.lutris.appserver.server.sql.DatabaseManager defines management of database connections for application - placed in dbmanager-api.jar file.
package com.lutris.appserver.server.sql
DatabaseManager - he database management object interface. This class implementing this interface manages operations with database.
Implementations of DatabaseManager:
StandardDatabaseManager - implements DatabaseManager interface. DODS project is Standard implementation of DatabaseManager interface.
To set DatabaseManager implementation class, use the following syntax in configuration file: DatabaseManager.Class parameter defines class name of DatabaseManager implementation (full package name). Default value is com.lutris.appserver.server.StandardDatabaseManager.
Application parameters are read via JNDI. Parameters can be read from applications'a web.xml file, or from its <appName>.conf file.
Application configuration can be read from application's <appName>.conf file. Configuration can also be read from application's web.xml file. Two parameters that define which file will be used are ConfFile and ConfFileClass. They are defined in web.xml in
<init-param>
tag.
NOTE: <appName> is the name of the application.
The first parameter is obligatory. It contains the name of the configuration file (with the path relative to directory where web.xml file is) that will be used for reading configuration.
The second parameter contains the name of the class (with full package) that will be used for creation of configuration file and for reading application configuration. It can have the following values:
The API consists of:
org.enhydra.util.ConfigFileInterface - an interface that defines methods that every configuration file should have.
org.enhydra.util.AbsConfigFile - an Abstract class that implements org.enhydra.util.ConfigFileInterface and contains non specific code for all configuration files.
Implementations of ConfigFileInterface:
com.lutris.util.ConfigFile - This class implements reading parameters from <appName.conf> config file and defines methods that are specific for this type of configuration file.
org.enhydra.util.XMLConfigFile - This class implements reading parameters from web.xml file and defines methods that are specific for this type of configuration file.
The configuration object com.lutris.util.Config (which contains application configuration datails) now works with org.enhydra.util.ConfigFileInterface interface. For adding new type of configuration file, the class org.enhydra.util.AbsConfigFile should be extended (or directly interface org.enhydra.util.ConfigFileInterface implemented), and in web.xml file parameters ConfFile (name of the configuration file with the path relative to directory where is web.xml file) and ConfFileClass (name of the class with full package that will be used for configuration file) should be set to new values.
The default value is com.lutris.util.ConfigFile .
Example: Reading configuration from <appName>.conf file
<init-param>
<param-name>ConfFile</param-name>
<param-value><absolute_or_relative_path>/<appName>.conf</param-value>
</init-param>
<init-param>
<param-name>ConfFileClass</param-name>
<param-value>com.lutris.util.ConfigFile</param-value>
</init-param>
Example: Reading configuration from web.xml file
<init-param>
<param-name>ConfFile</param-name>
<param-value>web.xml</param-value>
</init-param>
<init-param>
<param-name>ConfFileClass</param-name>
<param-value>org.enhydra.util.XMLConfigFile</param-value>
</init-param>
Enhydra Application Framework supports three different ways of logging. Logger interface defines abstract level of Enhydra logging (Logger and LogChanel interfaces) in eaf_api.jar (EAFApi source module).
Old Standard logging system (to file and to console) is default and it is defined in application conf file by LogFile, LogToFile and LogToStderr parameters.
Also new Enhydra Application Framework supports log4j-logging. Implementations of Logger and LogChannel classes with log4j support are included in EAF.
Monolog is used in Jonas for logging. So, EAF contains Monolog implementation of Enhydra Logger. Implementations of Logger and LogChannel classes with log4j support are included in eafmonolog.jar.
If you want to use log4j or monolog logging, you have to set two new parameters in application configuration file : LogClassName and Log4j(Monolog).
LogClassName parameter means which implementation of logger class is used :
Possible values:
com.lutris.logging.StandardLogger (default value - for standard logging system)
com.lutris.logging.Log4jLogger (for log4j logging)
com.lutris.logging.MonologLogger (for monolog logging)
Log4j : Pathname of Log4j XML configuration file.
Monolog : Pathname of Monolog configuration file (trace.properties for Jonas J2EE Server).
LogChannel class is an interface of a channel associated with a logging facility. All messages for the facility are written using a channel.
Logger is a general-purpose logging facility. It is modeled after syslogd. This is a base class from which an actual implementation is derived.
LogWriter is a class used to write log output to a particular LogChannel and level. This class is PrintWriter, with println() causing a write.
Implementations of LogChannel interface:
com.lutris.logging.StandardLogChannel (default value - for standard logging system)
com.lutris.logging.Log4jLogChannel (for log4j logging)
com.lutris.logging.MonologLogChannel (for monolog logging)
Extensions of Logger class:
com.lutris.logging.StandardLogger (default value - for standard logging system)
com.lutris.logging.Log4jLogger (for log4j logging)
com.lutris.logging.MonologLogger (for monolog logging)
Extensions of LogWriter class:
com.lutris.logging.Log4jLogWriter (for log4j logging)
com.lutris.logging.MonologWriter (for monolog logging)
Standard logging initialization
Standard logging in is initialized by default, in case no LogClassName parameter is specified in the application's configuration file. The following is the list of parameters one can specify for a standard logger:
Server.LogFile -- This is the file where the server log is written
Server.LogToFile[] -- This is a comma separated list of message types to send to the log file specified in server.logFile
Server.LogToStderr[] -- This is a comma separated list of message types to send to standard error. Possible logger levels:
EMERGENCY -- Panic condition.
ALERT -- A condition that should be corrected immediately, such as database corruption.
CRITICAL -- Critical conditions such as had device errors.
ERROR -- General errors that are not usually fatal, but must be resolved.
WARNING -- Warning condition that may need attention, although the need is not immediate.
NOTICE -- Conditions that are not error conditions, but may require special handling such as infrequent conditions.
INFO -- General informational conditions, knowledge of which will help to keep the server in good order.
DEBUG -- Messages that contain information normally of use only when debugging an application.
CLASSLOAD -- Information about the loading of application classes. Very useful debugging class path problems.
REQUEST -- The StandardLoggingFilter logs hits to this facility if this is specified (normally it writes to it's own file).
XMLC -- Information about auto-compiling XMLC pages.
XMLC_DEBUG -- Debug information about auto-compiling XMLC pages.
An example:
Server.LogFile = "C:/enhydra5.1/logs/multiserver.log"
Server.LogToFile[] = EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, INFO
Server.LogToStderr[] = EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, INFO
In order to initialize log4j it is mandatory to specify the following parameter in the configuration file:
LogClassName=com.lutris.logging.Log4jLogger
In addition, a log4j-config paramer should be defined and point to a log4j.xml configuration file. Detailed specification can be found at: http://jakarta.apache.org/log4j/docs/documentation.html.
Log4j supports following logging levels: ALL, DEBUG, INFO, WARN, ERROR, FATAL, OFF.
In order to initialize Monolog the following paramer should be defined in the configuration file:
LogClassName=com.lutris.logging.MonologLogger
The application's logging configuration can be performed either in the trace.properties file in the enhydra/conf folder or in a user-specific file in which case a Monolog property should be defined in such a way that it points to the configuration file. An example:
Monolog=trace.properties
Monolog supports following logging levels: INHERIT, DEBUG, INFO, WARN, ERROR, FATAL.
More details about Monolog logging can be found at: http://monolog.objectweb.org/index.html.
NOTE: Please, check out Release Notes. They contain late-breaking information information that might not have made it into this document.