com.edustructures.sifworks.tools.cfg
Class AgentConfig

java.lang.Object
  com.edustructures.sifworks.tools.cfg.AgentConfig

public class AgentConfig
extends java.lang.Object

Implements an XML-based configuration file for agents.

To read the configuration file into memory, call the read method and specify whether to validate the XML document against a DTD. The methods of the AgentConfig class do not perform validation of required elements and attributes or their values, so it is recommended that you validate against a DTD. A default DTD is located in the docs directory.

Applying the Configuration Once the configuration file is parsed, you can inspect the elements and attributes by calling the various methods of this class. Or, you can call the apply method prior to agent initialization to automatically apply the configuration settings to your agent as follows:

• The root <agent> attributes are inspected to set the SourceId and default SIF Version for the agent.
• For each <property> element, the associated property is set in the agent's AgentProperties object.
• The agent's transports are configured according to the properties of the <transport> elements
• A zone is created for each <zone> element

Most agents will extend or modify this class to add additional configuration settings specific to the agent. The source code can be found in the ADK's extras directory.

Properties Agent and Zone properties can be defined at three levels:

• <property> elements of the root <agent> node are intended to serve as global defaults. When then applyProperties method is called, these property values are assigned to the Agent's AgentProperties object.
• <property> elements of a zone <template> are inherited by zones that reference that template. When the applyZones method is called, these property values are assigned to the Zone's AgentProperties object unless specifically overridden by <property> elements defined by each <zone>
• <property> elements of a <zone> are specific to that zone and override any property defined in the template referenced by the zone

Updating the Configuration Programmatically The elements and attributes of the configuration file are represented as DOM Nodes that can be programmatically updated using the standard DOM interface. Use the convenience methods getZoneNode, getZoneTemplateNode, getTransportNode, and so on to obtain a reference to a DOM Node instance for a group of configuration settings. The getProperty and setProperty methods can also be used to manipulate the <property> children of an element. Static helper routines from the com.edustructures.util.XMLUtils class may also be used to get and set element attributes and text values.

Call the save method to write the configuration to a file.

Version:

ADK 1.0

Constructor Summary

AgentConfig()
Constructor

Method Summary

