OPS User Guide
- Getting Started
- Tutorial
- Core Technologies Reference
- XForms
- Page Flow
- XML Pipelines (XPL)
- OPS Technologies Reference
- Processors Reference
- API Reference
- Integration
- Obsolete
|
Properties File
1. Overview
-
Rationale The OPS properties are used by some processors to configure
or customize their behavior. This section describes how the system is
configured, and lists all the customizable properties.
-
Properties File Location The properties sub-system is initialized after
the Resource Manager (the
properties being read like any other OPS resources). By default
it tries to load a file from the URL oxf:/properties.xml . This
value can be overridden in the Web application descriptor web.xmxl
with the oxf.properties initialization parameter:
<context-param> <param-name>oxf.properties</param-name> <param-value>oxf:/config/properties.xml</param-value> </context-param>
-
Automatic Reloading The property file is reloaded every time it is
changed, however some properties are taken into account only when the server is
first started.
-
Property types Properties have a type, which must be one of the
following XML Schema simple types: xs:anyURI ,
xs:integer , xs:boolean , xs:QName ,
xs:string , xs:date , xs:dateTime .
-
Global and Processor Properties There are two types of properties:
global properties that apply to the system as a whole, and processor-specific
properties. For instance, you set the cache size with a global property:
<property as="xs:integer" name="oxf.cache.size" value="200"/>
On the other hand setting the maximum amount of bytes that can be uploaded to
the server is set with a processor specific property. Note the additional
processor-name attribute:
<property as="xs:integer" processor-name="oxf:request" name="max-upload-size" value="100000000"/>
2. Global Properties
2.1. oxf.log4j-config
Purpose |
Configures the logging system |
Type |
xs:anyURI
|
Default Value |
The logging system not initialized with a warning if this property
is not present.
|
OPS uses the
Log4J logging
framework. Log4J is configured with an XML file conforming to the Log4J DTD. Here is a sample Log4J configuration:
<log4j:configuration xmlns:log4j="log4j"> <appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender"> <param name="Target" value="System.out"/> <layout class="org.apache.log4j.PatternLayout"> <param name="ConversionPattern" value="%-4r [%t] %-5p %c %x - %m%n"/> </layout> </appender> <catagory name="org.orbeon.oxf.processor.DebugProcessor"> <priority value="info"/> </catagory> <root> <priority value="error"/> <appender-ref ref="ConsoleAppender"/> </root> </log4j:configuration>
If this property is not set, the Log4J initialization is skipped. This is
useful if another subsystem of your application has already initialized Log4J
prior to the loading of OPS.
2.2. oxf.cache.size
Purpose |
Setup the size of the OPS cache |
Type |
xs:integer
|
Default Value |
200 |
OPS uses an efficient caching system. OPS
automatically determines what can be cached and when to expire objects. The
cache has a default size of 200, meaning that it can hold 200 objects. This size
is reasonable for most applications. A bigger cache tends to make the
application faster, but it uses more memory. To tune the cache, start the Java
VM with the -verbose:gc option. Then with the application under
typical load, look at the server logs and monitor:
- How often full garbage collections happen
- The value of the "success rate" reported by OPS after each page is generated
The "success rate" is the percentage of the objects needed to generate the pages
that were found in the cache. The closer this value is to 100%, the better. If
the success rate is too low (say below 70% with a mostly static site), then the
cache size should be increased. If full garbage collections happen too often,
then the VM heap size should be increased. On the other hand, if the success
rate is acceptable and garbage collections do not happen too often, you can
consider reducing the size of the cache and maybe even the heap size.
Tuning the VM heap size and cache size is not always needed and in most cases
the default values are acceptable.
2.3. oxf.validation.processor
Purpose |
Controls the automatic processor validation |
Type |
xs:boolean
|
Default Value |
Enabled |
Many processors validate their configuration input with a schema. This
validation is automatic and allows meaningful error reporting. To potentially
improve the performance of the application, validation can be disabled in
production environments. It is however strongly discouraged to do so, as
validation can highly contribute to the robustness of the application.
2.4. oxf.validation.user
Purpose |
Controls user-defined validation |
Type |
boolean
|
Default Value |
Enabled |
User-defined validation is activated in the XML Pipeline Definition Language with the
attributes schema-href and schema-uri . To potentially
improve the performance of the application, validation can be disabled in
production environments. It is however strongly discouraged to do so, as
validation can highly contribute to the robustness of the application.
2.5. oxf.prologue
Purpose |
Defines OPS processors |
Type |
xs:anyURI |
Default Value |
A default prologue is loaded automatically |
Loads a OPS prologue file, where processors are declared.
OPS is bundled with a default prologue file containing all
processors. You can create processors (see the processor API) and declare them in a
custom prologue. The custom prologue doesn't replace, but completes the default
prologue. It is possible to override a default processor with a custom
implementation by binding it to the same URI as the default processor. The
following example shows a simple custom prologue declaring an hypothetical
processor:
<processors> <processor name="oxf:myprocessor"> <class name="com.company.oxf.MyProcessor"/> </processor> </processors>
2.6. sax.inspection
Purpose |
Enable inspection SAX events |
Type |
xs:boolean |
Default Value |
false |
SAX is the underlying mechanism in OPS by which processors
receive and generate XML data. Given only the constraints of the SAX API, it is
possible for a processor to generate an invalid sequence of SAX events. Another
processor that receives that invalid sequence of events may or may not be able
to deal with it without throwing an exception. Some processors try to process
invalid SAX events, while others throw exceptions. This means that when a
processor generating an invalid sequence of SAX events is used in a pipeline,
the problem might go unnoticed, or it might cause some other processor
downstream to throw an exception.
To deal more efficiently with those cases, the sax.inspection
property can be set to true . When it is set to true, the pipeline
engine checks the outputs of every processor at runtime and makes sure that
valid SAX events are generated. When an error is detected, an exception is
thrown right away, with information about the processor that generated the
invalid SAX events.
There is a performance penalty for enabling SAX events inspection. So this
property should not be enabled on a production system.
3. Java Processor Properties
3.1. Class Path
Name |
classpath |
Purpose |
Defines a directory where Java class files are located. The
Java processor dynamically
compiles Java code, and may need some libraries. This property
defines the classpath used by the compiler.
|
Processor name |
oxf:java |
Type |
xs:string |
Default Value |
None |
3.2. JAR Path
Name |
jarpath |
Purpose |
Defines a list of directories where JAR files are located. The
Java processor dynamically
compiles Java code, and may need some libraries. This property
defines a "JAR path", a list of directories containing JAR files
that will be added to the classpath when compiling and running
the processor executed by the Java processor.
|
Processor name |
oxf:java |
Type |
xs:string |
Default Value |
None |
3.3. Compiler JAR
Name |
compiler-jar |
Purpose |
Define a URL pointing to a JAR file containing the Java compiler to
use. If this property is set, the Java
processor adds the specified JAR file to the class path used
to search for the main compiler class.
|
Processor name |
oxf:java |
Type |
xs:anyURI |
Default Value |
If the property is not specified, the Java processor tries to load
the main compiler class first using the current class loader. If
this fails, it retrieves the java.home system property
which specifies a directory on disk. If that directory is called
jre , and there exists a JAR file relative to that
directory under ../lib/tools.jar , that JAR file is
added to the class path used to search for the main compiler class.
This covers most cases where the standard Sun JDK is used, so that
the compiler-jar property does not have to be
specified.
|
3.4. Compiler Main Class
Name |
compiler-class |
Purpose |
Define a class name containing the Java compiler to use. The Java processor loads the corresponding
class and calls a static method on this class with the following
signature: public static int compile(String[] commandLine,
PrintWriter printWriter) .
|
Processor name |
oxf:java |
Type |
xs:string |
Default Value |
com.sun.tools.javac.Main
|
4. Email Processor Properties
4.1. Global SMTP Host
The following property can be specified globally as a property instead of
being part of the processor configuration:
Name |
smtp-host |
Purpose |
Configure the SMTP host for all email processors. This global
property can be overridden by local processor configurations.
|
Processor name |
oxf:email |
Type |
xs:string |
Default Value |
None |
The following properties can be used for testing purposes:
4.2. Test SMTP host
Name |
test-smtp-host |
Purpose |
Configure a test SMTP host for all email processors. This global
property when specified overrides all the other SMTP host
configurations for all Email processors, whether in the processor
configuration or using the smtp-host property.
|
Processor name |
oxf:email |
Type |
xs:string |
Default Value |
None |
Note
This property replaces the deprecated smtp property.
4.3. Test Recipient
Name |
test-to |
Purpose |
Configure a test recipient email address for all email processors.
This global property when specified overrides all the other SMTP
recipient configurations for all Email processors.
|
Processor name |
oxf:email |
Type |
xs:string |
Default Value |
None |
Note
This property replaces the deprecated forceto property.
For example, those properties can be used as follows:
<property as="xs:string" processor-name="oxf:email" name="smtp-host" value="mail.example.org"/> <property as="xs:string" processor-name="oxf:email" name="test-smtp-host" value="test.example.org"/> <property as="xs:string" processor-name="oxf:email" name="test-to" value="joe@example.org"/>
The test properties can easily be commented out for deployment.
5. XPL Profiling Properties
5.1. Trace Class
Name |
processor.trace |
Purpose |
Specify the name of a class that implements the interface
org.orbeon.oxf.pipeline.api.PipelineContext.Trace .
|
Type |
xs:NCName |
Default Value |
None |
Note
OPS ships with two implementations of Trace,
org.orbeon.oxf.processor.NetworkTrace and
org.orbeon.oxf.processor.StdOutTrace .
NetworkTrace sends profiling information to Studio which the
displays the data in the trace views. StdOutTrace simply
dumps profiling information to standard out.
5.2. Network Trace Host
Name |
processor.trace.host |
Purpose |
Specify the host name that
org.orbeon.oxf.processor.NetworkTrace will send data
to.
|
Type |
xs:NMTOKEN |
Default Value |
localhost |
5.3. Network Trace Port
Name |
processor.trace.host |
Purpose |
Specify the port that
org.orbeon.oxf.processor.NetworkTrace will send data
to.
|
Type |
xs:nonNegativeInteger |
Default Value |
9191 |
|