Table of Contents
Note
If you find this EDG documentation helpful please consider DONATING! to keep the doc alive and current.
| Maintainer:David Lloyd |
Expresso provides various degress of control in both the framework and the applications, through both the schema objects and the configuration files written in XML. These configuration controls include:
Schema objects: enables management of the security for all of the applications component objects
Configuration Manager: used for configuration information used by all applications running in a particular context
Setup Values: specific to a particular context, but are further specific to one application
User Preferences: finer level of detail that are specific to a particular user.
There are 3 basic steps (and a few optional ones) in creating your own Expresso Application. They are:
Create your Schema object
Create your XML files in the config directory
Register your Schema and create/intialize the schema/database
Expresso requires this configuration file in order to specify customizable settings controlling it's operation on your system. This file is called expresso-config.xml and it is found in the WEB-INF/config directory. This file contains the primary configuration information for Expresso. It is read during system startup, and it's information is available to any object in the application from the ConfigManager object.
The expresso-config.xml configuration file supplies all of the information for each of the contexts set up with Expresso on your system, and provides information for each of those contexts to connect to their appropriate database engine(s), LDAP servers, and other core information.
The expresso-config.xml that comes with Expresso is set up only for acces to the built-in Hypersonic databases (the "default" and "test" contexts). In order to add access to your own databases you must edit this file and either alter one of the existing contexts or add an entirely new context. See the documentation onsite for example jdbc configuration entities for various database types under the Database-specific Installation Notes header.
The top-level element is the "expresso-config" object, which contains definitions that apply to the entire application. This top-level contains attributes and sub-elements that are applied to all contexts in Expresso. This includes properties like the log directory location where the application will write its log files, which are essential in tracking the application's operation.
Another important section of the expresso-config file is the "class-handlers" section. This section specifies the classes that are used for various implementation classes within Expresso and it's applications. One of these classes, for example, is the "userInfo" implementation, which by default is supplied by the "com.jcorporate.expresso.services.dbobj.DefaultUserInfo" class.
Specifying an alternate implementation:
<class-handlers>
<class-handler name="userInfo" classHandler="com.jcorporate.expresso.services.dbobj.DefaultUserInfo"/>
</class-handlers>
There are several classhandler already defined in Expresso. Here are a few along with their default values:
Table 7.1. Pre-Defined Class Handlers
| Class Handler Name | Default Class | Description |
|---|---|---|
| userInfo | com.jcorporate.expresso.services.dbobj.DefaultUserInfo | userInfo is the implementation of com.jcorporate.expresso.core.security.UserInfo. It is used for mapping login names to integer user id's and also is responsible for storing passwords and other information. |
| orderedCache | com.jcorporate.expresso.core.cache.OrderedCache | Ordered cache specifies a cached list where order must be preserved. It is usually backed by some sort of java.util.List implementation. |
| unOrderedCache | com.jcorporate.expresso.core.cache.UnOrderedCache | UnOrdered cache specifies a cached list where order must be preserved. It is usually backed by some sort of java.util.List implementation |
| registration | com.jcorporate.expresso.services.controller.SimpleRegistration | Registration is a controller that allows for an end user registration process |
| login | com.jcorporate.expresso.services.dbobj.DefaultUserInfo | login is a Controller that provides authentication capabilities for end users |
| nextNumber | com.jcorporate.expresso.core.dbobj.NextNumberImpl | |
| cacheSynchronizer | N/A | cache Synchronizer is an object that communicates to remote machines that cache has been modified and remote caches should be cleared. Expresso itself does not contain a cacheSynchronizer component, but commercial add-ons are available through products such as Expresso Enterprise(tm) |
Nested within the "expresso-config" element are one or more "context" elements, with various nested elements within them. Settings with the context element only affect that one context. Each "context" element defines a different context of operation - typically including a separate database. To recap, context elements contain settings that are specific to one individual context. Another example is the JDBC sub-element, which specifies the connection parameters for DBConnectionPool to connect to your JDBC data source.
Each context has a name, and a description - these are used when the context is displayed, for example, by the Login controller.
The format of the expresso-config.xml file is specified by a DTD (stored in WEB-INF/classes/com/jcorporate/expresso/core/expresso-config_5_5.dtd or a similar name for later versions), and the configuration file is validated against this DTD during startup of the system - any deviation from the expected format will cause a startup failure, and Expresso will likely not initialize. The expresso-config.xml file is organized into a hierarchy, as specified in the DTD file.
It is important to check the DTD for the expresso-config.xml configuration file, and to read the comments in that DTD to understand all of the options available. There are extensive comments in the DTD file that provide the explanation for each setup option - this file will always be your best reference as to alterations of configuration values, as it is the final word on what the valid format for expresso-config.xml is.
If you encounter startup problems with Expresso, the fault is quite possibly the expresso-config.xml file. In order to resolve the problems, examine the output in the expresso.log file in your specified log directory (by default WEB-INF/log). If there is no such file, then the log4j logging system is also not initializing - look for the standard error or standard output log for your servlet engine/application server. For Tomcat, for example, these log files would be in the logs subdirectory of a standard Tomcat installation.
This log files should explain why the loading of the configuration is failing: if it is a DTD validation exception, the element causing the problem should have been specified - correct your expresso-config.xml file and try again.
If the configuration file does not appear to be loading at all, make sure that the DefaultInit servlet is set to be run on system startup - this servlet is the one which actually calls the ConfigManager object, which performs the loading of the expresso-config.xml file itself.
This file provides the mappings required by the Struts frameworks from URL's to "Action" objects - in this case, to the Controller objects in Expresso (which are sub-classes of the Action object.) See the Struts documentation included with Expresso for details of the format of this file. Ordinarily, you will not need to adjust this file at all.
In addition to the normal struts-config.xml file, applications that have their own Controller objects can provide mappings for them in separate configuration files. For example, eForum has an eforum-config.xml file that provides mappings for it's Controllers. In this way, the core struts-config.xml file for Expresso does not need to be adjusted as you install or develop other applications, and the configurations for own applications can be easily adjusted.
Since Expresso 5.1, Expresso uses a unified logging configuration file that is initialized and utilized quite differently from previous versions.
For servlet environments, it is a matter of setting the 'logDir' property in the Servlet context for your web.xml. Look for the configDir in existing installations and add the logDir parameter under that. This is the directory to expand expresso related macros in the log file. What the configuration system does with the logDir parameter is set the system property. 'expresso.logDir' for which log4j can expand upon. Example Snippet:
<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>
<distributable/>
<context-param>
<param-name>configDir</param-name>
<param-value>WEB-INF/config</param-value>
</context-param>
<context-param>
<param-name>logDir</param-name>
<param-value>WEB-INF/log</param-value>
</context-param>
....
If you are using a non-servlet environment, you need to call new LogManager(String loggingConfig, String logDirectory) to initialize the log4j system with the same kind of parameters.
Step #2 is implementing the expressoLogging.xml file. For most of the public downloads, and example of this is already created. To do this, add the expresso.logDir macro to wherever you would normally put the logging directory name.
<appender name="expressoLog" class="org.apache.log4j.FileAppender">
<param name="File" value="${expresso.logDir}/expresso.log"/>
<param name="Append" value="true"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%l) - %m\n"/>
</layout>
</appender>
Please note, that depending on your installation, you may not need ANY such macros expanded. For example, if you're logging to a database or JMS system, then logging directory doesn't make sense. So you can pass null values into LogManager for the logDirectory if this is the case without fear.
There are several special instances for instantiating LogManager that may better fit your special application needs. Use them as you need or see fit.
System Property: expresso.logDir Thanks to the log4j System, all log manager does is set the system property expresso.logDir. Depending on your server environment, it may be more practical to set this system property yourself. (Depending on your security settings)
System Property: log4j.configuration Log4j can automatically find its own logging configuration file through this system property. You can use this directly too.
Put log4j.xml in class path. If no configuration file is used, log4j automatically looks for log4j.xml in the classpath. This may be initialized as needed.
Use LogManager(URL logConfigFile, String logDirectory) This is perfect if the logConfigFile is at a central configuration location or if you have it embedded in a jar file, for example. Note that when you use this method, Log4j does not watch for changes in the logging configuration file.
Use Other System Properties instead Any system property can be used inside the log4j file by enclosing the system property with ${}. So, for example, under Tomcat installations you could write your log file to the catalina log directory by having:
<appender name="expressoLog" class="org.apache.log4j.FileAppender"> <param name="File" value="${catalina.home}/logs/expresso.log"/> <param name="Append" value="true"/> <layout class="org.apache.log4j.PatternLayout"> <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%l) - %m\n"/> </layout> </appender>Notice the use of ${catalina.home} instead of ${expresso.logDir}.
As long as you don't use the last initialization method described above, log4j will watch the configuration file and automatically reload all configuration information once changed. This allows you to selectively turn on and off debugging information without restarting the server.
The fundamental structure of an Expresso application is defined in the application's "Schema" object. This object extends the "Schema" class, and serves as a list of all of the other objects that make up a particular application. Expresso itself uses a Schema class (com.jcorporate.expresso.core.ExpressoSchema) to describe the classes "common" to all Expresso applications. A list of all known Schema objects for a particular installation is held in the SCHEMALIST table in the default database (which may maintained from the Setup page).
The Schema Object is method of control, allowing the application(s) to register the different parts of applications with Expresso. These parts could include database objects (dbobjects), controllers, jobs, and servlets. These different parts are integrated into Expresso to allow better management and services. Also, once integrated into the Expresso Framework, the schema objects allow the various databases in one's application to be populated (if necessary), various initial setups, and fine grained security to be applied without giving up flexibility over the rest of the framework. Every application (such as eContent, eForum, or your own application) has one "schema"ues are very flexible and can be adapted to a wide breath of situations and environments.
To create your own Schema simply extend the com.jcorporate.expresso.core.dbobj.Schema class. Then in the constructor be sure do the following:
Add all of your controllers, dbobjects or jobs that are associated with that Schema.
Modify/add any Setup table values
Set the MessageBundle path (implement getMessageBundlePath())
Define a version number with getVersion()
For details on how to do that see the API or view ExpressoSchema.
When the application server/servlet container that contains Expresso starts up, a number of initialization steps are triggered. These steps begin with the DefaultInit servlet and the ExpressoActionServlet servlet. These two servlets are specified to execute on system startup in the web.xml file for any Expresso application.
The DefaultInit servlet begins by setting a system property to specify which XML parser is to be used during the remainder of the initialization process - this is set to the Xerces parser, and should not be changed.
DefaultInit's next step is to call the ConfigManager object to initialize itself. ConfigManager then deals with the remainder of Expresso's initialization process.
The Configuration Manager allows further configuration of the Expresso Framework as well as the applications that run under the framework. The Configuration Manager achieves this by a set of XML files under the config directory. In these configuration XML files, there are properties that applies to the entire Expresso Framework, such as the underlying database, and some that apply to certain applications. Using the Configuration Manager in conjunction with the set of both Expresso Framework XML and application XML files gives utmost flexibility in the day-to-day operations of the framework.
Every application has access to the Configuration Manager (ConfigManager), an object automatically initialized when Expresso starts up. This object gives access to one or more sets of "properties" - typically used for configuration information used by all applications running in a particular context, such as the required information to connect to the database server. Multiple "contexts" are supported by the database manager to allow many different database contexts to be used at once, either by one or a number of applications.
A context is a separate section in expresso-web.xml, and is typically associated with a single database. A user can log in to a specific context. Most of the configuration properties held by ConfigManager are therefore specific to one context, although there are a few "system-wide" configuration values available as well.
ConfigManager's first step on initialization is to read the expresso-config.xml file, and to create one or more "contexts" of configuration values. The Configuration Manager works by reading in the XML files at Expresso's startup. ConfigManager is a singleton object - that is, there is a single instance of ConfigManager running in any given Expresso application's virtual machine, even if several different db contexts and applications are installed. On startup, the Configuration Manager (expresso/core/misc/ConfigManager.java) will open and read the express-config.xml as well as any the application xml files. Furthermore, the ConfigManager will create one or more "contexts" of the configuration values. A context is a separate section in expresso-web.xml, and is typiclaly associated with a single database.The contexts are separate instances that a user can log into. Most of the configuration properties held by ConfigManager are therefore specific to one context, although there are a few "system-wide" configuration values available as well. Thus the ConfigManager holds both application specific and system-wide configuration values, even though the application specific values grossly outweighs the system-wide values.
Technically, ConfigManager uses the Struts Digester class to read it's XML configuration file, and any problems during this initialization process are logged to the standard output of the servlet container . The Digester class was designed by the Struts folks to map XML to java objects in a systematic fashion with pre-defined rules being applied along the way. Any problems during this initialization process are logged to the standard output of the servlet container - so if your system does not initialize properly, or you see ConfigurationException errors when you attempt to work with your application, examine the system output log. The Digester class provides logging through Log4J (another Apache package) to a predefined logging area (usually a file). This logging provides both record of transactions as well as a simpler debugging process. One of the advantages of Expresso, is Expresso is built upon other projects to provide a best of breed solution. For Tomcat, this is a file in the "logs" directory called "catalina.out". For other servlet containers the location and name will vary - you must check the documentation for your servlet container for details. Once the expresso-config.xml file is read, the Setup values are read from each database into their appropriate context, and the connection pool is initialized for each context.
Another advantage to the ConfigManager is the flexiblity of the class. The ConfigManager supports "custom" configuration values, so you can use it's capabilities to read and maintain values that are specific to your particular application, eliminating the need to create a custom object to do this. This aleviates the need for the application developer to write any custom code to read and parse the application's values. Furthermore, once the application has been registered with the Expresso framework, the ConfigManager is at the application's disposable.
ConfigManager then becomes available to all applications running in that environment for them to request the value of any of it's configuration settings - see the JavaDoc documentation for ConfigManager and the various "Config" objects in the com.jcorporate.expresso.core.misc package for details on what configuration values are available.
's content in. The values are available to any part of the package at runtime with a simple method call to the Configuration Management object (ConfigManager), and are automatically maintained in cache or read again as required. Setup values are different from the values held by the ConfigManager in several ways. They are more application-specific - e.g. there can be a number of setup values that are only used by one particular application, and another set of simiar values that are used by another application, whereas ConfigManager's values are available to all applications. Setup values can also be changed and re-read during execution, whereas ConfigManager's values are only read during system startup. Setup values are stored in the database for a particular context, and can be accesed via methods in the "Setup" object in the com.jcorporate.expresso.services.dbobj package. Once Expresso is set up, you can use the Database Maintenance Servlet to display and edit the list of configuration values. Setup Values can be accessed from the Expresso Framework admin page (running on one's machine of course). To view the Setup Values, click on the Setup in the left bar to get a list of all currently installed setup values. After the Setup Page finishes loading, click on Setup Values in the first table.
Some uses of Setup values are to hold the connection information for a SMTP server, so that various Expresso functions can send emails automatically, and to hold the preferences for the URL of the header of the standard frameset used by Expresso - allowing easy customization to your own frame header for your applications.
Setup values take affect as soon as they are saved.
Table 7.2. Setup Values
| Setup Code | Description |
| AdminEmail | Email address of Administrative / Support Contact. This value should be set to the email address of a user who will receive support queries for the web site being set up - it is used when building the "verify" email for email-based user authentication. |
| AdminName | Name of Administrative / Support Contact for Site webmaster. This is the name to use for the email address specified above. |
| BaseDir | Web Document Root Directory on Server. This should be set to the directory of the root context of your web server. |
| CompanyName | Name of Company - this value is also used for the "verify" email when email-based user authentication is utilized. |
| ConnTimeOut | Database Connection Timout Interval seconds - this is the number of seconds that a database connection may be idle before it is considered "stale" and returned to the connection pool. |
| ContextPath | Context Path for Expresso - this is a very important setup value for all other Express components to operate correctly. By default Expresso is installed in the /components/expresso directory (relative to the root web directory), but may be any other value depending on your installation. For Servlet API 2.2 installations, this is the Context Path for the application context of Expresso. |
| DefaultGroup | Default User Group for Self-registered users - this value supplies the code of a security group. Users that use the self-register function of Expresso are automatically made members of this group. |
| EmailValidateURL | Full URL of Email Validation Servlet - this is the URL to use in the user-authentication emails that are sent if this function is enabled. |
| HomePageURL | Home Page URL - this is the URL included in the authentication email if user-authentication via email is enabled. |
| HTTPServ | Web Server Host Name - this is the system host name of the server hosting this installation of Expresso. |
| LogLevel | Level of detail in Log 0=min, 9=max - you may want to initially specify a high level of detail (e.g. 9) and reduce the level once the system goes into production. |
| MAILFrom | Value for From field in Event E-Mails - this must be a valid email address on the specified email server for outgoing event emails to be operational. |
| MAILPassword | Password for sending e-mail if required - if your email server requires a username and password for outgoing emails the pasword must be specified here. |
| MAILServer | SMTP Server Name for sending E-Mails - the host name of the server hosting your EMail server. Expresso uses this server for sending all of it's email notifications and events. |
| MAILUserName | User Name for sending e-mail if required - if the email server requires a username and password this field specifies the username. |
| MaxConnections | Maximum Number of allowed Database Connections - the connection pool will throw an exception if more than this many connections are requested at any one moment. This is useful if there is an external limit imposed on how many connections to the database can be used - if there is no such limit, this value should be set fairly high (e.g. 20 to 30 is reasonable). |
| MaxJobs | Max Number of Server Jobs to run at once - this specifices the limit on the number of JobHandler requests that will be processed in parallel. Specifying 1 indicates a single-threaded job queue. |
| RequireEmailValidate | Require Email Validation for Account Activation - set to Y to enable to email user-authentication process. |
| RestartServer | Command Line to re-start Servlet Server - a command line on the server that will re-initialize the servlet engine, used by the HealthCheck process if the servlet engine fails. |
| ServletEvent | Servlet Exceptions Trigger SYSERROR Event? - set this field to "Y" if you wish to receive emails for any exceptions that users of Expresso or Expresso applications encounter. A SYSERROR event will be triggerred, and the contents of the email will include a full stack trace and other details of the error. Setting of "N" will not email messages, and a setting of "E" will email all exceptions *except* SecurityExceptions. |
| ServletPath | Default path for Servlets - this is the prefix for servlets in Expresso, by default /servlet. For Servlet 2.2API installations (such as J2EE) this is the context path for the Expresso application. |
| ServletPort | Port Number for Servlet Server - the HTTP port number to use for servlet requests. Often the default of 80 if no port number is supplied in URL's. |
| TempDir | Temporary Directory - a temporary directory that Expresso can store files in on the server. Should be an absolute path name ending with a "/". |
| TimerInterval | Scan Job Queue and directories how often? - the Job Queue is scanned every so many seconds for new job requests. |
User Preferences
At a finer level of detail even than Setup values, which are application-specific, Expresso also provides for the management of "User Preferences". These are settings that are specific to a particular user, and may be used for custom settings for that user - such as the presentation mode used to display forum listings, for example.
The LogManager class is Expresso's interface to the Apache Log4j framework, and is used to set up logging for all applications in a particular environment. See the section regarding log4j configuration above for more information on LogManager.
A JobHandler thread can be configured to start automatically whenever a particular db/context is initialized. This thread runs in the same VM as the servlet engine, and handles jobs queued in that context automatically. If you configure the job handler to not be started automatically, you should run one or more JobHandler utilities as separate tasks (e.g. in their own VM, running them directly as standalone java applications), or jobs queued in that context will not be processed.
JobHandler's thread can be turned on at startup by having the following line in expresso-config.xml:
<startJobHandler>y</startJobHandler>
ConfigManager also initializes the CacheManager, which is responsible for keeping in-memory caches of database information and other data, making it available to applications for quick access, while at the same time managing the size of the cache so that it does not consume all available memory. The CacheManager also "listens" to update events for object so that the cached copy of data can be discarded if it becomes "stale", and new data read directly from the database (or other source).
Each context also has a database connection pool initialized for it at startup time. No connections are established immediately, but the pool grows (to a maximum size specified in the Setup values) as objects request access to the database. The connection information for the pool is stored in the expresso-config.xml file.
Once the Expresso Configuration Manager has initialized, a second servlet is called during system startup to initialize the Struts framework, which Expresso uses for URL mapping and UI presentation via JSP pages.
The Struts initialization process reads, initially, the struts-config.xml file (also in the config directory) in order to determine how URL's are mapped to Controller classes, and various other configuration information for Struts. In addition, each XML file that implements the same DTD as struts-config.xml is also read - again meaning that each application can use a separate configuration file, eliminating the need to edit the supplied struts-config.xml file as you add your own application Controllers. For example, eForum uses eforum-config.xml, ePoll has epoll-config.xml, and so forth. All of these files that can be located are read during startup, and all of the appropriate path mappings are then made available to the user.
It is also possible to initialize Expresso from a standalone java application - e.g. not running in a servlet environment. Examine the code in the "main" method of com.jcorporate.expresso.core.utility.JobHandler for an example of this. Struts is not available from standalone applications initialized in this way, but ConfigManager, CacheManager, DB connection pools and logging all are.
DBTool is a standalone Java application which can be run independently of your servlet container. DBCreate/DBTool can help in two directions: from existing Java code, they can initialize database tables and perform other setup functions. Also, DBTool can be used to reverse-engineer java from existing DB tables. See the javadoc for DBTool, and the Ant task "generatefromdb" which calls DBTool and creates java (DBObject) files from the database specified in /config/expresso-config.xml.
To reverse engineer database tables, the first thing is to set up the connection to the database that you are trying to reverse engineer. Otherwise, there is no way for Expresso to find the tables that you want to reverse engineer. Reverse engineering presumes that the database driver has the ability to query the catalog for the database (most major databases do have this ability). So you have to figure out what to put in the file expresso-config.xml. There is likely a complete example and notes for whatever database you want to use at http://www.jcorporate.com/econtent/Content.do?state=template&template=2&resource=636&db=default
Alternatively, the expresso-config.xml that comes embedded within the download is for the database HSQL, a simple Java database. You could start with that, and just reverse engineer the database tables already created within Expresso, just to get a feeling for how to reverse engineer tables into Java classes.
Have you used Ant before? Ant is a nice cross-platform tool, and all of the jars are put in the classpath automatically when you use that tool as described below. You will have to install it separately (download from http://ant.apache.org/ ).
Now, here's a problem: some downloads, like Expresso-x.y-complete.zip does not include the file build.xml, and described below. "Complete" as part of the download name means that Tomcat has been integrated into the package, so nothing else is needed to run Expresso as a web server, but a "complete" download does not necessarily include source.
So if you download the corresponding package for source, expresso-x.y-src.zip, you will find build.xml there. OK, one more problem: this source package does not include libraries, so you have to copy from the "complete" download, webapps/ROOT/WEB-INF/lib/* into the corresponding directory of this source download. Clearly, these downloads are created with a single purpose, and their size prohibits adding anything that might be convenient but not absolutely necessary.
OK, if you got this far, you have a source distribution which also has libraries, and you have to make one more environmental setting: set an environmental variable for CATALINA_HOME. That is the Tomcat main directory. If you like, you can set it to the directory where you expanded the "complete" download, since Tomcat is installed into the top directory there. (The whole point is just to find servlet.jar to put into the classpath.)
From the top directory where this source download was expanded (e.g., "expressosrc"), and referring to the directory where the "complete" download was expanded (e.g., "expressocomplete"), the commands would be something like
# copy appropriate db config, expresso-config.xml, into directory # where src package has been expanded cp downloads/expresso-config.xml expressosrc/expresso-web/WEB-INF/config/ # set env var for where to find tomcat (used to find servlet.jar) export CATALINA_HOME=/home/me/expressocomplete # go to topmost directory where you unpacked src zip file, # where (topmost) build.xml is found cd expressosrc # execute ant command; assumes ant is installed per instructions, # with (ant-distrib)/bin in path ant generatefromdb # list java files created in this directory ls *.javaIn order to know if the Java files have been created, look in the directory. The Ant script will also give you output that Java files are being created for various tables.
Whew, this could be a lot easier! :-) And after you get the Java files created, there's still plenty to do to register them in a new schema in Expresso in order to use them. Despite all the work, it is still faster to go this route when reverse engineering several tables. And of course, after you've done it once...
The DBCreate is a servlet that is built into the Expresso framework to allow easy addition of applications into the underlying database. To use the DBCreate function, first one must install the Expresso framework and an application.
DBCreate works in conjunction will DBTool. The DBCreate servlet is actually a wrapper to check that the user can execute this function (usually the Admin user), search for the schemas (done in #8 of How-To), and then calls various methods in DBTool. The code source of DBCreate can be found at ($Expresso Installation Directory) /src/com/jcorporate/expresso/services/servlet/DBCreate.java. Once you have installed Expresso and have the servlet server configured, you can automatically create the database tables that are required. You should manually create the actual database that is referred to in your properties file (part of the dbURL is normally the database name). The name can be any valid name for a database. Do not create any tables in the database - Expresso will do that for you. As soon as the database exists, you can verify Expresso's connection to it with the "Status" servlet, on the "Server" page.
The DBCreate servlet is used to perform the following actions. You may select one or more functions for this program to perform. The functions are listed below.
Table 7.3. Initializing the Database
| Field | Description |
| Create Tables | Creates the tables in the database for each database objects (dbobject) in the default schema and in any registered schemas. If the table already exists, no further action occurs. |
| Setup Default Security | Create initial entries for security, including an "Admin" user and user group, and permission for this group to access all administrative functions. Sets user security for a user named "Admin" to access all tables created. |
| Create Default Config Values | Creates default entries in the SETUP database table for configuring your system. Create an entry for all required configuration values for all known schemas. If there are customized values already set up, this function will not overwrite them. |
| Perform additional Setup | Schema objects may optionally provide a method for additional setup to be performed. This method may create application component records, create default values in look up tables and any other required initialize functions. |
When first setting up a server, perform the following steps:
Run the Initialize servlet, selecting all functions. This will create all of the required tables for the standard Jcorporate schema in your database.
Go to the Setup Functions page by clicking Setup on the Expresso Frameworks Table of Contents and select Database Schema Objects. Add a new Schema object definition for each of the applications you have installed, if any.
Come back to the Initialize servlet and run it again. Now all of the required items for each of the schemas will be created, and default security will be initialized. See the Help file for Initialize (the DBCreate servlet) for details.
Once DBCreate is complete, you should Log In as "Admin". There will initially be no password for this user, one should be set immediately using the "Change Password" servlet on the Login page. When you are finished, you can go back to the Expresso Setup page and continue with the Verify Configuration step.
It is suggested that for beginner's, the user installs the location example application (Download) as a demonstration. The following steps illustrate how to get the location demo.
Install the Expresso Framework
Download location-2.0.zip from the Expresso Examples project (to find click on Projects in the header of Jcorporate's site)
Unzip under the location-2.0.zip under the ROOT directory (see here, under Directory Structure Details for more info)
After installing the location application, start up Expresso if not done so already
Bring up Expresso's home page in a web browser
Click on the Applications (see below in the circle)
Find the add button for the Registered Schemes
Fill in the appropiate values and Click the form's button at the bottom
Click on Setup
Make sure that all the checkboxes are checked, and click run.
The user will see the text appear in the frame saying what the process is doing. The user will need to check the output for an errors.
The DBTool program is used to create the required database tables for Expresso (and other application built with Expresso) and to set initial values for a number of important Setup values.
DBTool is a standalone Java application which can be run independantly of your servlet container in order to initialie your database tables and perform other setup functions. It uses the same code as the DBCreate servlet and the two perform the same function.
Create tables: One of the primary functions of DBTool is to create new tables in the selected database for all of the Expresso DBObjects. Once the Expresso tables are created, other applications can be "Registered" by adding entries to the SCHEMALIST table and then DBTool can be re-run and these applications' tables also created.
Default Security: DBTool can also create default security settings for the applications of a particular database.
Populate Default Values: DBTool allows you to step through the default setup values & change their value to one suitable to your system.
The DBTool program can be run with the command line: java com.jcorporate.expresso.core.utility.DBTool configDir=<config> [arg=value] This assumes that you have Expresso on your CLASSPATH - the CLASSPATH for running DBTool should be exactly the same as the one your servlet engine is using. You can use the -classpath option on the "java" executable to set the classpath, or specify it from the environment. In this command line, you replace <config> with the directory that contains your default.properties and any other database properties. Be sure it is the directory, not the path to the default.properties file itself! Other arguments to DBTool are available to perform several other functions which are discussed later in this section.
To perform initial setup with DBTool, execute it with the following arguments: java com.jcorporate.expresso.core.utility.DBTool configDir=<config> setup=yes
You should first manually create the actual database that is referred to in your properties file (part of the dbURL is normally the database name). The name can be any valid name for a database. Do not create any tables in the database - Expresso will do that for you. With the built-in Hypersonic database you must only create the empty directory for the database to be stored in. DBTool will display a long sequence of output in this mode, you may wish to redirect standard output and standard error to a file for later review. If you have problems during initialization, you can send this file to us to the listserv or forums and we will try to help. This function will:
Create the Tables in the database for each DBObject in Expresso
Create default entries in the SETUP database table for configuring your system
Create initial entries for security, including an "Admin" user and user group, and permission for this group to access all administrative functions.
Perform any additional setup and initial processing specified by custom applications.
This function can also be performed by the DBCreate servlet, once Expresso is set up and operational. For more information see:
Help file (at http://yourservername:8080/expresso/help/DBCreate.html) for Initialize (the DBCreate servlet) for details
The DBCreate section of the documentation
Review the output from the "setup=yes" step and correct any errors (for example, bad configuration file information). You can safely re-run this step even if it completes partially - no information will be overwritten.
Once you have created the database and the default setup values, you must specify appropriate Setup values for your system and installation. DBTool allows you to step through the default setup values & change their value to one suitable to your system. Particularly important are the ServletPath and ContextPath for your system, but all values should be checked carefully. You can edit these setup values at any time once Expresso is installed from the link on the setup page. Enter the config mode of DBTool by running: java com.jcorporate.expresso.core.utility.DBTool configDir=<config> config=yes
DBtool will now prompt you for each essential setup value as discussed earlier in this chapter. DBTool will prompt for each setup value, displaying it's current value and description. You can accept the default value by pressing RETURN or specify a new value, which will be saved to the database. Once setup values have been set, it is best to restart your servlet server to make sure no caching is occurring, then continue to verify your installation. Once initial setup is complete, you should log in as "Admin". There will initially be no password for this user, one should be set immediately using the Change Password command on the Log in page. When you are finished, you can go back to the Expresso Setup page (http://yourservername:8080/expresso/setup.jsp) and continue with the next step.
DBTool takes a number of optional command-line arguments that can perform many different functions.
Table 7.4. Arguments to DBTool
| Argument | Value | Description |
| configDir | a directory | The directory argument indicates where the default.properties and other properties files can be found. If no dbname argument is specified, default.properties is used. |
| webAppDir | a directory | The directory argument to webAppDir indicates the location in which Expresso (or the Expresso-based application) is installed as a web-application. If you use the %web-app% macro in your properties file you must supply this value. |
| db | A database/context name | This optional property specifies a database/context name to use for subsequent processing. The db/context name is the same as the first part of the name of a .properties file in the directory indicated by configDir's value (e.g. dbname=oracle would be looking for oracle.properties in the configDir). If this value is not specified, default.properties is used for database connect information. |
| setup | yes (or any non-blank value) | Initial system setup mode. With this argument, DBTool will attempt to create the default tables and default setup values and security on the indicated database. Note that if this command is run after the tables are already there, it is safe - the existing tables will not be dropped. This can be particularly valuable for adding new tables as Expresso (or other applications) are updated. |
| config | yes (or any non-blank value) | Enter/edit Setup/configuration values |
| test | yes (or any non-blank value) | Invoke test mode. In test mode, DBTool will scan all registered applications (e.g. all entries in the SchemaList table), including Expresso, and perform a database "verify" on all database objects in those Schemas/Applications. This will report all and any referntial integrity errors, and will display an exception if the definition of any database object does not match the actual database. This can be very helpful when checking for database changes in a new version of Expresso or other application. |
| generate | Database object or table name | Generate database object source code from named table in the database. In this mode, DBTool will write a file to the current directory by the same name as the table name given on the command line. The file will have a .java extension and is a basic DBObject for the specified table, reverse-engineered from the current database. |
| import | dbobjname | Import data into named database object, use 'all' to import into all known database objects for which files exist. |
| file | filename | File name to import from/export to. Not required if 'all' is used for the import parameter. |
| format | formatCode | Format for import/export. Options are xml or tab |
| bench | yes | Run benchmarks |
The following persons have contributed their time to this chapter:
Kris Thompson
Michael Nash
Larry Hamel, CodeGuild, Inc. (JGroup Expert)
Mike Rimov
Mike Traum (JGroup Expert)
Sandra Cann
Tino Dai
Note
Was this EDG documentation helpful? Do you wish to express your appreciation for the time expended over years developing the EDG doc? We now accept and appreciate monetary donations. Your support will keep the EDG doc alive and current. Please click the Donate button and enter ANY amount you think the EDG doc is worth. In appreciation of a $35+ donation, we'll give you a subscription service by emailing you notifications of doc updates; and donations $75+ will also receive an Expresso T-shirt. All online donation forms are SSL secured and payment can be made via Credit Card or your Paypal account. Thank you in advance.
Copyright © 2001-2004 Jcorporate Ltd. All rights reserved.