org.w3c.dom.Node	addTransportNode(java.lang.String protocol) Add a <transport> node for the specified transport protocol.
org.w3c.dom.Node	addZone(java.lang.String zoneId, java.lang.String zoneUrl, java.lang.String templateId) Adds a new zone
org.w3c.dom.Node	addZoneTemplateNode(java.lang.String templateId) Add a <template> node for the specified zone template.
Zone[]	apply(Agent agent, boolean overwrite) Applies the settings in the configuration to the Agent.
void	applyProperties(Agent agent, boolean overwrite) Applies <property> elements to the Agent
void	applyTransports(Agent agent, boolean overwrite) Applies <transport> elements to the Agent.
Zone[]	applyZones(Agent agent) Applies <zone> elements to create new Zone instances.
void	deleteProperty(java.lang.String property) Deletes a property.
void	deleteZone(java.lang.String zoneId) Deletes a zone
void	deleteZoneProperty(java.lang.String zoneId, java.lang.String property) Deletes a zone property.
void	deleteZoneTemplateProperty(java.lang.String templateId, java.lang.String property) Deletes a zone template property.
void	getAgentProperties(AgentProperties props) Populates an AgentProperties object with all <property> values defined for the root <agent> element.
org.w3c.dom.Node[]	getAgentPropertyNodes() Gets all <property> values defined for the root <agent> node.
org.w3c.dom.Document	getDocument() Gets the DOM document
Mappings	getMappings() Gets the Mappings object
java.lang.String	getProperty(org.w3c.dom.Node node, java.lang.String property, java.lang.String defaultValue) Gets the value of a <property> element defined by a node.
java.lang.String	getProperty(org.w3c.dom.Node node, java.lang.String element, java.lang.String property, java.lang.String defaultValue) A convenience function to get the value of a <property> defined by the first child element of the specified node that has a matching tag name.
org.w3c.dom.Node	getPropertyNode(org.w3c.dom.Node node, java.lang.String property) Gets a <property> DOM Node
org.w3c.dom.Node[]	getPropertyNodes(org.w3c.dom.Node node) Gets all <property> child nodes of an element
org.w3c.dom.Node	getRootNode() Gets the root <agent> element
java.lang.String	getSourceId() Gets the SourceId that should be used by the agent
org.w3c.dom.Node	getTransportNode(java.lang.String protocol) Gets a <transport> node.
SIFVersion	getVersion() Gets the version of SIF that should be used by the agent
java.lang.String	getZoneAttribute(java.lang.String zoneId, java.lang.String attr, java.lang.String defaultValue) Gets the value of a <zone> node attribute.
org.w3c.dom.Node	getZoneNode(java.lang.String zoneId) Gets the <zone> element with the specified ID
org.w3c.dom.Node[]	getZoneNodes() Gets an array of all zones defined by the configuration file
void	getZoneProperties(java.util.Properties props, org.w3c.dom.Node zone) Populates a Properties object with all <property> values defined by a <zone> node as well as all properties defined by the referenced zone template.
void	getZoneProperties(java.util.Properties props, java.lang.String zone) Populates a Properties object with all <property> values defined by a <zone> node as well as all properties defined by the referenced zone template.
java.lang.String	getZoneProperty(java.lang.String zoneId, java.lang.String property, java.lang.String defaultValue) Gets the value of a <property> child of the specified <zone> node.
org.w3c.dom.Node[]	getZonePropertyNodes(org.w3c.dom.Node zone) Gets all <property> values defined for a <zone> node.
org.w3c.dom.Node[]	getZonePropertyNodes(java.lang.String zoneId) Gets all <property> values defined for a <zone> node.
org.w3c.dom.Node	getZoneTemplateNode(java.lang.String templateId) Gets a zone template by ID.
void	getZoneTemplateProperties(java.util.Properties props, org.w3c.dom.Node template) Populates a Properties object with all <property> values defined for a <template> node.
void	getZoneTemplateProperties(java.util.Properties props, java.lang.String template) Populates a Properties object with all <property> values defined for a <template> node.
java.lang.String	getZoneTemplateProperty(java.lang.String templateId, java.lang.String property, java.lang.String defValue) Gets a zone template property.
org.w3c.dom.Node	getZoneTemplatePropertyNode(java.lang.String templateId, java.lang.String property) Gets a zone template property node.
org.w3c.dom.Node[]	getZoneTemplatePropertyNodes(org.w3c.dom.Node template) Gets all <property> values defined for a <zone> node.
org.w3c.dom.Node[]	getZoneTemplatePropertyNodes(java.lang.String templateId) Gets all <property> values defined for a <zone> node.
org.w3c.dom.Node[]	getZoneTemplates(boolean filtered) Gets an array of all zones templates.
boolean	isLoaded() Determines if the configuration file has been loaded
void	populateProperties(java.util.Properties props, org.w3c.dom.Node node) Populates a Properties object with all <property> values defined as children of the specified node.
void	populateProperties(java.util.Properties props, org.w3c.dom.Node node, boolean replace) Populates a Properties object with all <property> values defined as children of the specified node.
org.w3c.dom.Document	read(java.lang.String file, boolean validate) Read a configuration file into memory.
void	save() Saves the XML document back to the file from which it was read.
void	save(java.io.BufferedWriter out) Saves the XML document to the specified Writer.
void	save(java.io.OutputStream out) Saves the XML document to the specified output stream.
void	setAgentProperty(java.lang.String property, java.lang.String value) Sets the value of a <property> child of the root <agent> node.
void	setProperty(org.w3c.dom.Node node, java.lang.String property, java.lang.String value) Sets the value of a <property> child of the specified node.
void	setProperty(org.w3c.dom.Node node, java.lang.String element, java.lang.String property, java.lang.String value)
void	setZoneAttribute(java.lang.String zoneId, java.lang.String attr, java.lang.String value) Sets the value of a <zone> node attribute.
void	setZoneProperty(java.lang.String zoneId, java.lang.String property, java.lang.String value) Sets the value of a <property> child of the specified <zone> node.
void	setZoneTemplateProperty(java.lang.String template, java.lang.String property, java.lang.String value) Sets the value of a <property> child of the specified <zone> node.

Methods inherited from class java.lang.Object

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

Constructor Detail

AgentConfig

public AgentConfig()

Constructor

Method Detail

read

public org.w3c.dom.Document read(java.lang.String file,
                                 boolean validate)
                          throws java.io.IOException,
                                 ADKConfigException,
                                 ADKMappingException,
                                 ADKException

Read a configuration file into memory.

Parameters:

file - The path to the configuration file

validate - true to validate the configuration file

Returns:

A DOM Document encapsulating the configuration file. This object may also be obtained by calling getDocument

Throws:

java.io.IOException - thrown if an error occurs reading the file

ADKException - thrown if the ADK is not initialized

