uk.co.weft.configurator
Class BasicConfigurator

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          uk.co.weft.maybeupload.MaybeUploadServlet
              uk.co.weft.htform.Servlet
                  uk.co.weft.htform.WithExceptionHandlerServlet
                      uk.co.weft.htform.Page
                          uk.co.weft.htform.Form
                              uk.co.weft.configurator.BasicConfigurator

All Implemented Interfaces:

DocumentGenerator, ResourceConsumer, java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

Direct Known Subclasses:

DatabaseAwareConfigurator

public class BasicConfigurator

extends Form

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. It shows a form of the configuration parameters, allows the user to supply values, unpacks the war file in temporary space, makes the substitutions, repacks the war archive, and delivers it over the HTTP connection. There is at present one magic paramater, appname, which must be in the parameters file because it controls the name of the war file which gets built.

To specialise this class it should be sufficient to specialise the method validate( Context), q.v.

See Also:

Serialized Form

Nested Class Summary

protected class	BasicConfigurator.ConfiguredWidgetSet a widget set to be selected when the configured package is available in the stageing area
protected class	BasicConfigurator.ConfigureWidget

Field Summary

static java.lang.String	APPNAMETOKEN token for the name of the webapp I am to buils
static java.lang.String	CACHENAME the name of the directory within the stage in which I unpack the payload
static java.lang.String	CONFIGURATIONTAG the configuration tag
static java.lang.String	DEFAULTATTR the default value attibute of the parameter tag
static java.lang.String	DELIVERYPACKAGEURLTOKEN token for the URL of the configured package for delivery
static java.lang.String	DESTINATIONATTR the destination attribute of the file tag
static java.lang.String	FILETAG the file tag
static java.lang.String	HELPTAG the help tag - child of parameter tag
protected Element	intro An XML element whose value should be printed out as my introductory material; may include HTML markup.
static java.lang.String	INTROTAG the intro tag
static java.lang.String	MANDATORYATTR the mandatory attribute of the parameter tag
static java.lang.String	NAMEATTR the name attribute of the parameter tag
static java.lang.String	NOAMPERSANDVALUESTOKEN token whose value in the config should be a space separated list of tokens whose values in the service time context should be checked for unescaped ampersands - any found which are not already part of recognisable XML entities being replaced by &.
static java.lang.String	OPTIONTAG the option tag - child of parameter tag
static java.lang.String	PARAMETERTAG the parameter tag
static java.lang.String	PARAMSTOKEN token for the full or relative pathname or URL of the file from which I will read parameters
protected java.lang.String	payloadName name of my payload
static java.lang.String	PAYLOADNAMETOKEN token for the name (perhaps including version number) of the payload I'm delivering
protected java.lang.String	payloadPath location of my payload.
static java.lang.String	PAYLOADTOKEN token for the full or relative pathname or url of the war archive which is my payload
static java.lang.String	PROMPTATTR the prompt attribute of the parameter tag
static java.lang.String	SIZEATTR the size attribute of the parameter tag
static java.lang.String	SOURCEATTR the source attribute of the file tag
protected java.lang.String	stagePath location of my staging area.
static java.lang.String	STAGINGAREATOKEN token for the full or relative path name of the directory where we unpack and repack our payload
static java.lang.String	TITLETAG the title tag

Fields inherited from class uk.co.weft.htform.Form

action, actionExecutedToken, ACTIONEXECUTEDTOKEN, auxiliaries, contextMenuMagicToken, CONTEXTMENUMAGICTOKEN, cssHelp, CSSHELP, cssPrompt, CSSPROMPT, defaultScriptBase, mandatoryPrompt, MIN_WIDGETS, onloadFunctionToken, ONLOADFUNCTIONTOKEN, optionalPrompt, selectedWidgetSetMagicToken, SELECTEDWIDGETSETMAGICTOKEN, showHeadline, submitMethod, SUBMITMETHODCONFIGTOKEN, SUBMITMETHODGET, SUBMITMETHODPOST, validationWhingeToken, VALIDATIONWHINGETOKEN, whingeHeader, widgets, widgetSets

Fields inherited from class uk.co.weft.htform.Page

