Jump to ID:
  Project: xmlprocess  [Show Path]

Project Home

Tracker

Documents

Source Code

Discussions

Reports

File Releases

Wiki

Project Info
xmlprocess

XML tools from CFH
Project Created: 02/27/2008
Project Categorization
forge
Project Members
Total Project Members: 12
Project Administrators:
adam.flinton
Site Administrator
Configuration File settings
Configuration File guide

Table of Contents:


  1. Basics
  2. Where to find the <CONFIGFILE>
  3. Setting the <CONFIGFILE>
  4. Basic Settings
    1. Setting the applicationRoot
    2. Setting the fileIO
    3. Running as a Remote Server
  5. Adding an Application
    1. Vital Values - These values are required in order for an application to function.
    2. Defaulted Values - These values are required but have an acceptable default value so only need adding if it's a change away from the default.
    3. Optional Values - These values are optional.
    4. File Applications - A very specific type of application which deals with File operations

(1) Basics :

  • The configuation file is an XML file.
  • By default it is called main.xml
  • It will be referred to henceforth as <CONFIGFILE>

(2) Where to find the <CONFIGFILE>


Assuming the application has come as a Web Archive (War) file and has been deployed inside tomcat
To find where it is, find where you installed tomcat (I will call this directory " <TOMCAT_HOME> ").
The Web app will be in:
<TOMCAT_HOME>\webapps\xmlprocess

The configuration properties file can be found at

<TOMCAT_HOME>\webapps\xmlprocess\config\main.xml

(3) Setting the <CONFIGFILE>


The <CONFIGFILE> name and path is set in the web.xml which is a standard java web application file and is found in:

<TOMCAT_HOME>\webapps\xmlprocess\WEB-INF

In the web.xml look for a piece of XML called context-param where the param-name is mainxml :

<context-param>
<param-name>mainxml</param-name>
<param-value>config/main.xml</param-value>
<!-- <description> The main xmlprocess configuration file </description>-->
</context-param>


You can set this value to be :
  • A Relative URL such as it is by default e.g. config/main.xml
  • An absolute URL such as http://myserver/myconfigdir/main.xml
  • A local path such as c:\myconfigdir\main.xml
  • Any of the above using a different filename e.g. c:\mynewdir\MyNewNameForMain.xml
This gives you the facility to have the configuration file outside of the web application which can be usefull either for maintaining a single configuration file for multiple servers (if using the absolute URL facility) or where the application server autodeploys in such a way as to make it hard to keep the settings between redeployments for example if deploying in JBOSS.

If you are going to require this change repeatedly, it is best to make your changes in the source tree and the deploy it with this change in place. See Advanced Building and Deploying for details

(4) Basic Settings:


There are some basic Settings which you can configure.
Basic Settings are contained within a piece of XML which look like this:

<BasicSettings jspRoot="jsp-app" applicationRoot="Applications"
fileIO="file"
remoteServer="false"
docRoot="C:\TestDocumentation\test"
xformUrl="xformEndpoint" debugFile="">
<JSFBeans>
<JSFBean name="DomElementBean" value="DOMElement" />
</JSFBeans>
</BasicSettings>

Of these setting the ones you may need to change are:
  • applicationRoot
  • fileIO
  • remoteServer
  • docRoot

(A) Setting the applicationRoot


The applicationRoot sets the root folder in which the system can find applications should they not be specified with an exact URL or file path You can set this value to be :
  • A Relative URL such as it is by default e.g. Applications
  • An absolute URL such as http://myserver/Applications
  • A local path such as c:\Applications
  • Any of the above using a different filename e.g. c:\MyNewAppsDir
See the section below dealing with adding Applications for more details

(B) Setting the fileIO


The fileIO setting tells the system which file handler it should use. This is an application and is detailed here.
The value is the name of the application you wish to use as your file handler.

(C) Running as a Remote Server


You can use XMLProcess either as a local web app if you have Tomcat installed locally or as a remote server for many people.

If you wish to use it as a remote web server you must set the remoteServer attribute to a value of true i.e.

remoteServer="true"

It will then allow people to browse a directory using JSP to render the directories and their contents.

In the interests of safety you must set a root folder which you will not be allowed to browse outside of. If no root folder is set then you will see no files or directories when you click browse on the front page.

You do this by setting a file path in the docRoot attribute e.g.

docRoot="C:\TestDocumentation\test"
If remoteServer is set to false then it will simply ignore the docRoot setting

(5) Adding an Application :


Now you need to tell the application what to do when it runs into something of a given type.
These values are stored as attributes in an Application element (one per application) which itself within an Applications element e.g.

<Applications>
<Application name="ExampleApp" typeHome="ExampleAppDir"
backingFile="ExampleApp_backingfile.xml" jspTree="No"
formTitle="ExampleApp"
indexText="Please choose your ExampleApp File"/>
</Applications>


