com.goldencode.p2j.cfg (P2J - Progress 4GL to Java Conversion and Runtime)

Class Summary
Class	Description
BootstrapConfig	Collection of convenient methods to read, encrypt, decrypt and parse bootstrap configuration XML files.
Configuration	Master configuration object which loads subsystem configurations.
Parameter	A simple parameter object with `name` and `value` properties and a bean-like interface to access them.

Exception Summary
Exception Description

ConfigurationException
This exception should be thrown to indicate an error during application configuration.

Exception Summary
Exception	Description
ConfigurationException	This exception should be thrown to indicate an error during application configuration.

Package com.goldencode.p2j.cfg Description

Provides a way of finding pieces of initial (bootstrap) configuration.

Author	Nick Saxon, Greg Shah
Date	May 15, 2014
Access Control	CONFIDENTIAL

Introduction
Bootstrap Configuration
Definitions
XML file structure

Client XML
Server XML

References
API
Encryption

Introduction

This package provides means of reading application configuration data from a persistent storage like XML files.

Bootstrap Configuration

The bootstrap configuration is a collection of data items needed for both client and server sides of the P2J applications in order to start up and be able to make connections.

Portions of the bootstrap configuration of the client may be shared amongst multiple users. Thus, the client side bootstrap configuration may be specified as one or two XML files, whereas the server side is always one XML file. Two XML files are considered a single logical XML file for the purpose of this description.

Definitions

Regardless of the side, the bootstrap information is organized as a three level tree: category, group, key. Categories do not have attributes. Groups have attributes. Attribute names are the keys. Queried values are strings.

XML file structure

The root element of a XML bootstrap configuration file is always a

<node
      type="type">

element, where type is either server or client. The type of the node should match the type of the object being constructed based on this XML file. Categories and groups are nested XML elements. Keys are attributes that may be queried. They always return strings, so the interpretation of the values is beyond the responsibilities of this package.

In case of two configuration files, both have to be of type client. The logical structure of the union is simply a set of categories from both files.

Same category may be coded multiple times. Same group may be coded multiple times within the category, too. Normally, this is used to code different keys. If a key is coded more than once, the first occurrence is used. Besides that, the order of categories, groups and keys does not matter. Any number of attributes can be coded with elements.

The general structure of the XML file is discussed below.

In the samples below all attributes are coded separately, This is not a requirement. They can be grouped. Values are typed in italics.

Client XML

`<?xml version="1.0"?>`
`<node type="client">`	client bootstrap configuration file
`<net>`	"net" category begins
`<server host="hostname"/>`	"server" group, "host" key	these two items define the server's TCP/IP host name or IP address and port number
`<server port="port"/>`	"server" group, "port" key
`<dispatcher threads="threads"/>`	"dispatcher" group, "threads" key	number of dispatcher's threads
`</net>`	"net" package category ends
`<security>`	"security" category begins
`<truststore filename="file"/>`	"truststore" group, "filename" key	where X.509 certificates of the known servers and the Certification Authorities are stored and the server's alias
`<truststore alias="alias"/>`	"truststore" group, "alias" key
`<keystore filename="keystore"/>`	"keystore" group, "filename" key	where this client or application's X.509 certificates and private keys are stored
`<keystore processalias="alias"/>`	"keystore" group, "processalias" key, optional	if present, specifies the process authentication mode and the process alias pointing to a X.509 certificate to use
`<keystore useralias="alias"/>`	"keystore" group, "useralias" key, optional	may be coded here to provide input for `AuthUIHelper`
`</security>`	"security" category ends
`</node>`	end of client bootstrap configuration file

Server XML