DOCTYPECONFIGTOKEN, dynamicFootInclude, dynamicHeadInclude, footInclude, footIncludeURL, headInclude, headIncludeURL, imageUrlBase, layout, printStylesheet, PRINTSTYLESHEETCONFIGTOKEN, stylesheet, STYLESHEETCONFIGTOKEN, title, titleMagicToken, TITLEMAGICTOKEN

Fields inherited from class uk.co.weft.htform.WithExceptionHandlerServlet

EXCEPTIONHANDLERCLASSCONFIGTOKEN

Fields inherited from class uk.co.weft.htform.Servlet

calendar, conf, contentType, CONTENTTYPECONFIGTOKEN, cookieDomain, cookiePath, COOKIESCONFIGTOKEN, cookieTTL, dbPassword, dbUrl, dbUsername, debug, DEBUGCONFIGTOKEN, driverName, embedded, here, identity, localeMagicToken, LOCALEMAGICTOKEN, outputStreamMagicToken, OUTPUTSTREAMMAGICTOKEN, parsePathInfo, PATHINFOMAGICTOKEN, ready, redirectMagicToken, REDIRECTMAGICTOKEN, requestMagicToken, REQUESTMAGICTOKEN, resourceBundleName, responseMagicToken, RESPONSEMAGICTOKEN, servletMagicToken, SERVLETMAGICTOKEN, sessionMagicToken, SESSIONMAGICTOKEN, USEHTTPSCONFIGTOKEN, zone

Fields inherited from class uk.co.weft.maybeupload.MaybeUploadServlet

allowOverwrite, maxUpload, saveUploadedFilesToDisk, silentlyRename, uploadDir, uploadDirPath, uploadDirURL

Fields inherited from interface uk.co.weft.htform.ResourceConsumer

RESOURCEBUNDLEMAGICTOKEN

Constructor Summary

BasicConfigurator()

Method Summary

protected void	configure(Context context) actually do the work.
protected void	deleteDir(java.io.File target) delete the file, or, recursively, the directory, passed as argument
protected java.io.File	fetchPayload(java.io.File dir) fetch my payload into the specified directory and unpack it there
protected java.lang.String	fixXMLSyntaxChars(java.lang.String tofix) fix any XML syntax chars in tofix with the appropriate entities - unless they are themselves part of entities.
protected java.util.Vector	getParameters(Context config) Parse my parameters file, and return explicitly a list of my parameters.
void	init(Context config) Read my config and set up my widgets
protected void	patchFile(java.lang.String sourcepath, java.lang.String destpath, Context context) patch the specified file by substituting the user-supplied values
protected void	preForm(Context context) Say what we're currently delivering
protected void	preProcess(Context context) Check tokens listed in NOAMPERSANDVALUESTOKEN for unprotected ampersands - useful for things which will be output in [X|HT]ML documents
protected void	repack(Context context, java.io.File dir) repack the contents of the specified directory into a WAR archive file
protected boolean	validate(Context context) determine whether or not to configure using this context.
protected java.net.URL	validatePayload(Context config) return a URL (possibly a file URL) for my payload, ideally having checked it exists and seems to be the right sort of thing
protected java.io.File	validateStage(Context config) validate that my stage exists, is a directory, and is writable by me; return it as a File.

Methods inherited from class uk.co.weft.htform.Form

addAuxiliary, addWidget, defaultActionHandler, doBody, doHead, doHeadBodySep, fixupMagicValues, generate, getLayout, getNextActionURL, getSelectedWidgetSet, getTitle, getTransformURL, getWidgetSetByName, handleAction, hasWidgets, makeReady, postForm, postProcess, selectNextWidgetSet, setContextMenuQuery

Methods inherited from class uk.co.weft.htform.Page

doFoot, doFoot, generateContent, getFootInclude, getFootIncludeURL, getFootIncludeURL, getHeadInclude, getHeadIncludeURL, getHeadIncludeURL, getStylesheet, getStylesheets, getTables, getTitle, outputRedirectBlock, readStringFromURL

Methods inherited from class uk.co.weft.htform.WithExceptionHandlerServlet

whinge, whinge, whinge

Methods inherited from class uk.co.weft.htform.Servlet

addCookie, addCookie, coerceCookiesToContext, coerceToContext, coerceToContext, coerceToContext, coerceToContext, coerceToUrl, createContext, doGet, doPost, getCalendar, getContentType, getDebug, getLocale, getOutputStream, getResource, getResourceString, getServletInfo, grs, grs, handleCookies, handleRedirect, init, setCookieValues, storeOnSession

