Understanding Options In Configuration

This document deals with MorganaXProc's configuration process and the settings you can make to influence the process of compiling and running XProc pipelines.
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:config xmlns:mox="http:www.xml-project.com/morgana">

<mox:PropertyName value="PropertyValue" />
<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 or
AlternateFilesystem depending on whether you have or you have not
Apache™'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:

  • "FOP11Connector" for "..fopsupport.FOP11Connector"
  • "FOP22Connector" for "..fopsupport.FOP22Connector"

This feature was introduced with MorganaXProc 1-0-11, so you will need this or a later version to use it.

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 p:unescape-markup the attribute content-type is "text/html". The value may be "null" , so no parser is used or must be the Java class name of an XMLReader. Like with all extensions, MorganaXProc will look in all Jar-files in the folder "Extensions" next to "MorganaXProc.jar".

By default this value is "null", so trying to use p:unescape markup with content-type="text/html" will fail with XC0051.

LogFileName

Controls the filename for the output of p:log. Note that here just a file name is required. The path is set by LogPathURI.

By default "PortLogger.xml" is used.

LogPathURI

Controls the path to where outputs of p:log are written. This property is used to make relative paths in p:log absolute and also as base, if no href attribute is found in p:log. In the latter case it is combined with the property LogFileName to determine the full filename.
Please mind that any setting for LogPathURI and LogFileName must also be allowed by a setting for SecurityControl, because writing uncontrolled log outputs could be a possible threat to your system.

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 p:log are written. Currently three styles are implemented: "OFF", "PLAIN" and "WRAPPED".

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.
Please keep in mind, that in MorganaXProcs command line interface relative uri for pipelines are made absolute against the value of your current working directory, if PipelineFolderURI is null.

null, so you must give absolute uris for the pipelines you want to run.
PortDumperURI

By giving an uri for PortDumperURI you can switch on MorganaXProc's port dumping feature and control, where the output for port dumping is written. The port dumping feature is a debugging tool which writes the content of all visible ports (= all ports of the outmost pipeline and all output ports of embedded steps) to a file.

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 PKGRepository you can tell MorganaXProc, where to look for packages. This uri must point to a folder with the layout explained in section 7 of the specification. See the documentation for more details.

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 SecurityControl is named "allowed" which controls by a boolean value, whether the operation is allowed for the given uri (fragment) or whether it is forbidden.
Please mind, that any setting will add the given security rule to the existing SecurityManager. So if you need to set a new SecurityManager in your configuration, do this first and then add the security rules for the new SecurityManager by using SecurityControl. For a detailed description of the security management in MorganaXProc see the documentation of this feature.

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.
Use attribute "value" with a java class path as value to select another implementation for the security manager or use attribute "strategy" with value "liberal" or "authoritarian". If a SecurityManager element has both attributes, only strategy is used.

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 StrictExternalBinding to "true", the attempt to bind a port or an option value to a pipeline which is not declared in the pipeline will raise an error. If it is "false" any undeclared port or option will be ignored.
As the phrase "external" should hint at, this does only apply if you call a pipeline from the command line interface or run it from your Java application. If such a pipeline itself calls a pipeline, the defined standard mechanism of XProc applies, that is, strict binding is in place.

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 p:xquery step. With "value" attribute you have to give the name of the Java class with the adapter for the desired XQuery processor. See the documentation on enhancing MorganaXProc with third party software for a detailed discussion of this feature.

By default MorganaXProc uses the built in XQuery processor.
XSLTConnector

This property is used to select the XSLT processor used in p:xslt. The "value" attribute must be the Java class name of an adapter for the XSLT processor to used. See the documentation on enhancing MorganaXProc with third party software for a detailed discussion of this feature.

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.