org.openeai.config
Class AppConfig

java.lang.Object
  org.openeai.OpenEaiObject
      org.openeai.config.EnterpriseConfigurationObjectImpl
          org.openeai.config.AppConfig

All Implemented Interfaces:

EnterpriseConfigurationObject

public class AppConfig
extends EnterpriseConfigurationObjectImpl
implements EnterpriseConfigurationObject

The AppConfig class acts as a container for all pre-configured object that an application may use. It reads an application's config XML document, instantiates the objects contained in that document and configures them according to the information found in the document. Then, those objects are available to the application via the getObject, getObjectByType or getObjectsLike methods.

The config document can be stored in several different places which include: file system, web server or directory server. Typically, an application instantiates app config using a properties file that contains all the properties AppConfig needs to find the configuration document and configure the application listed in the properties file.

Currently, an AppConfig is associated to these distinct types of applications:

• A runnable class like MessageConsumerClient or GenericAppRunner
• A Servlet
• A ScheduledCommand implementation
• A Command implementation

Configuration Parameters:

These are the configuration parameters that may exist in an application's property file.

Name	Required	Description
instanceName	no, unless a gateway is being started	For gateways, this property is used by PubSubConsumers to establish their durable subscriptions. This should be reflective of where the gateway is physically running (machine name etc.)
providerUrl	yes	Indicates where the config doc is located. If the protocol specified is "ldaps" AppConfig will use SSL to connect to the directory server. It does this by using JSSE. Other protocols that can be specified include http:, https: and file:. A local file system path can also be specified like "/usr/configs/ConfigDoc.xml" or "c:/user/configs/ConfigDoc.xml".
initialContextFactory	no, unless the providerUrl is ldap/ldaps	The initialContextFactory property indicates how AppConfig is to connect to the store (only applies to directory server connection)
securityPrincipal	no, unless the providerUrl is ldap/ldaps	The securityPrincipal and securityCredentials are directory server credentials used to connect to the providerUrl in the directory server. This is only related to configuration documents stored in a directory server.
securityCredentials	no, unless the providerUrl is ldap/ldaps	The securityPrincipal and securityCredentials are directory server credentials used to connect to the providerUrl in the directory server. This is only related to configuration documents stored in a directory server.
configDocName	no, unless the providerUrl is ldap/ldaps	name of the object as it's stored in the directory server.
messageComponentName	yes	the application/gateway etc. being configured specifically, as it's named in the config doc.

Example properties file:

• instanceName=SomeGateway-1
• providerUrl=ldaps://ldap.some.company.com:636/ou=Development,ou=Configurations,ou=Messaging,dc=uillinois,dc=edu
• initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
• securityPrincipal=uid=Gateway1,ou=Users,ou=Messaging,dc=uillinois,dc=edu
• securityCredentials=secretpw
• configDocName=configxmlname=SampleGateway
• messageComponentName=SampleGateway

Directory Server Example:

• providerUrl=ldaps://ldap.some.company.com:636/ou=Development,ou=Configurations,ou=Messaging,dc=uillinois,dc=edu
• providerUrl=ldap://ldap.some.company.com:389/ou=Development,ou=Configurations,ou=Messaging,dc=uillinois,dc=edu

Web Server Example:

• providerUrl=http://www.aits.uillinois.edu/config/xml/SomeApp.xml
• providerUrl=https://www.aits.uillinois.edu/config/xml/SomeApp.xml

File system Example:

• providerUrl=/usr/config/xml/SomeApp.xml
• providerUrl=c:/usr/config/xml/SomeApp.xml
• providerUrl=file://localhost/usr/config/xml/SomeApp.xml

Version:

3.0 - 28 January 2003

Author:

Tod Jackson (tod@openeai.org), Steve Wheat (steve@openeai.org)

Field Summary

Fields inherited from class org.openeai.OpenEaiObject

logger

Constructor Summary

AppConfig()
Constructor

AppConfig(org.jdom.Element configElement)
This constructor might be used if an application has already parsed the deployment document and found the configuration Element associated to the application.

AppConfig(java.util.Properties props)
This is the most commonly used constructor.

AppConfig(java.lang.String docUri, java.lang.String appName)
This constructor might be used if an application knows URI of the document that is to be used to configure the application.

Method Summary

java.lang.String	dumpStats() Returns name and class information about all objects currently stored in this AppConfig object.
java.lang.String	getDocUri() Returns the config document URI that is used to locate the XML config document for this application.
AppConfig	getMainAppConfig() Returns the main appConfig (in other words, the top-level AppConfig).
java.lang.Object	getObject(java.lang.String name) Returns the object stored in this AppConfig object with the name passed in.
java.lang.Object	getObjectByType(java.lang.String className) Returns the first object stored in this AppConfig that is a class of object matching the the class name passed in.
java.util.Hashtable	getObjects()
java.util.List	getObjectsLike(java.lang.String pattern) Returns a List of objects currently stored in this AppConfig object with names that contain the pattern passed in.
java.util.Properties	getProperties(java.lang.String name) Convenience method that returns a Properties object associated to a PropertyConfig object.
java.lang.String	getProviderUrl() Returns the providerUrl instance variable associated with this Application.
void	init(org.jdom.Element eConfig) This is the "workhorse" initialization method for an AppConfig object.
void	initializeFromFile(java.lang.String docUri, java.lang.String appName) Loads the configuration document from a URI (file or webserver etc.).
boolean	isInitialized() Returns an indication that specifies if this AppConfig object has been initialized yet.
void	reInitialize() Re-initializes this AppConfig object.
void	setDocUri(java.lang.String docUri) Sets the config document URI that is used to locate the XML config document for this application.
void	setProviderUrl(java.lang.String url) Sets the providerUrl instance variable associated with this Application.
void	shutdown() Recursively shuts down all objects contained within this AppConfig.