Methods inherited from class uk.co.weft.maybeupload.MaybeUploadServlet

doDelete, doHead, doOptions, doPut, doTrace, getUploadDir, getUploadURL, service

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doGet, doHead, doOptions, doPost, doPut, doTrace, getLastModified, service

Methods inherited from class javax.servlet.GenericServlet

destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletName, init, log, log

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface uk.co.weft.domutil.DocumentGenerator

destroy

Field Detail

CACHENAME

public static final java.lang.String CACHENAME

the name of the directory within the stage in which I unpack the payload

See Also:

Constant Field Values

PARAMSTOKEN

public static final java.lang.String PARAMSTOKEN

token for the full or relative pathname or URL of the file from which I will read parameters

See Also:

Constant Field Values

PAYLOADTOKEN

public static final java.lang.String PAYLOADTOKEN

token for the full or relative pathname or url of the war archive which is my payload

See Also:

Constant Field Values

PAYLOADNAMETOKEN

public static final java.lang.String PAYLOADNAMETOKEN

token for the name (perhaps including version number) of the payload I'm delivering

See Also:

Constant Field Values

APPNAMETOKEN

public static final java.lang.String APPNAMETOKEN

token for the name of the webapp I am to buils

See Also:

Constant Field Values

STAGINGAREATOKEN

public static final java.lang.String STAGINGAREATOKEN

token for the full or relative path name of the directory where we unpack and repack our payload

See Also:

Constant Field Values

DELIVERYPACKAGEURLTOKEN

public static final java.lang.String DELIVERYPACKAGEURLTOKEN

token for the URL of the configured package for delivery

See Also:

Constant Field Values

NOAMPERSANDVALUESTOKEN

public static final java.lang.String NOAMPERSANDVALUESTOKEN

token whose value in the config should be a space separated list of tokens whose values in the service time context should be checked for unescaped ampersands - any found which are not already part of recognisable XML entities being replaced by &. Also checks for left and right angle brackets and replaces with < and > as appropriate.

See Also:

Constant Field Values

CONFIGURATIONTAG

public static final java.lang.String CONFIGURATIONTAG

the configuration tag

See Also:

Constant Field Values

FILETAG

public static final java.lang.String FILETAG

the file tag

See Also:

Constant Field Values

HELPTAG

public static final java.lang.String HELPTAG

the help tag - child of parameter tag

See Also:

Constant Field Values

INTROTAG

public static final java.lang.String INTROTAG

the intro tag

See Also:

Constant Field Values

OPTIONTAG

public static final java.lang.String OPTIONTAG

the option tag - child of parameter tag

See Also:

Constant Field Values

PARAMETERTAG

public static final java.lang.String PARAMETERTAG

the parameter tag

See Also:

Constant Field Values

TITLETAG

public static final java.lang.String TITLETAG

the title tag

See Also:

Constant Field Values

DEFAULTATTR

public static final java.lang.String DEFAULTATTR

the default value attibute of the parameter tag

See Also:

Constant Field Values

DESTINATIONATTR

public static final java.lang.String DESTINATIONATTR

the destination attribute of the file tag

See Also:

Constant Field Values

MANDATORYATTR

public static final java.lang.String MANDATORYATTR

the mandatory attribute of the parameter tag

See Also:

Constant Field Values

NAMEATTR

public static final java.lang.String NAMEATTR

the name attribute of the parameter tag

See Also:

Constant Field Values

PROMPTATTR

public static final java.lang.String PROMPTATTR

the prompt attribute of the parameter tag

See Also:

Constant Field Values

SIZEATTR

public static final java.lang.String SIZEATTR

the size attribute of the parameter tag

See Also:

Constant Field Values

SOURCEATTR

public static final java.lang.String SOURCEATTR

the source attribute of the file tag

See Also:

Constant Field Values

intro

protected Element intro

An XML element whose value should be printed out as my introductory material; may include HTML markup.

payloadName

protected java.lang.String payloadName

name of my payload

payloadPath

protected java.lang.String payloadPath

location of my payload. Full or relative pathname or URL of the war archive which is my payload