`<?xml version="1.0"?>`
`<node type="server">`	server bootstrap configuration file
`<net>`	"net" category begins
`<server port="port"/>`	"server" group, "port" key	TCP/IP port this server listens on
`<server nodeaddress="address/>`	"server" group, "nodeaddress" key	P2J node address of this server
`<dispatcher threads="threads"/>`	"dispatcher" group, "threads" key	number of dispatcher threads
`<router threads="threads"/>`	"router" group, "threads" key	number of router threads
`</net>`	"net" package category ends
`<security>`	"security" category begins
`<server id="ident"/>`	"server" group, "id" key	server id matching an object under /security/accounts/processes
`<keystore filename="keystore"/>`	"keystore" group, "filename" key	this server's X.509 certificates, private keys and alias
`<keystore alias="alias"/>`	"keystore" group, "alias" key	this server's X.509 certificates, private keys and alias
`</security>`	"security" category ends
`<directory>`	"directory" category begins
`<backend class="class"/>`	"backend" group, "class" key	class name of a back end implementation
`<backend type="type"/>`	"backend" group, "type" key	back end type as a string "xml" or "ldap"; conditional groups should match the type
`<xml filename="file"/>`	conditional "xml" group, "filename" key	names the directory XML file
`<ldap url="url"/>`	conditional "ldap" group, "url" key	Defines full LDAP server URL and initial context, like this "ldap://localhost:389/dc=goldencode,dc=com". For the ordinary connection URL should have protocol "ldap". For TLS connection protocol should be set to "ldaps".
`<ldap mode="file"/>`	conditional "ldap" group, "mode" key	These two variables define the source of the mapping data for use by LDAP back-end. Depending on the value of mode variable, mapping may contain different values. If mapping mode is set to "file" then mapping specifies a file name where P2J to LDAP mapping is stored. If mapping mode is set to "subtree", mapping should contain two parts separated with '/'. First part defines LDAP distinguished name of the node where mapping is stored. Second part defines name of the attribute which holds mapping data.
`<ldap mapping="file"/>` `<ldap mapping="location/attribute"/>`	conditional "ldap" group, "filename" key
`<ldap principal="name"/>`	conditional "ldap" group, "principal" key	Distinctive Name (DN) to be used for LDAP authentication
`<ldap credentials="text"/>`	conditional "ldap" group, "credentials" key	Credentials (like password) used in LDAP authentication.
`<ldap auth="auth"/>`	conditional "ldap" group, "auth" key	Authorization mode for LDAP bind operation. Recognized values are "simple" and "EXTERNAL".
`<ldap keystore="file"/>`	conditional "ldap" group, "keystore" key	Keystore filename that contain certificate to be used for LDAP connection.
`<ldap alias="alias"/>`	conditional "ldap" group, "alias" key	Alias of the certificate which will be selected from ones present in keystore.
`<ldap truststore="file"/>`	conditional "ldap" group, "truststore" key	Truststore that contain private keys to be used for LDAP connection.
`<ldap keypasswd="password"/>`	conditional "ldap" group, "keypasswds" key	Password which will be used to decrypt keystore.
`<ldap aliaspasswd="password"/>`	conditional "ldap" group, "aliaspasswd" key	Password which will be used to decrypt certificate.
`<ldap trustpasswd="password"/>`	conditional "ldap" group, "trustpasswd" key	Password which will be used to decrypt truststore.
`</directory>`	"directory" category ends
`</node>`	end of server bootstrap configuration file

References

Values of the configuration items looking like "#word1.word2.word3" are interpreted as pointers to another items, or references. When such a value is queried, the class tries to resolve the reference and look for another item with category=word1, group=word2 and key=word3. If such an item can be found in the file, its value is returned instead.

References may point to references, but to avoid endless loops, the class limits the number of lookups to 3. The result of the last lookup is returned whether it is resolved or not. Broken references are returned as empty strings.

API

Accessing the bootstrap configuration does not need a complicated API. The following public methods are provided:

public String[] listCategories() - returns an array of all categories found in the configuration
public String[] listGroups(String category) - returns an array of all groups found in the category
public String[] listKeys(String category, String group) - returns an array of all keys found in the group
public String getConfigItem(String category, String group, String key) - gets the value for a key, resolving references
public boolean isClient() - returns true if this is a client configuration , otherwise false
public boolean isServer() - returns true if this is a server configuration , otherwise false

Names, returned with enumeration calls are always in uppercase. getConfigItem method uses case-insensitive search for all levels, so the returned names can be directly used for retrieving key values.

Encryption

Bootstrap configuration files are kept in the file system in an encrypted form for higher security. The encryption method used is "PBEWithMD5AndDES".

Package com.goldencode.p2j.cfg