ADKMappingException - thrown if an error occurs parsing any <mappings> elements

ADKConfigException - thrown if the configuration file fails to parse or is not valid when validation is turned on

See Also:

getDocument()

save

public void save()
          throws java.io.IOException,
                 ADKConfigException

Saves the XML document back to the file from which it was read.

Throws:

java.io.IOException - thrown if an error occurs writing the document

ADKConfigException

save

public void save(java.io.OutputStream out)
          throws java.io.IOException,
                 ADKConfigException

Saves the XML document to the specified output stream.

Parameters:

out - The OutputStream to which the XML document is written

Throws:

java.io.IOException - thrown if an error occurs writing the document

ADKConfigException

save

public void save(java.io.BufferedWriter out)
          throws java.io.IOException,
                 ADKConfigException

Saves the XML document to the specified Writer.

Parameters:

out - The Writer to which the XML document is written

Throws:

java.io.IOException - thrown if an error occurs writing the document

ADKConfigException

isLoaded

public boolean isLoaded()

Determines if the configuration file has been loaded

Returns:

true if the read method has been successfully called

apply

public Zone[] apply(Agent agent,
                    boolean overwrite)
             throws ADKException,
                    ADKConfigException

Applies the settings in the configuration to the Agent. This method should be called at most once during agent startup, usually from Agent.initialize

• For each <property> element, the associated property is set in the agent properties.
• A Zone instance is created for each <zone> element. Any <property> elements defined for the zone are set in the zone's AgentProperties object. An array of all zones created is returned. The caller can then join those zones to topics.

Parameters:

agent - The Agent to apply the configuration settings to

overwrite - When true, properties defined in the configuration file replace properties of the same name that are already defined in the agent properties

Throws:

ADKException

ADKConfigException

applyProperties

public void applyProperties(Agent agent,
                            boolean overwrite)
                     throws ADKException,
                            ADKConfigException

Applies <property> elements to the Agent

Parameters:

agent - The Agent to apply properties to

overwrite - When true, properties defined in the configuration file replace properties of the same name that are already defined in the agent properties

Throws:

ADKException

ADKConfigException

applyTransports

public void applyTransports(Agent agent,
                            boolean overwrite)
                     throws ADKException,
                            ADKConfigException

Applies <transport> elements to the Agent.

This method selects the <transport> child of the root <agent> with the enabled attribute set to true. Only one transport may be enabled; if more than one is enabled the last definition is considered the agent's default transport protocol. The <property> elements are then assigned to the agent's default transport properties for this protocol.

Parameters:

agent - The Agent to apply the transport properties to

overwrite - When true, properties defined in the configuration file replace properties of the same name that are already defined in the agent's default transport properties

Throws:

ADKException

ADKConfigException

applyZones

public Zone[] applyZones(Agent agent)
                  throws ADKException,
                         ADKConfigException

Applies <zone> elements to create new Zone instances. The caller is responsible for setting up topics, connecting to zones, and joining zones to topics.

Throws:

ADKException

ADKConfigException

getDocument

public org.w3c.dom.Document getDocument()

Gets the DOM document

Returns:

The loaded configuration file

addZone

public org.w3c.dom.Node addZone(java.lang.String zoneId,
                                java.lang.String zoneUrl,
                                java.lang.String templateId)
                         throws ADKConfigException

Adds a new zone

Parameters:

zoneId - The zone ID

zoneUrl - The zone URL

templateId - The ID of the zone template

Throws:

ADKConfigException

deleteZone

public void deleteZone(java.lang.String zoneId)

Deletes a zone

Parameters:

zoneId - The zone ID

getVersion

public SIFVersion getVersion()

Gets the version of SIF that should be used by the agent

Returns:

A SIFVersion object for the value of the sifVersion attribute specified by the <agent> element, or the ADK's default SIFVersion if this attribute was not set

getMappings

public Mappings getMappings()

Gets the Mappings object

Returns:

The <agent> node if defined

getRootNode

public org.w3c.dom.Node getRootNode()

Gets the root <agent> element

Returns:

The root node

getSourceId

public java.lang.String getSourceId()

Gets the SourceId that should be used by the agent

getAgentProperties

public void getAgentProperties(AgentProperties props)

Populates an AgentProperties object with all <property> values defined for the root <agent> element. Properties defined at the root level are applied to the AgentProperties object of the Agent class. These serve as global defaults to all zones. Use the getTemplateProperties method to obtain properties for a zone template, which apply to all zones that reference that template, or the getZoneProperties method to obtain properties specific to a zone.