stagePath

protected java.lang.String stagePath

location of my staging area. Full or relative pathname to a directory which the servlet has permission to write to and read from

Constructor Detail

BasicConfigurator

public BasicConfigurator()

Method Detail

init

public void init(Context config)
          throws InitialisationException

Read my config and set up my widgets

Specified by:

init in interface DocumentGenerator

Overrides:

init in class Form

Throws:

InitialisationException

getParameters

protected java.util.Vector getParameters(Context config)
                                  throws InitialisationException

Parse my parameters file, and return explicitly a list of my parameters. As side effects set up my list of files to process, my title, introduction and other identifying stuff.

Parameters:

config - the configuration of this servlet.

Returns:

a vector comprised of ConfigurationParameter objects which describe the configurable parameters of the webapp being configured

Throws:

InitialisationException

configure

protected void configure(Context context)
                  throws java.lang.Exception

actually do the work. Unpack the war, make the substitutions, repack the war, and deliver it.

Throws:

java.lang.Exception

deleteDir

protected void deleteDir(java.io.File target)

delete the file, or, recursively, the directory, passed as argument

Parameters:

target - the file or directory to delete

fetchPayload

protected java.io.File fetchPayload(java.io.File dir)
                             throws java.io.IOException

fetch my payload into the specified directory and unpack it there

Parameters:

dir - the directory into which I unpack

Returns:

the directory in which I unpacked

Throws:

java.io.IOException - if anyhing fails

fixXMLSyntaxChars

protected java.lang.String fixXMLSyntaxChars(java.lang.String tofix)

fix any XML syntax chars in tofix with the appropriate entities - unless they are themselves part of entities. TODO: this implementation is quite inefficient.

Parameters:

tofix - the string to be fixed.

Returns:

the fixed string.

patchFile

protected void patchFile(java.lang.String sourcepath,
                         java.lang.String destpath,
                         Context context)
                  throws SubstitutionException

patch the specified file by substituting the user-supplied values

Parameters:

sourcepath - the name of the file to patch

destpath - where to store the processed file

context - a context containing the substitutions to make

Throws:

java.io.IOException - if anything goes wrong

SubstitutionException

preForm

protected void preForm(Context context)
                throws java.lang.Exception

Say what we're currently delivering

Overrides:

preForm in class Form

Throws:

java.lang.Exception

preProcess

protected void preProcess(Context context)
                   throws DataStoreException,
                          javax.servlet.ServletException

Check tokens listed in NOAMPERSANDVALUESTOKEN for unprotected ampersands - useful for things which will be output in [X|HT]ML documents

Overrides:

preProcess in class Form

Parameters:

context - the context in which this response is being generated

Throws:

DataStoreException

javax.servlet.ServletException

repack

protected void repack(Context context,
                      java.io.File dir)
               throws java.io.IOException

repack the contents of the specified directory into a WAR archive file

Parameters:

dir - the directory to pack

Throws:

java.io.IOException - if anything goes wrong

validate

protected boolean validate(Context context)
                    throws ConfigurationException

determine whether or not to configure using this context. This method is designed to be specialised and is in fact the only method you should need to specialise. The default does nothing. In this method you could

1. check that parameter values are valid
2. check a password or license key, for example, to ensure that only authorised people can use this configurator
3. collect a credit card payment
4. do some processing on the parameter values given.

If you are satisfied with the context and wish the configuration to go ahead, return true. Otherwise, do not return false - instead, throw a ConfigurationException with your reason in the message. Otherwise your users will not know what is wrong.

Parameters:

context - the service context, containing values for all the configuration parameters

Returns:

true

Throws:

ConfigurationException - if you consider the context is not valid.

validatePayload

protected java.net.URL validatePayload(Context config)
                                throws InitialisationException

return a URL (possibly a file URL) for my payload, ideally having checked it exists and seems to be the right sort of thing

Parameters:

config - my servlet configuration

Returns:

the validated URL of my payload

Throws:

InitialisationException - if it can't be found

validateStage

protected java.io.File validateStage(Context config)
                              throws InitialisationException

validate that my stage exists, is a directory, and is writable by me; return it as a File.

Parameters:

config - my servlet configuration

Returns:

my staging area

Throws:

InitialisationException - if it can't be found or isn't writable