Methods inherited from class org.openeai.config.EnterpriseConfigurationObjectImpl

addProperty, getAppName, getConfigDoc, getConfigElementByAttributeValue, getElementByAttributeValue, getName, getType, getValidation, refresh, setAppName, setConfigDoc, setName, setRefresh, setType, setValidation

Methods inherited from class org.openeai.OpenEaiObject

getDebug, getFromAddr, getMailHost, getMailService, getProperties, getToAddr, initializeLog4j, initializeLog4j, initializeLog4j, setDebug, setFromAddr, setMailHost, setMailService, setProperties, setToAddr

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.openeai.config.EnterpriseConfigurationObject

getAppName, getProperties, refresh, setAppName

Constructor Detail

AppConfig

public AppConfig()

Constructor

AppConfig

public AppConfig(java.lang.String docUri,
                 java.lang.String appName)
          throws EnterpriseConfigurationObjectException

This constructor might be used if an application knows URI of the document that is to be used to configure the application. Note, this can only be a web address or a file URI. This is generally not needed but is provided as a potential convenience method.

Throws:

EnterpriseConfigurationObjectException - if any errors occur while initializing the component.

AppConfig

public AppConfig(java.util.Properties props)
          throws EnterpriseConfigurationObjectException

This is the most commonly used constructor. Most applications, gateways, servlets etc. will simply read a properties file on the file system which contains information regarding where to find the configuration document and what component to configure. See Class description for more details on the Properties file used.

Throws:

EnterpriseConfigurationObjectException - if any errors occur while initializing the component.

AppConfig

public AppConfig(org.jdom.Element configElement)
          throws EnterpriseConfigurationObjectException

This constructor might be used if an application has already parsed the deployment document and found the configuration Element associated to the application. This is generally not needed but is provided as a potential convenience method.

Throws:

EnterpriseConfigurationObjectException - if any errors occur while initializing the component.

Method Detail

setProviderUrl

public final void setProviderUrl(java.lang.String url)

Sets the providerUrl instance variable associated with this Application. This is the location in the directory server, file system or web server where the deployment document resides. i.e. - this is where the AppConfig object should "look" for the deployment document.

Parameters:

url - String the providerUrl.

getProviderUrl

public final java.lang.String getProviderUrl()

Returns the providerUrl instance variable associated with this Application. This is the location in the directory server, file system or web server where the deployment document resides. i.e. - this is where the AppConfig object should "look" for the deployment document.

Returns:

String the providerUrl.

getMainAppConfig

public AppConfig getMainAppConfig()

Returns the main appConfig (in other words, the top-level AppConfig). This allows access to shared resources, such as database pools, from individual commands instantiated through the main or top-level AppConfig.

isInitialized

public final boolean isInitialized()

Returns an indication that specifies if this AppConfig object has been initialized yet.

Returns:

boolean

getDocUri

public final java.lang.String getDocUri()

Returns the config document URI that is used to locate the XML config document for this application.

Returns:

String

setDocUri

public final void setDocUri(java.lang.String docUri)

Sets the config document URI that is used to locate the XML config document for this application.

Parameters:

docUri - String

reInitialize

public final void reInitialize()
                        throws EnterpriseConfigurationObjectException

Re-initializes this AppConfig object. This method stops any running component that it's managing, re-reads the deployment document and re-initializes/re-starts all objects for this application that's listed in the deployment document.

Throws:

EnterpriseConfigurationObjectException

initializeFromFile

public void initializeFromFile(java.lang.String docUri,
                               java.lang.String appName)
                        throws EnterpriseConfigurationObjectException

Loads the configuration document from a URI (file or webserver etc.).

Parameters:

docUri - String file URI to the document (http:, file: etc.)

appName - String appName the name of the messaging component in the configuration document that the AppConfig object should be lookning for.

Throws:

EnterpriseConfigurationObjectException

getObjects

public java.util.Hashtable getObjects()

getObjectByType

public final java.lang.Object getObjectByType(java.lang.String className)
                                       throws EnterpriseConfigurationObjectException

Returns the first object stored in this AppConfig that is a class of object matching the the class name passed in.

If the object has been configured with the 'refresh' attribute set to 'true' the object will be refreshed based on the current contents of the config document before it's returned. Currently, this only works for PropertyConfig objects so properties associated to an application like a Servlet, ScheduledApp or Gateway can be refreshed dynamically without restarting the app. This will only work if the application actually retrieves the Properties object from AppConfig when the business logic is executed as opposed to retrieving those properties when the command or servlet is first instantiated.

