|
jacquard 1.10.0 by The Web Engineering Factory and Toolworks | |||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | |||||||||
See:
Description
| Interface Summary | |
| InitialisationChecker | There's a serious problem with initialising a new webapp in place after it's been delivered. |
| Class Summary | |
| BasicConfigurator | A configurator is a servlet which knows about a war archive, a list of 'to be configured' files within that archive, and a list of configuration parameters. |
| ConfiguratorParam | A parameter for a configurator. |
| DatabaseAwareConfigurator | A configurator which knows some stuff about databases which is common to a lot of Jacquard applications. |
| FirstTime | Part of the 'virginity' mechanism; a servlet to be called just once, when a newly installed web-app is accessed for the first time. |
| InitialisationManager | Central broker for initialisation checkers. |
| JarUnpacker | experimental utility class to understand how to unpack a jar file |
| SQLInitialisationChecker | an InitialisationChecker which checks whether the database has been initialised TODO: doesn't really work and probably isn't going to. |
| Exception Summary | |
| ConfigurationException | an exception thrown when something is wrong with the configuration and the configurator can't procede. |
Configurator is a Java language package for configuring and delivering web application archives (WAR files). It replaces some of the functions of a conventional installer. Yes, the name 'configurator' is a sort of a joke.
Dependencies | Using | Parameter File Syntax | License
Configurator is part of and dependent on the Jacquard toolkit, version 1.10 or above. It is however dependent on the following third party packages. All are open source:
| Package | Description | Supplier | License | Version |
|---|---|---|---|---|
| Jakarta Regexp | A regular expression parser/matcher. | Apache Foundation | Apache license | 1.2 |
You will have to download all these packages and include their jar files in your classpath before you can use configurator.
Typically Web applications are delivered as war files. These war files contain all the resources needed to run the Web application. But the war file is in fact a zipped archive, and within that zipped archive are configuration files, notably the file WEB-INF/web.xml. In the majority of cases these configuration files will need to be customised for different installations, and customising them isn't trivial. The idea behind configurator is to configure applications before the war file is delivered, so that it can simply be dropped into place in the servlet container and run immediately.
The BasicConfigurator servlet prompts the user for a series of configuration parameter values, fetches a payload war file, unpacks it, substitutes those parameter values in the files within it, repacks the war file, and delivers the repackaged file.
While you can specialise the BasicConfigurator servlet, and will need to do so if you want to, for example, take credit card payments as part of the delivery process, it should be adequate for most purposes. On startup the BasicConfigurator reads a parameter file, which is an XML file whose syntax is discussed below. This file describes those files within the payload war archive into which substitutions should be made, and the parameters which are to be substituted into them. If you specialise all you should need to do is to override the method validate< Context).
The parameter file is a custom XML file. its root element is the element configuration which takes no attributes. Within the configuration element there may be any number of file elements and any number of parameter elements.
The file element has no attributes. It contains only the relative pathname of a file within the war archive into which parameters should be substituted.
The parameter element has the following attributes:
Additionally the parameter element may have a child element help whose contents should be suitable help text about the parameter, and any number of parameters option whose contents are optional values for the parameter.
Thus the following is a valid parameter file
<?xml version = '1.0' ?>
<configuration>
<file source="WEB-INF/web.xml.dist" dest="WEB-INF/web.xml"/>
<parameter name="APPNAME" prompt="Name" default="dealersys2" mandatory="true">
<help>
String: The name of your web application. This should be a single word
comprising only letters and digits with no punctuation or
spaces; it should be reasonably short.
</help>
</parameter>
<parameter name="SERVERPORT" default="80" prompt="Port" size="6">
<help>
Integer: The port from which your web application will be served, for
example '80', or '8080'.
</help>
</parameter>
<parameter name="DBDRIVER" prompt="Database Driver" mandatory="true">
<help>
Class name: The JDBC driver you will use to talk to your database.
</help>
<option>org.postgresql.Driver</option>
<option>org.hsqldb.jdbcDriver</option>
<option>com.microsoft.jdbc.sqlserver.SQLServerDriver</option>
</parameter>
<parameter name="DBURL" prompt="Database URL" size="128">
<help>
URL: The JDBC URL you will use to talk to your database, for example
'jdbc:postgresql://localhost:5432/mydatabase'.
</help>
</parameter>
</configuration>
Files into which parameter values must be pasted should contain placeholders of the form left angle bracket, percent sign, name of parameter in lower case, percent sign, right angle bracket. Thus where you want to substitute the value of the parameter name you would have <%name%>. I appreciate this syntax is awkward and may render XML files invalid, but to arrive at a syntax which didn't break the regular expression parser was hard and that's what I came up with!. Any file listed in a file element of the parameter file will be processed. Each may contain arbitrarily many instances of substitution tokens in any order. If no value is provided for a given token, it won't get substituted.
The following is the whole of your license and warranty to use this package:
[Note: this is the 'BSD License' as endorsed by OpenSource.org.]
Copyright (c) 2003 Simon Brooke. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SIMON BROOKE OR OTHER CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
jacquard 1.10.0 by The Web Engineering Factory and Toolworks | |||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | |||||||||