This information is placed in the <CONFIGFILE> and can be broken down into 4 main categories :
  1. Vital Values - These values are required in order for an application to function.
  2. Defaulted Values - These values are required but have an acceptable default value so only need adding if it's a change away from the default.
  3. Optional Values - These values are optional.
  4. File Applications - A very specific type of application which deals with File operations.

(A) Vital Values:


The main attributes settings are
  1. name
  2. typeHome
  3. backingFile

(i) name :


The name is what defines the application.
It must be unique within the group of applications

(ii) typeHome :


The typeHome sets the folder in which the system can find all the text based application specific files
such as XSLT files, XForms, schemas, xml files etc.
It can be a relative URL, an absolute URL or a filepath.

By default it uses the value set in applicationRoot as the starting point for any relative URL.
For example if the applicationRoot was "ExampleAppRoot" and the typeHome was "ExampleAppDir"
then the system would look to see if there was a folder with a relative URL of ExampleAppRoot/ExampleAppDir .

(iii) backingFile :


The backing file is the name/URL of the backing file which is used to tell the system what do do with a given XML document at the level of that document
e.g. what XForm or XSLT sheet to load for a given Element within that document.

It can be a relative URL, an absolute URL or a filepath.

By default it uses the value set in typeHome as the starting point for any relative URL.

For example if the typeHome was "ExampleAppDir" and the backingFile was "ExampleApp_backingfile.xml"
then the system would look to see if there was a file with a relative URL of ExampleAppDir/ExampleApp_backingfile.xml .

Given an applicationRoot and using the example above, with a relative url the full relative URL would be:
ExampleAppRoot/ExampleAppDir/ExampleApp_backingfile.xml

(B) Default Values:


These are values where the default setting is usually sufficient & thus do not need to be set.
The place that these values are taken from is the "xml" application ie

<Application name="xml" typeHome="xml" jsfAction="XMLAction.jsp"
jspTree="XFormTree.jsp" jspAction="XFormMain.jsf"
jsfeditor="XMLJSFEditor.jsp" jspRenderer="RenderAction.jsp"
jspXsltActions="XSLTActionsChoice.jsp"
typeClass="org.xmlprocess.jsf.tree.XpathTreeNode"
forwardAction="/index.jsp" />

The Values are:
  • type - Only needed if creating a File Application.
  • typeClass - Only needed if creating a File Application or creating your own JSF tree java class see JSFTree handling class.
  • fileIO - Value is taken from the BasicSettings fileIO setting by default and defines which file application this application should use.
  • jspAction - Defines which is the main JSP/JSF page which should be used to load the application.
    Only If you were to write a replacement for XFormMain.jsf for a specific application and wished to use it would you change this.
  • jspXsltActions - An Action Page which allows a user to action any XSLT actions defined in the backing file
  • jspTree - A JSF Page which provides a tree on the left hand side of the page for use in navigation (see JSFTree).
    If you do NOT require a tree this value must be set to No
  • jsfAction - An Action Page which allows the user to interact with the document using JSF actions.
    You can set this to a JSF page of your choice, however it does provide standard actions defined via the backing file
    Such as adding and removing elements etc. If you wish add additional actions consider instead adding the optional jsfAction1 value.
  • jspRenderer - An Action Page which if render actions are defined in the backing file (for example to turn the XML into HTML or SVG
    then this page will give the user the relevant actions.
  • forwardAction - Tells the System where to go to by default. Usually will not be needed

(C) Optional Values:

  • jsfAction1 - An Action Page which allows the user to interact with the document using JSF actions.
    To be used if jsfAction does not provide all the actions you require but you wish to keep it.
  • jsfEditor - If you wish to use a JSF based editor rather than an XForms based one then use this value.
  • hasExternalDataFile - If you have a file which will not change very often then you can set this and
    the filename will be persisted & used by default. i.e. once set you will not have to choose it again (though you can reset it).
  • formTitle - The title of the form which you can use if adapting the JSF pages
    Basically some text which you can set & will then be returned.
  • indexText - The Text which appears on the index page when choosing a file.

(D) File Applications:


Background:
  • A File application is a specific sort of Application which provides file handling to the system
  • It is used to load and save the XML files the users wish to edit/view
  • Current examples include the default FileUrlRW application, whose configuration is shown above.
  • Anything which can load and persist a file could be used from Source Control Systems (e.g. CVS or Subversion)
    to a message based (e.g. JMS) system to a http/webservice based system to a workflow system.
An example of a File Application:

<Application name="file" typeHome="io/file"
typeClass="org.xmlprocess.io.FileUrlRW"
jsfAction="FileActions.jsp" type="FileIO"/>


As with any Application a File Application must define However a File Application does NOT need or use a backingFile

Other than name and typeHome, a File Application must define 2 things:
  1. typeClass - A Class which implements org.xmlprocess.io.FileRW
  2. jsfAction - An Action Page which allows the user to use the File Application (e.g. by providing buttons, links, dropdown choices etc.)
  3. type - This must be "FileIO"