getAgentPropertyNodes

public org.w3c.dom.Node[] getAgentPropertyNodes()

Gets all <property> values defined for the root <agent> node.

setAgentProperty

public void setAgentProperty(java.lang.String property,
                             java.lang.String value)

Sets the value of a <property> child of the root <agent> node. If a <property> element already exists, its value is updated; otherwise a new element is appended to the root <agent> node.

Parameters:

property - The name of the property

value - The property value

getZoneProperties

public void getZoneProperties(java.util.Properties props,
                              java.lang.String zone)

Populates a Properties object with all <property> values defined by a <zone> node as well as all properties defined by the referenced zone template. Properties defined by the <zone> override properties defined by the template.

getZoneProperties

public void getZoneProperties(java.util.Properties props,
                              org.w3c.dom.Node zone)

Populates a Properties object with all <property> values defined by a <zone> node as well as all properties defined by the referenced zone template. Properties defined by the <zone> override properties defined by the template.

getZonePropertyNodes

public org.w3c.dom.Node[] getZonePropertyNodes(java.lang.String zoneId)

Gets all <property> values defined for a <zone> node.

getZonePropertyNodes

public org.w3c.dom.Node[] getZonePropertyNodes(org.w3c.dom.Node zone)

Gets all <property> values defined for a <zone> node.

setZoneProperty

public void setZoneProperty(java.lang.String zoneId,
                            java.lang.String property,
                            java.lang.String value)

Sets the value of a <property> child of the specified <zone> node. If a <property> child already exists with the same name, its value is updated; otherwise a new element is appended to the <zone> node.

Parameters:

zoneId - The zone ID

property - The name of the property

value - The property value

getZoneProperty

public java.lang.String getZoneProperty(java.lang.String zoneId,
                                        java.lang.String property,
                                        java.lang.String defaultValue)

Gets the value of a <property> child of the specified <zone> node.

Parameters:

zoneId - The zone ID

property - The name of the property

defaultValue - The value that will be returned if the property is not defined

setZoneAttribute

public void setZoneAttribute(java.lang.String zoneId,
                             java.lang.String attr,
                             java.lang.String value)

Sets the value of a <zone> node attribute.

Parameters:

zone - The zone ID

attr - The name of the attribute

value - The attribute value

getZoneAttribute

public java.lang.String getZoneAttribute(java.lang.String zoneId,
                                         java.lang.String attr,
                                         java.lang.String defaultValue)

Gets the value of a <zone> node attribute.

Parameters:

zone - The zone ID

attr - The name of the attribute

defaultValue - The value that will be returned if the attribute is not defined

getZoneTemplateProperties

public void getZoneTemplateProperties(java.util.Properties props,
                                      java.lang.String template)

Populates a Properties object with all <property> values defined for a <template> node.

getZoneTemplateProperties

public void getZoneTemplateProperties(java.util.Properties props,
                                      org.w3c.dom.Node template)

Populates a Properties object with all <property> values defined for a <template> node.

getZoneTemplateProperty

public java.lang.String getZoneTemplateProperty(java.lang.String templateId,
                                                java.lang.String property,
                                                java.lang.String defValue)

Gets a zone template property.

Parameters:

templateId - The ID of the <template>

property - The name of the <property>

defValue - The default value to return if the property is not defined

getZoneTemplatePropertyNode

public org.w3c.dom.Node getZoneTemplatePropertyNode(java.lang.String templateId,
                                                    java.lang.String property)

Gets a zone template property node.

Parameters:

templateId - The ID of the <template>

property - The name of the <property>

Returns:

the DOM Node if found

getZoneTemplatePropertyNodes

public org.w3c.dom.Node[] getZoneTemplatePropertyNodes(java.lang.String templateId)

Gets all <property> values defined for a <zone> node.

getZoneTemplatePropertyNodes

public org.w3c.dom.Node[] getZoneTemplatePropertyNodes(org.w3c.dom.Node template)

Gets all <property> values defined for a <zone> node.

setZoneTemplateProperty

public void setZoneTemplateProperty(java.lang.String template,
                                    java.lang.String property,
                                    java.lang.String value)

Sets the value of a <property> child of the specified <zone> node. If a <property> child already exists with the same name, its value is updated; otherwise a new element is appended to the <template> node.

Parameters:

template - The zone template ID

property - The name of the property

value - The property value

deleteProperty

public void deleteProperty(java.lang.String property)

Deletes a property.

Parameters:

property - The name of the <property>

deleteZoneProperty

