$Id: config.xml,v 1.15 2011/02/18 05:20:55 hannes Exp $
Copyright © 2006 - 2012 Hannes Holtzhausen
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Table of Contents
This document will serve as a reference to all Toolbox related configuration documents. The document will be devided into two sections:
XML Configuration Documents - This section will cover the structure and purpose of all the XML configuration documents used by the various API's of the Toolbox.
Java Properties Files - This section will cover the Java properties files used by the various API's of the Toolbox.
Most Toolbox configuration settings are expressed in XML configuration documents.
XML conveys information on two levels; structure and content. It is possible to convey the purpose of the configuration through the way it is structured. The structure also allows the user or reader of the configuration to form a logical picture of how the various configuration settings interact. The Toolbox XML configuration documents, in some instances, follow the structure of the actual API that will consume and use the configuration, providing the user with some insight into the design of the API.
At this point, this document makes a departure from some of the conventions adopted to document XML configuration documents. A decision was made not to express the structure of the XML configuration documents in HTML tables, but to rather keep to the most natural way of defining XML structure; Document Type Definitions - DTD's. A couple of reasons exist for this decision:
The DTD specification was designed to define SGML and XML structure.
Provides the XML novice with an introduction to DTD's.
The author of this document only has to maintain one set of XML configuration reference material :).
The following table will provide information regarding each type of XML configuration document. A link will be provided to an HTML version of the DTD. At this point I need to thank Robert Stayton (http://www.sagehill.net/) for his livedtd utility. All HTML versions of the DTD's were generated using this useful utility.
Table 1. XML configuration table
| DTD | API Package(s) | Description |
|---|---|---|
| ServiceRegistry | toolbox.services | Defines the structure of XML instance documents used to configure the Toolbox Services API. |
| DaoManager | toolbox.dao,toolbox.services.dao | Defines the structure of XML instance documents used to configure implementations of the toolbox.dao.DaoManager interface. |
| ORMConfig | toolbox.dao.orm | Defines the structure of XML instance documents used to configure the toolbox.dao.orm.ORMQueryServiceImpl implementation of the toolbox.dao.orm.ORMQueryService interface. |
| FTPManager | toolbox.ftp,toolbox.services.ftp | Defines the structure of XML instance documents used to configure implementations of the toolbox.ftp.FTPManager interface. |
| LDAPManager | toolbox.ldap,toolbox.services.ldap | Defines the structure of XML instance documents used to configure implementations of the toolbox.ldap.LDAPManager interface. |
| MailManager | toolbox.mail,toolbox.services.mail | Defines the structure of XML instance documents used to configure implementations of the toolbox.mail.MailManager interface. |
| JmsManager | toolbox.jms,toolbox.services.jms | Defines the structure of XML instance documents used to configure implementations of the toolbox.jms.JmsManager interface. |
| SocketClientManager | toolbox.socket,toolbox.services.socket | Defines the structure of XML instance documents used to configure implementations of the toolbox.socket.SocketClientManager interface. |
| UDDIManager | toolbox.uddi,toolbox.services.uddi | Defines the structure of XML instance documents used to configure implementations of the toolbox.uddi.UDDIManager interface. |
| WebConfig | toolbox.web | Defines the structure of XML instance documents used to configure the ControllerServlet class. |
| ViewServlet | toolbox.web | Defines the structure of XML instance documents used to configure the ViewServlet class. |
| Permissions | toolbox.web | Defines the structure of XML instance documents used to configure the PermissionFilter class. |
| Validator | toolbox.web.validation | Defines the structure of XML instance documents used to configure the FieldValidator class. |
The Toolbox utilises Java Properties files in a few places to configure some basic parameters. This section will provide an overview of these properties files.
The ServiceRegistryFactory provides the entry point into the Toolbox Services API. For the Factory to be able to initialse ServiceRegistry instances it must be able to locate the relevant XML configuration documents. The Factory utilises a simple Java Properties file to accomplish this. The file specification is as follows:
# <registry name>=<config file>
myservices=/opt/applications/myservices/etc/services.xml
The location of the file is configured using the
toolbox.services.ServiceRegistryFactory.config
Java System Property.
The toolbox.web package provides a mechanism to perform finalisation when a web application is unloaded from a servlet container. The Toolbox provides a simple convenience implementation to destroy a specific ServiceRegistry instance when a web application is unloaded. The name of the registry is obtained from a properties file with the following specification:
# registry=<registry name>
registry=myservices
The toolbox.allegato.XMLProperties class provides the required functionality to parse and access XML configuration documents. In most cases where software is developed and maintained, various environments are involved. This may imply that different configuration settings exist for each environment. This in turn may require multiple versions of configuration files to be maintained.
The XMLProperties class provides a pre-processor mechanism that allows for the manipulation of the XML stream before it is parsed. A default pre-processor implementation, the toolbox.allegato.PropertyPreprocessor, provides functionality to define a set of substitution variables in a Java Properties file. These properties can be referenced in any XML configuration document, parsed by the XMLProperties class, using the syntax:
${<property>}
NOTE
The toolbox.allegato.PropertyPreprocessor is implemented using the FreeMarker template engine. This means that each XML configuration is a FreeMarker template when using this pre-processor. Please reference the toolbox.allegato API documentation for more details.