Configuration files and how they work

All configurations, both client and server work the same. This article documents their commonalities. Features are:

• XML-based
• Multiple named configurations supported in a given file
• Multiple types of storage may be specified
• Aliases for configurations are allowed.
• Other configuration files may be included (as of OA4MP 1.1)

Comment: ALL tag names are case sensitive in the configuration file -- as per the XML spec, so "fileStore" works, but "filestore" would not, for instance.

Parameters or, how the system finds its files

There are two things that determine which configuration to use, the file in which it resides and the name of the configuration in that file. These will henceforth be referred to as the file parameter and name parameter. To specify parameters you have two options:

1. Specify them as context parameters in the web.xml file for Tomcat.
2. Specify them as command line arguments to the JVM (prepend "-D"). This is much less common.

Tip: It is a very good idea to put your context parameters in the server web.xml (should be located at $CATALINA_HOME/conf/web.xml.) This will allow you to swap out/upgrade versions of OA4MP without having to touch any configuration -- just drop a new version of the war into the right place and restart the server to get an upgrade.

Clients and servers as well as different versions of OA4MP have different parameters. The specific of those will be documented elsewhere. However, here is the definitive list for reference

Component	Parameter	OAuth 1.0a	OAuth 2.0
client	file	oa4mp:client.config.file	oa4mp:oauth2.client.config.file
	name	oa4mp:client.config.name	oa4mp:oauth2.client.config.name
server	file	oa4mp:server.config.file	oa4mp:oauth2.server.config.file
	name	oa4mp:server.config.name	oa4mp:oauth2.server.config.name

A server example for OAuth 1.0a

This how the the file and name parameters would be specified in the web.xml file:

<context-param>
    <param-name>oa4mp:server.config.file</param-name>
    <param-value>/path/to/cfg.xml</param-value>
</context-param>

<context-param>
    <param-name>oa4mp:server.config.name</param-name>
    <param-value>default</param-value>
</context-param>

in this case the server configuration file at /path/to/cfg.xml would be loaded, searched and the configuration named "default" would be loaded. For a given version and component, use the appropriate parameter from the table above.

Aliases

An alias is a reference to another named configuration. They are completely analogous to file links in unix. Only resolves an alias if it is specifically used. It will also throw an exception if a cycle is detected. By that we mean a chain of aliases that resolves to itself. So if A refers to B as an alias, and B refers to A, then an exception will occur and no configuration will be loaded.

A client example using aliases

in this example, the name parameter is "default". Inside the configuration file though, there are a couple of configurations possible. For instance a production instance and one for debugging. All you would need to switch your entire installation is to change what the alias points to here (rather than messing around in Tomcat) and restarting the server.

<config>
    <client name="default" alias="postgres-cfg"/>
    <client name="postgres-cfg">
        <!-- lots of stuff -->
    </client>
    <client name="debug-cfg">
        <!-- lots of other stuff -->
    </client>
</config>

Included files.

As of OA4MP 1.1, configuration files may now be included in other configuration files. Note that

• the other files must be completely correct syntactically. So no snippets.
• there is no limit on the number of files that may be included and referenced files can reference other files.
• all files are ingested first into what is essentially one large configuration internally. Hierarchies of configurations will not be understood. What distinguishes configurations is their name. If two configurations with the same name are encountered, the result will be unpredictable.
• aliases are resolved after loading. This allows you to keep you aliases in any included file and they will be resolved.
• referenced files are loaded exactly once. So if file A refers to file B which refers to A, Both A and B will load but no recursion will take place. An informational message will be written to the logs if this happens. This is not considered a fatal condition.

A client example of using files.

Reworking the above alias example, this is completely equivalent to

<config>
     <file include="/path/to/file.xml"/>
     <client name="default" alias="postgres-cfg"/>
</config>

and the next file, which is /path/to/file.xml in toto is

<config>
    <client name="postgres-cfg">
        <!-- lots of stuff -->
    </client>
    <client name="debug-cfg">
        <!-- lots of other stuff -->
    </client>
</config>

Refer to the first file in your deployment. The second will be loaded for you automatically.