public void deleteZoneProperty(java.lang.String zoneId,
                               java.lang.String property)

Deletes a zone property.

Parameters:

zoneId - The ID of the <zone>

property - The name of the <property>

deleteZoneTemplateProperty

public void deleteZoneTemplateProperty(java.lang.String templateId,
                                       java.lang.String property)

Deletes a zone template property.

Parameters:

templateId - The ID of the <template>

property - The name of the <property>

populateProperties

public void populateProperties(java.util.Properties props,
                               org.w3c.dom.Node node)

Populates a Properties object with all <property> values defined as children of the specified node. Properties that already exist in the Properties object are not overwritten by properties defined by the node.

populateProperties

public void populateProperties(java.util.Properties props,
                               org.w3c.dom.Node node,
                               boolean replace)

Populates a Properties object with all <property> values defined as children of the specified node. Properties that already exist in the Properties object are optionally overwritten with properties defined by the node.

Parameters:

props - The Properties object to populate

node - The Node to search for child <property> elements

replace - true to replace the values of properties already defined in the props object

setProperty

public void setProperty(org.w3c.dom.Node node,
                        java.lang.String property,
                        java.lang.String value)

Sets the value of a <property> child of the specified node. If a <property> element already exists, its value is updated; otherwise a new element is appended to the node.

Parameters:

node - The parent node of the property

property - The name of the property

value - The property value

setProperty

public void setProperty(org.w3c.dom.Node node,
                        java.lang.String element,
                        java.lang.String property,
                        java.lang.String value)

getProperty

public java.lang.String getProperty(org.w3c.dom.Node node,
                                    java.lang.String property,
                                    java.lang.String defaultValue)

Gets the value of a <property> element defined by a node.

Parameters:

node - The parent node to search

property - The name of the property

defaultValue - The value to return if the property is not found

Returns:

The property value

getPropertyNode

public org.w3c.dom.Node getPropertyNode(org.w3c.dom.Node node,
                                        java.lang.String property)

Gets a <property> DOM Node

Parameters:

node - The parent node to search

property - The name of the property

Returns:

The DOM Node if the property is found, otherwise null

getProperty

public java.lang.String getProperty(org.w3c.dom.Node node,
                                    java.lang.String element,
                                    java.lang.String property,
                                    java.lang.String defaultValue)

A convenience function to get the value of a <property> defined by the first child element of the specified node that has a matching tag name. This routine is often used to obtain properties that are organized into named groups (e.g. <database-settings>, <transport-settings>, etc.)

For example, to lookup a property named "user" of a top-level <database-settings> element,

getProperty( getRootNode(), "database-settings", "user", "sa" );

Parameters:

node - The parent node to search

element - The tag name of the element to search for (it must be a non-repeating child of the parent node)

property - The name of the property

defaultValue - The value to return if the property is not found

Returns:

The property value

getPropertyNodes

public org.w3c.dom.Node[] getPropertyNodes(org.w3c.dom.Node node)

Gets all <property> child nodes of an element

getZoneNodes

public org.w3c.dom.Node[] getZoneNodes()

Gets an array of all zones defined by the configuration file

Returns:

An array of DOM Nodes representing the <zone> elements defined by the configuration file

getZoneNode

public org.w3c.dom.Node getZoneNode(java.lang.String zoneId)

Gets the <zone> element with the specified ID

getZoneTemplates

public org.w3c.dom.Node[] getZoneTemplates(boolean filtered)

Gets an array of all zones templates.

Returns:

An array of DOM Nodes comprised of <template> elements defined as children of the root <agent> node

getZoneTemplateNode

public org.w3c.dom.Node getZoneTemplateNode(java.lang.String templateId)

Gets a zone template by ID.

Parameters:

templateId - The ID of the template to return

Returns:

The DOM Node encapsulating the <template> element with the specified ID

addZoneTemplateNode

public org.w3c.dom.Node addZoneTemplateNode(java.lang.String templateId)

Add a <template> node for the specified zone template.

Returns:

The newly created node, or if a zone template node already exists with this templateId, a reference to it is returned

getTransportNode

public org.w3c.dom.Node getTransportNode(java.lang.String protocol)

Gets a <transport> node.

Parameters:

protocol - The protocol type (e.g. "http", "https", etc.)

Returns:

The DOM Node encapsulating the <transport> element

addTransportNode

public org.w3c.dom.Node addTransportNode(java.lang.String protocol)

Add a <transport> node for the specified transport protocol.

Returns:

The newly created node, or if a transport node already exists for this protocol, a reference to it is returned