Overview:
How does MorganaXProc's configuration work?
MorganaXProc has a set of configuration properties you can use to change its behaviour. Before we will discuss this properties and their influence in detail, we will first have to talk about the configuration mechanism as a whole.
Configurating MorganaXProc is a multi level process where every level will either take the settings of the previous levels or overwrites the settings of a previous level with its own settings. Sounds complicated to you? If you are familiar with css and it cascading style definitions for a html document: This is exactly the same idea, MorganaXProc uses to configurate itself. To make it more concrete:
- The first level of configuration is built into MorganaXProc. On start up every property will get its default value. While you cannot influence the first level settings, you can influence every further level by writing a configuration file (or by calling the appropriate Java methods).
- On the second level of configuration, MorganaXProc will try to find a file called "xproc-config.xml" in the same folder as "MorganaXProc.jar" and set the properties mentioned in this file to the values found there. Any property not mentioned is left unchanged, so it keeps its first level value.
- You can add a third, fourth, ... level of configuration by using the "-config:" element with the uri of a configuration file in MorganaXProc's command line interface we discussed in another document.
So the basic thing about configurating MorganaXProc is to write a configuration file with the values you want the settings to have and then call it. So your next question probably is:
What should a configuration file look file?
Because MorganaXProc is all about xml, the configuration files are of course xml documents. The name and the extension you choose for this files is completely up to you with the notable exception of the configuration document for level two (Remember? You cannot influence the first level of configuration - it is built in, but you can control the second level).
For the second level you have to provide a file named "xproc-config.xml" in the same folder as "MorganaXProc.jar". The configuration in this file will be used automatically every time MorganaXProc starts up, so it is probably a good idea to put your favorite settings into this file. Actually if you look into the "MorganaXProc" folder on your computer, you will find a file named "xproc-config.xml". This file contains the factory settings, but of course you can put any setting you like into this file.
For MorganaXProc to recognize the properties you would like to change, the document must of course have a certain structure we will discuss now. First, it must have a root element named "config" which has to be in MorganaXProc's namespace "http://www.xml-project.com/morgana". The actual configuration settings are the child elements of "config", where the element names are associated with the properties to set. And: These elements also have to be in MorganaXProc's namespace. In other words: MorganaXProc will only respect elements in its namespace. Elements in another or no namespace are ignored. The elements have to have an attribute named "value" (otherwise they are ignored as well), and the value of this attribute is set to the named configuration property. This is the general rule, applying for most property settings. But as there is (almost) no rule without exception, we will soon discover property values not set by the "value"-attribute. The principle structure of a configuration file should therefore look like this:
<mox:PropertyName value="PropertyValue" />
...
<mox:PropertyName value="PropertyValue" />
</mox:config>
There is another caveat: The configuration files themselves are not cascading, which means you can not set a property twice in one configuration file. For most properties (though not for all) MorganaXProc will only respect the first element with a property name, any other with the same name will be ignored. Please take this as a debugging hint if your MorganaXProc does not behave as expected: May be you have two elements with the same name and the value you want to the property to have is in the second (and therefore ignored) element.
So, you know how MorganaXProc's configuration process works and you know what a configuration file should (in principle) should look like. But,
Which properties can be set for MorganaXProc?
Well, there are a lot. So the following table is rather long. It contains all configuration properties MorganaXProc supports in alphabetical order. Most of the properties will be explained in full detail, but as some of them belong to MorganaXProc's security system or are used to enhance MorganaXProc with third party software, we will have only a brief description here and leave the detailed discussion for the respective sections.
| Property name | Property description | Default value |
|---|---|---|
| CompilerInfoStreamURI | With the CompilerInfoStreamURI property you can control, whether the compiler writes compilation infos or not and where this infos are written. By default the compiler does not emit any infos, but when you set CompilerInfoStreamURI to any other value than null, it will emit compiler infos.If CompilerInfoStreamURI is set to System.out or System.err, the compiler will write the information to the respective output stream. Any other value is interpreted as an uri and the compiler will try to write out his infos to the resource designated to this uri. The uri can be absolute or relative. In the latter case, the uri of you user home folder is used to make it absolute. |
null, so no compiler compiler infos are generated. |
| DefaultXPathVersion | This property controls the version of XPath used by MorganaXProc, when a pipeline has no explicit request for a specific XPath version with @xpath-version. The value must be a supported XPath version ("1.0", "2.0" or "3.0"). Setting another value will raised an error. See here for more details. | 2.0 |
| DependencyMapURI | With this property to can tell MorganaXProc's compiler to create a dependency map and to store it to the given uri or to "System.out". The dependency map is basically a debugging aid, showing you the connections between the ports of the different steps in a subpipeline. | null, so no dependency map is generated. |
| DebugInfoStreamAppend | With this property you can choose whether the result of the debug stream is appended to the existing content of the DebugInfoStreamURI or the resource starts with debug infos of the next run. |
false, so a new resource is created to every run of a pipeline. |
| DebugInfoStreamURI | With this property you can control, whether debug infos of a running pipeline are generated and where they are written. Like with CompilerInfoStreamURI the value null means no debug infos, System.out and System.err uses the respective system stream and any other value is interpreted as uri for the resource to write the debug infos to. Also like CompilerInfoStream a relative uri is made absolute by using the uri of your user home folder. |
null, so no debug compiler infos are generated. |
| DataWrapper | A DataWrapper is used while executing p:data to produce an xml document out of non xml data. To invoke a wrapper, you can associate either a mime type or an extension (in the file name) with a specified Java class, which does the wrapping. A DataWrapper element must either have an attribute named "mime" or "extension" (not both!) declaring the mime or file name extension, to which the wrapper should be applied. The name of the Java class to do the wrapping must be given in the attribute "value". Like with all extensions, MorganaXProc will look in all Jar-files in the folder "Extensions" next to MorganaXProc.jar. See MorganaXProc's api guide for a discussion of this enhancement feature.To unload all previously loaded DataWrappers for any mime type, use "null" as value for attributes "mime" and "value". The unload all previously loaded for any extension, use "null" as value for attributes "extension" and "value". To unload all previously loaded DataWrappers (for any extension and for any mime type) leave out attributes "mime" and "extension" and use "null" for attribute "value". All DataWrappers in a configuration file will be respected, so this configuration property is an exception to the general rule, that only the first appearance of a specific property matters. |
No DataWrappers are loaded by default. |
| DocumentBaseURI | This property gives you a handy way to avoid long uris when loading documents or data inside a pipeline. Whenever MorganaXProc encounters a relative uri in p:document or p:data, it first tries to make the uri absolute by using DocumentBaseURI. So if DocumentBaseURI is set to any other value than null, MorganaXProc will use this uri as the base for resolving relative uris. If it is null the uri of the p:document or p:data element is used.This mechanism is also used when binding external documents to input ports of a called pipeline either with the command line interface or from a Java application. If DocumentBaseURI is set, relative uris are resolved by using it. If it is null, the command line interface will use the current working directory to make it absolute. In your Java application the uri of the called pipeline is used. |
null, so uris in pipeline call, p:document and p:data either have to be absolute or are made absolute by using uris retrieved from the pipeline. |
| ExtensionLibrary | The property ExtensionLibrary allows you to load additional XPath functions and XProc steps written in Java into the compilation and runtime environment. ExtensionLibrary will need an attribute named "value" which indicates the java package name to load. See MorganaXProc's - API guide for a detailed description of this feature.To load more than one extension library just add an element for each library. To unload all ExtensionLibraries loaded by this or any previous configuration level, use "null" or "" in attribute "value". |
No extension libraries are loaded in default configuration. |
| FileSystem | The property FileSystem let you choose the filesystem used to do input/output when running pipelines with MorganaXProc by giving the classname in attribute "value". Because you always need a filesystem, you cannot set this property to null. Setting FileSystem to null is ignored, so the existing filesystem keeps on working. |
By default MorganaXProc uses DefaultFilesystem orAlternateFilesystem depending on whether you have or you have notApache™'s httpcomponents-client on your classpath. |
| FOConnector | The property FOConnector specifies which implementation of FOConnector to use in MorganaXProc's implementation of p:xsl-formatter. The attribute value must be the fully qualified Java class name of the implementing class. The named class must be provided in a JAR-file places into folder "Extensions" in the same folder, which contains MorganaXProc. For your convenience MorganaXProc knowns the following shortcuts:
This feature was introduced with |
By default MorganaXProc uses the FOConnector for Apache's FOP 2.2. Please note, that Apache's FOP is not provided with MorganaXProc's standard distribution. You have to install this software yourself if you want to use it. Please see documentation for details. |
| HTMLParserClass |
Controls the parser used, if in |
By default this value is "null", so trying to use |
| LogFileName |
Controls the filename for the output of |
By default "PortLogger.xml" is used. |
| LogPathURI |
Controls the path to where outputs of |
By default the value of Java's property "user.home" (your user home foldder) is taken, so the exact pass depends on your Java settings and on the operation system in use. |
| LogStyle |
Controls the style, in which the outputs of |
By default LogStyle is set to "OFF", so no log information will be written. |
| PipelineFolderURI |
This uri is used, if you try to compile a pipeline with a relative uri. Note that this is only true for the outmost pipeline directly delivered to MorganaXProc via command line interface or API. The uri for any pipeline or library that is imported into another pipeline is made absolute by using the uri of the importing pipeline. |
null, so you must give absolute uris for the pipelines you want to run. |
| PortDumperURI |
By giving an uri for |
null, so no dump information for any output port is written. |
| PKGRepository |
Since version 0.95-4 MorganaXProc supports the Packaging System proposed by EXPath.org. By giving an uri for |
NONE, so by default no package repository is used. |
| SecurityControl |
With this property you can add another rule to the existing security manager. With the "operation" attribute you define, for which operation the rule should be applied, with the "path" attribute you have to define for which path (or path fragment) the rule should be applied. For the uri given with the "path" attribute you can either give a full uri to which the rule should apply or an uri fragment, which means, that the rule applies to all uris starting with this fragment. The third necessary attribute of |
See documentation of SecurityManager for MorganaXProc's default security settings. |
| SecurityManager |
MorganaXProc's Security Manager is a security wall against potential threats for your system by running pipelines from third parties or during development and testing new pipelines. It allows you to control, whether a pipeline does have access to ressources on your system at all, which ressources can be accessed and which can not, which ressources on the internet can be accessed and which system commands a pipeline is allowed to run. For a detailed description of the security management in MorganaXProc see the documentation of this feature. |
By default, MorganaXProc uses an "authoritarian security manager", which allows running and importing pipelines from any uri with scheme 'file' and reading documents from the path set by Java's property "user.home". All other operations for paths starting with "file://" are forbidden. Additionally all http-operation are forbidden except http method "get", which is allowed for all uris. |
| StrictExternalBinding |
This property controls the mechanism used to bind ports and options to the outmost pipeline. If you set |
true, so you cannot bind undeclared ports or set undeclared options. |
| XMLCatalogFiles |
Since MorganaXProc 0.95-10 OASIS XML Catalogs are supported. For an introduction see XML Entity and URI Resolvers. This properties controls which catalogs are used to resolve resources. For each catalog file an absolute uri is required. To use more than one catalog file, catalog uris have to be separated by ";". |
By default MorganaXProc does not use any catalog to resolve resources. |
| XQueryConnector |
With this property you can control, which XQuery processor is used when MorganaXProc encounters a |
By default MorganaXProc uses the built in XQuery processor. |
| XSLTConnector |
This property is used to select the XSLT processor used in |
By default MorganaXProc uses the XSLT processor that is standard to the Java environment you use. (Technically: It uses the processor that TransformerFactory.newInstance() will return. |
Tired of reading the long list? Sorry, but we have to talk about one more point.
How to use configurations in the command line interface?
As we said earlier, the second level of configuration for MorganaXProc is done by reading a document from a file called "xproc-config.xml". Then we have learned that there are more levels which can be used in the command line interface. How to do this?
If you recall our discussion of the command line interface, almost all relevant things are done by using an element. Configuration is no exception, so we will use the "-config:" element to make the command line interface use a special configuration. After the element we have to give the uri of the file with the config document. If the uri is relative, the command line interface makes it absolute by using the uri of the current working directory.
The "-config:" elements in the command line are processed from left to right, so you can tell the command line interface to read as many configuration files as you like. This gives you level 3 and higher in the configuration of MorganaXProc.
Additionally you can set individual properties directly in the command line interface. To separate those properties from the other elements of the command line call, we will use prefix "-mox:" for before any property name. To separate the value from the name, a "=" is required. Example: If you want to change the log-style, add "-mox:LogStyle=PLAIN" (without the quotes) to your call of MorganaXProc from the command line.
There are two exceptions to this general rule:
- To select a DataWrapper, you have to select first the mime type or the file extension to which the wrapper should apply and then add a '|' followed by the wrapper's class name. Example: "-mox:DataWrapper=mime:text/csv|java-class-name" or "-mox:DataWrapper=extension:csv|java-class-name".
- The second exception to the general configuration notation are settings for SecurityControl: Here you have to use the following syntax: -mox:SecurityControl=operation|path|allowance.
Please see file 'runMorganaTests.sh' in your MorganaXProc distribution folder for a detailed example on how to set configuration properties from the command line.