Configuring imago.properties
The
imago.properties file defines
the basic parameters of the servlet. In addition extension elements often require their
configuration to be placed here as well. The file is separated into sections:- Global Configuration
- Initialization Options
- Launcher Configuration
- SAX Parser
- Cache Manager
- TimedWatchableContainer
- Client Types
- Process Map
- Custom Extension Configuration
errors.internally=true- Indicates whether Imago should handle errors internally by sending the error and
exception stack trace to the client or return the HTTP error code to the web server
to be handled.
errors.environment=true- Dumps the XSLT environment to the log at startup and on error. If errors are
handled internally the environment is also appended to the end of any error page.
errors.404=- Specify a file not found page
errors.500=- Specify a generic server error page
container.2.2=org.xenei.imago.framework.containers.Container2_2- The class that implements the servlet container version-specific methods.
In this case it is specifically for a version 2.2 container.
container.1.0=org.xenei.imago.framework.containers.Container1_0- The class that implements the servlet container version-specific methods. In this case it is specifically for a version 1.0 container.
org.xenei.imago.framework.containers.Container2_2 would be used.All initialization-time options begin with the
init prefix.
init.query.0=http://www.imago.org/index.xml
init.query.1=http://www.imago.org/aBigDocument.xml- The initial queries to execute. Initialization queries are sent to Imago after
the init.delay timeout. The intention is to provide a method to "preload"
some of the data structures. To preload the cache it is recommended that these
queries request fairly complex documents. The queries are performed sequentially.
init.delay=5000- The delay in milliseconds between the time the servlet init routine ends and the first init.query is sent. On heavily loaded systems this may need to be in the 5-10 second range.
The launcher is used to speed-up processing for classes
that are either all static method extension elements or are specifically designed to
be thread safe. The launcher creates and registers an instance of each class listed then
passes it control when needed. This eliminates the overhead of creating an instance of
the class during the request. All launcher options begin with the
launcher
prefix.
init.Launcher.classes.0=Forms- The first launcher class. In this case called
Forms. init.Launcher.classes.1=Counter- The second launcher class. In this case called
Counter. init.Launcher.class.Forms=org.xenei.imagoX.forms.ImagoForm- Defines the class for the Forms launcher. In this case a forms processor defined
in the ImagoX packages.
init.Launcher.init.Forms.number=org.xenei.imagoX.forms.NumberValidator
init.Launcher.init.Forms.date=org.xenei.imagoX.forms.DateValidator
init.Launcher.init.Forms.choice=org.xenei.imagoX.forms.ChoiceValidator
init.Launcher.init.Forms.image=org.xenei.imagoX.forms.ImageValidator
init.Launcher.init.Forms.email=org.xenei.imagoX.forms.EmailValidator- Defines the initialization parameters for the Forms class. The
init() method of class org.xenei.imagoX.forms.ImagoForm will be called with a Configurations
object containing the lines above with the init.Launcher.init.Forms prefix removed.
init.Launcher.class.Counter=org.xenei.imagoX.counter.ImagoCounter- Defines the class for the Counter launcher. In this case a hit counter implemented
in the ImagoX packages.
init.Launcher.init.Counter.class=org.xenei.imagoX.counter.FileCounterData
init.Launcher.init.Counter.init.directory=/tmp- Initialization information needed by the Counter class that implements a file-based
hit counter.
init.Launcher.init.Counter.class=org.xenei.imagoX.counter.DBCounterData
init.Launcher.init.Counter.init.db.driver=org.gjt.mm.mysql.Driver
init.Launcher.init.Counter.init.db.host=jdbc:mysql://xenei.org/imagoData
init.Launcher.init.Counter.init.db.user=imago
init.Launcher.init.Counter.init.db.password=imago- Initialization for the Counter class that uses a MySQL database to store the hit counts. Any database supported by LDBC may be used.
sax.parser.class=org.apache.xerces.parsers.SAXParser- The SAX parser to use. If the parser is not defined the default system parser will be used.
SAX Parser FeaturesThis area is rather odd but necessary due to the way properties work.
If http://url is used as part of the name, the properties strip off the "http" and
make it the key. Thus the following construct may be used:
Example:
sax.feature.n=arbitrary_name causes
sax.feature.arbitrary_name.url and
sax.feature.arbitrary_name.state to be read and processed.
Example:
sax.feature.0=namespaces
sax.feature.1=prefixes
sax.feature.2=java-encodings- The list of features we are defining.
sax.feature.namespaces.url=http://xml.org/sax/features/namespaces- The URL for the namespaces feature.
sax.feature.namespaces.state=true- The state we are requesting, true or false.
sax.feature.prefixes.url=http://xml.org/sax/features/namespace-prefixes
sax.feature.prefixes.state=true- The prefixes configuration.
sax.feature.java-encodings.url=http://apache.org/xml/features/allow-java-encodings
sax.feature.java-encodings.state=true- The java-encodings configuration.
Define the desired cache configuration. There are several cache
options to choose from. The various types of caches are explained here:
This configuration is not recommended. Without a cache Imago is required to generate complete transforms for each request. A well-tuned cache can significantly increase performance.
- The No Cache option.
- The Memory Cache option.
- The DB Cache option.
- The Slow Cache wrapper.
- The Xenei Cache two-level mechanism.
This configuration is not recommended. Without a cache Imago is required to generate complete transforms for each request. A well-tuned cache can significantly increase performance.
cache=org.xenei.util.cache.NoCache- Defines a cache that does nothing. It always accepts entries and never has anything cached.
Imago is shipped with the Memory Cache enabled.
cache=org.xenei.util.cache.memcache.MemoryCache- Specifies the MemoryCache as the cache.
cache.cacheclass=java.util.HashMap- Specifies that the cache should use the standard HashMap to store data internally.
Any class that implements
java.util.Mapmay be used. cache.reaper.maxage=30- The maximum age in minutes of a cache entry before it is considered stale and removed.
cache.reaper.period=45- The period in minutes between sweeps of the cache for stale objects. This number
should be larger than the
maxageparameter. cache.reaper.priority=1- The thread priority that the reaper will run with. If this is not set then
the priority of the scheduler will be used.
cache.mem.min=1- The minimum free heap in MBs. This is the number of MBs required to be free when
the cache is operating. If the free memory drops below this number the cache attempts
an emergency clean of stale objects until the minimum free memory is achieved or the
cache is disabled.
cache.mem.max=4- This is the maximum memory used by the application. It is not possible to
differentiate between cache and non-cache items. If this limit is exceeded then
an emergency clean of stale objects is attempted.
cache.lock.maxage=10- The maximum age of a cache lock in seconds. If a lock exceeds this age it is
assumed to be abandoned and may be broken.
cache.lock.wait.count=5- The maximum number of times a thread should wait for a cache lock before giving
up and proceeding to rebuild the object. If this is set too low the cache will build
unnecessary objects, if too high the system will slow down waiting for locks when it
could rebuild the object faster.
cache.lock.wait.time=100- The number of timer ticks in milliseconds the thread should wait between attempts to get a cache lock.
The DBCache utilizes a database. This can make it easy for
multiple Imago servers to synchronize their caches. This can be particularly useful
if Imago is being run in a clustered environment.
cache=org.xenei.util.cache.dbcache.DBCache- Use the DBCache.
cache.driver=com.mysql.jdbc.Driver- The JDBC driver to use. This must be a driver and database supported by LDBC.
cache.url=jdbc:mysql://db.xenei.org/imago- The URL for the database.
cache.user=imago- The user ID for the database.
cache.password=imago- The password for the database.
cache.reaper.period=15- The period in hours between sweeps of the cache for expired objects. In the
DB cache an object is expired if it has changed. The reaper reads and validates
every object in the table.
cache.reaper.priority=1- The thread priority the reaper will run with. If this is not set
the priority of the scheduler will be used.
cache.lock.maxage=10- The maximum age of a cache lock in seconds. If a lock exceeds this age it is
assumed to be abandoned and may be broken.
cache.lock.wait.count=5- The maximum number of times a thread should wait for a cache lock before giving
up and proceeding to rebuild the object. If this is set too low the cache will
build unnecessary objects, if set too high the system will slow down waiting for
locks when it could rebuild the object faster.
cache.lock.wait.time=100- The number of timer ticks in milliseconds the thread should wait between attempts to get a cache lock.
The slow cache does not perform caching itself. It is used
to wrap a slower caching implementation. For example a remote database cache may
be too slow for regular operation but by wrapping it in a slow cache there is some
speed improvement.
cache=org.xenei.util.cache.slowcache.SlowCache- Use the slow cache wrapper.
cache.wraps=org.xenei.util.cache.dbcache.DBCache- Define a wrapping of a database cache.
cache.wraps.driver=com.mysql.jdbc.Driver
cache.wraps.url=jdbc:mysql://db.xenei.org/imago
cache.wraps.user=imago
cache.wraps.password=imago
cache.wraps.reaper.period=15
cache.wraps.reaper.priority=1
cache.wraps.lock.maxage=10
cache.wraps.lock.wait.count=5
cache.wraps.lock.wait.time=100- The DB cache options.
The Xenei Cache is a two-level cache mechanism. This is
particularly useful if you want to have a shallow cache for frequently used objects
and a deeper cache for less frequently used objects, such as an in-memory cache
backed by a database cache.
cache=org.xenei.util.cache.xeneicache.XeneiCache- Use the Xenei Cache.
cache.synchronizedlocks=false- Synchronized locks requires that both level1 and level2 caches be locked
before a lock is returned. Otherwise the first level lock is tried and if it
succeeds the second level is tried; regardless of the result of the second
level lock the lock is returned.
cache.level1=org.xenei.util.cache.memcache.MemoryCache- Level 1 uses the memory cache.
cache.level1.cacheclass=java.util.HashMap
cache.level1.reaper.maxage=30
cache.level1.reaper.period=45
cache.level1.reaper.priority=1
cache.level1.mem.min=1
cache.level1.mem.max=4
cache.level1.lock.maxage=10
cache.level1.lock.wait.count=5
cache.level1.lock.wait.time=100- The memory cache definition.
cache.level2=org.xenei.util.cache.slowcache.SlowCache- Level 2 uses the slow cache wrapper.
cache.level2.wraps=org.xenei.util.cache.dbcache.DBCache- It is wrapping a database cache.
cache.level2.wraps.driver=com.mysql.jdbc.Driver
cache.level2.wraps.url=jdbc:mysql://db.xenei.org/imago
cache.level2.wraps.user=imago
cache.level2.wraps.password=imago
cache.level2.wraps.reaper.period=15
cache.level2.wraps.reaper.priority=1
cache.level2.wraps.lock.maxage=10
cache.level2.wraps.lock.wait.count=5
cache.level2.wraps.lock.wait.time=100- The DB cache options.
The timed watchable container periodically scans TimedWatchable
entries and updates their timestamps. If the entry is stale (untouched) it is removed
from the cache. Changes to source files will only be detected during a scan.
The cache is implemented with a SoftReference so any items may be removed by the garbage collector when trying to free up heap space. This only works if the time check value is fairly high with respect to the demands on the system.
The cache is implemented with a SoftReference so any items may be removed by the garbage collector when trying to free up heap space. This only works if the time check value is fairly high with respect to the demands on the system.
timedwatchable.timecheck=30- The frequency in minutes at which the cache is scanned (default 30 minutes). Setting
timecheck value to 0 (zero) forces a timecheck on every request. This is useful on a
development system.
timedwatchable.priority=1- The priority at which the scanning thread runs (default Thread.NORM_PRIORITY).
timedwatchable.maxage=15- The maximum age in minutes of an untouched entry (default 15 minutes). If an entry has not been used within this time it is removed.
clientmap=/WEB-INF/ClientMap.xml- The URL location and name of the ClientMap.xml file, relative to the Imago servlet content directory.
processmap=/WEB-INF/ProcessMap.xml- The URL location and name of the ProcessMap.xml file, relative to the Imago servlet content directory.
These are the extensions available in the ImagoX or imago.extensions package.
The ImagoX Counter extension implements either a file-based or database-based "hit" counter.
The Counter Extension configuration is discussed in ImagoX Counter Extension. Further information is shown in the Launcher Configuration section.
The Counter Extension configuration is discussed in ImagoX Counter Extension. Further information is shown in the Launcher Configuration section.
ImagoX Forms is an extensible HTTP GET/POST mechanism
that provides field validation, validation error marking, and is resistant to hack attempts
because Forms ignores valid input and extraneous input fields.
The Forms Extension configuration is discussed in ImagoX Forms Extension. Further information is shown in the Launcher Configuration section.
The Forms Extension configuration is discussed in ImagoX Forms Extension. Further information is shown in the Launcher Configuration section.
ImagoX Mail can send email to one or more "to" or "bcc" addresses,
and HTML markup may be included.
The Mail Extension configuration is discussed in ImagoX Mail Extension.
The Mail Extension configuration is discussed in ImagoX Mail Extension.