Note, XmlEnterpriseObjects stored in an AppConfig will be cloned and the clone will be returned. For all other types of objects stored in an AppConfig, a reference to that object will be returned.

Parameters:

className - String the class name of the object being retrieved.

Returns:

Object

Throws:

EnterpriseConfigurationObjectException - if no objects of type passed in exist.

See Also:

getObject(java.lang.String)

getObjectsLike

public final java.util.List getObjectsLike(java.lang.String pattern)
                                    throws EnterpriseConfigurationObjectException

Returns a List of objects currently stored in this AppConfig object with names that contain the pattern passed in.

Parameters:

pattern - String the "pattern" name of the object(s) being retrieved.

Returns:

List of objects who's names contain the pattern passed in (empty list if none exist).

Throws:

EnterpriseConfigurationObjectException - if no objects exist with names containing the pattern passed in.

See Also:

getObject(java.lang.String)

getProperties

public final java.util.Properties getProperties(java.lang.String name)
                                         throws EnterpriseConfigurationObjectException

Convenience method that returns a Properties object associated to a PropertyConfig object. This allows developers to retrieve named properties from an AppConfig without having to go through the extra step of retrieving a PropertyConfig object and then calling the 'getProperties' method on that object. It can still be done that way but this method just provides a mechanism for doing with fewer lines of code.

Parameters:

name - String the name of the PropertyConfig object being retrieved as it's named in the Deployment document.

Returns:

Properties object associated to the PropertyConfig object who's name matches the name passed in.

Throws:

EnterpriseConfigurationException - if no object exists with a name passed in or if the object named 'name' is not a PropertyConfig object.

EnterpriseConfigurationObjectException

See Also:

getObject(java.lang.String)

getObject

public final java.lang.Object getObject(java.lang.String name)
                                 throws EnterpriseConfigurationObjectException

Returns the object stored in this AppConfig object with the name passed in. The name of the objects are specified in the XML Configuration documents and are the names by which AppConfig stores objects as it configures itself.

If the object has been configured with the 'refresh' attribute set to 'true' the object will be refreshed based on the current contents of the config document before it's returned. Currently, this only works for PropertyConfig objects so properties associated to an application like a Servlet, ScheduledApp or Gateway can be refreshed dynamically without restarting the app. This will only work if the application actually retrieves the Properties object from AppConfig when the business logic is executed as opposed to retrieving those properties when the command or servlet is first instantiated.

Note, XmlEnterpriseObjects stored in an AppConfig will be cloned and the clone will be returned. For all other types of objects stored in an AppConfig, a reference to that object will be returned.

Parameters:

name - String the name of the object being retrieved.

Returns:

Object who's name matches the name passed in.

Throws:

EnterpriseConfigurationException - if no object exists with a name passed in.

EnterpriseConfigurationObjectException

See Also:

getObjectByType(java.lang.String), getObjectsLike(java.lang.String)

init

public void init(org.jdom.Element eConfig)
          throws EnterpriseConfigurationObjectException

This is the "workhorse" initialization method for an AppConfig object. This method is called once the "Configuration" element for an application, gateway etc. has been retrieved from their config document. The configuration element passed in is used to determine which objects to instantiate and initialize with the information found in the Configuration element.

This method loops through all the child elements within the Configuration element passed in and instantiates configuration Java objects with those individual config elements. Then, it passes those Java objects to the appropriate Java object's constructor. These Java objects that are instantiated with the configuration objects, are then available to applications via the getObject, getObjectsLike and getObjectByType methods.

For example, an XML aware ProducerConfig object is instantiated/initialized with the ProducerConfig XML element. This object is then used to construct either a PointToPointProducer or a PubSubProducer foundation component depending on the information contained in the ProducerConfig object/element. Finally, the Producer that's instantiated is stored within the AppConfig object and can be retrieved during application execution by the application developer. This way, the Producer is instantiated, configured and potentially started (ready for producing messages) all based on information contained in the configuration document. All the application developer has to do is enter the appropriate configuration information into the config document and start his application. When the application is started, an AppConfig object is built and the appropriate Producers are added to it for use by the application being developed.

Specified by:

init in interface EnterpriseConfigurationObject

Overrides:

init in class EnterpriseConfigurationObjectImpl

Parameters:

eConfig - Element the Configuration Element for the application, gateway, servlet etc. being configured.

Throws:

EnterpriseConfigurationObjectException - if any errors occur while initializing the component.

dumpStats

public java.lang.String dumpStats()

Returns name and class information about all objects currently stored in this AppConfig object. Line feed included. Debug use only...

Returns:

String

shutdown

public void shutdown()
              throws EnterpriseConfigurationObjectException

Recursively shuts down all objects contained within this AppConfig. This includes things like MessageProducers, MessageConsumers and Database Connection pools that may have open connections to external sources like Brokers and Databases.

Throws:

EnterpriseConfigurationObjectException