edu.sdsc.inca.util
Class ResourcesWrapper

java.lang.Object
  edu.sdsc.inca.util.XmlWrapper
      edu.sdsc.inca.util.ResourcesWrapper

public class ResourcesWrapper
extends XmlWrapper

A convenience class for dealing with resource configuration files which provides methods for accessing the content.

Author:

Shava Smallen <ssmallen@sdsc.edu>

Nested Class Summary

class

ResourcesWrapper.ResourceInfo

Field Summary

Fields inherited from class edu.sdsc.inca.util.XmlWrapper

PASSWORD_MACRO_VALUE_PATTERN, PROCESSING_INSTRUCTION_PATTERN, XML_CDATA_PATTERN, XML_COMMENT_PATTERN, XML_NAME_PATTERN, XML_NODE_PATTERN

Constructor Summary

ResourcesWrapper()
Default constructor which creates a blank resource configuration document.

ResourcesWrapper(java.io.Reader rcXml)
Create a new ResourcesWrapper object from a reader object.

ResourcesWrapper(edu.sdsc.inca.dataModel.resourceConfig.ResourceConfigDocument rcDoc)
Create a new ResourcesWrapper object from an XML Beans class instance.

ResourcesWrapper(java.lang.String filename)
Create a new ResourcesWrapper object from a unencrypted resource configuration XML document file.

ResourcesWrapper(java.lang.String filename, java.lang.String passphrase)
Create a new ResourcesWrapper object from an encrypted resource configuration XML document file.

Method Summary

boolean	equals(java.lang.Object o) Return true iff another object is a ResourcesWrapper with identical resource information.
java.util.Vector<java.lang.String>	expand(java.lang.String stringValue, java.lang.String resource, java.lang.String prevMacro) Expand any macros in the specified string and return the results as a vector of strings.
java.lang.String	getFilePath() Return the path to resources file if applicable.
java.lang.String	getPassphrase() Return the passphrase associated with these resources.
edu.sdsc.inca.dataModel.resourceConfig.ResourceConfigDocument	getResourceConfigDocument() Return the stored resource configuration document.
java.lang.String[]	getResources(java.lang.String resource, boolean hostEquivalence) Recursively find the resource members (i.e., not resource sets) for the provided resource set.
java.lang.String[]	getResourcesByXpath(java.lang.String xpath, boolean hostEquivalence) Recursively find the resource members (i.e., not resource sets) for the resource sets specified in the provided xpath expression.
java.lang.String	getValue(java.lang.String resource, java.lang.String macro) Convenience method for getValues (see getValues for more documentation) when only one value is defined for the specified macro.
java.lang.String[]	getValues(java.lang.String resource, java.lang.String macro) Scan resourceConfig and return a list of values for the macro that applies to this resource.
boolean	hasHostEquivalence(java.lang.String resourceName) Returns true if the given resource resource contains a set of hosts that are considered equivalent (i.e., only need to monitor on one of them)
void	save() Save the resource configuration file to disk.
void	setFilePath(java.lang.String filePath) Set the path to the resources file.
void	setPassphrase(java.lang.String passphrase) Set the passphrase associated with these resources.
void	setResourceConfigDocument(edu.sdsc.inca.dataModel.resourceConfig.ResourceConfigDocument rcDoc) Set the resource configuration document to the provided document.

Methods inherited from class edu.sdsc.inca.util.XmlWrapper

configEqual, createCron, cryptSensitive, escape, getPrettyPrintOptions, main, prettyPrint, read, save, unescape, validate

Methods inherited from class java.lang.Object

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

Constructor Detail

ResourcesWrapper

public ResourcesWrapper()

Default constructor which creates a blank resource configuration document.

ResourcesWrapper

public ResourcesWrapper(edu.sdsc.inca.dataModel.resourceConfig.ResourceConfigDocument rcDoc)
                 throws org.apache.xmlbeans.XmlException

Create a new ResourcesWrapper object from an XML Beans class instance.

Parameters:

rcDoc - An instance of ResourceConfigDocument, a class generated from the schema file by XML Beans

Throws:

org.apache.xmlbeans.XmlException - if unable to verify document

ResourcesWrapper

public ResourcesWrapper(java.lang.String filename)
                 throws CrypterException,
                        java.io.IOException,
                        org.apache.xmlbeans.XmlException

Create a new ResourcesWrapper object from a unencrypted resource configuration XML document file.

Parameters:

filename - Path to a resource configuration XML file

Throws:

CrypterException - if unable to decrypt file

java.io.IOException - if unable to read file

org.apache.xmlbeans.XmlException - if unable to parse file

ResourcesWrapper

public ResourcesWrapper(java.lang.String filename,
                        java.lang.String passphrase)
                 throws CrypterException,
                        java.io.IOException,
                        org.apache.xmlbeans.XmlException

Create a new ResourcesWrapper object from an encrypted resource configuration XML document file.

Parameters:

filename - Path to an encrypted resource configuration XML file

passphrase - Secret string used to encrypt/decrypt file to disk

Throws:

CrypterException - if unable to decrypt file

java.io.IOException - if unable to read file

org.apache.xmlbeans.XmlException - if unable to parse file

ResourcesWrapper

public ResourcesWrapper(java.io.Reader rcXml)
                 throws java.io.IOException,
                        org.apache.xmlbeans.XmlException

Create a new ResourcesWrapper object from a reader object.

Parameters:

rcXml - Reader connected to a character stream to a resource config.

Throws:

java.io.IOException - if unable to read document

org.apache.xmlbeans.XmlException - if unable to parse document

Method Detail

equals

public boolean equals(java.lang.Object o)

Return true iff another object is a ResourcesWrapper with identical resource information.

Overrides:

equals in class java.lang.Object

Parameters:

o - the object to compare

Returns:

true if o contains identical resource information, else false

expand

public java.util.Vector<java.lang.String> expand(java.lang.String stringValue,
                                                 java.lang.String resource,
                                                 java.lang.String prevMacro)
                                          throws ConfigurationException

Expand any macros in the specified string and return the results as a vector of strings. In the case where you have multiple multi-valued macros, the cross product is returned.

Parameters:

stringValue - A string that may contain macros that need to be expanded

resource - The name of the resource this reportSeries is being expanded for.

prevMacro - The name of the previously expanded macro in order to detect infinite recursion.

Returns:

A vector of strings representing the specified string with macros expanded.

Throws:

ConfigurationException - if unable to expand string

getFilePath

public java.lang.String getFilePath()

Return the path to resources file if applicable.

Returns:

A string containing the path to the resources file or null if not set.

getPassphrase

public java.lang.String getPassphrase()

Return the passphrase associated with these resources.

Returns:

A string containing the passphrase

getResourceConfigDocument

public edu.sdsc.inca.dataModel.resourceConfig.ResourceConfigDocument getResourceConfigDocument()

Return the stored resource configuration document.

Returns:

The resource configuration document currently stored in this data access object.

getResources

public java.lang.String[] getResources(java.lang.String resource,
                                       boolean hostEquivalence)
                                throws ConfigurationException

Recursively find the resource members (i.e., not resource sets) for the provided resource set.

Parameters:

resource - The name of a resource set

hostEquivalence - A value of true indicates that resources that have the .equivalent macro defined as true should be treated as one resource. A value of false indicates that that resources that have the .equivalent macro defined as true should be resolved further. The former is good for launching reporter managers (because we only need one reporter manager launched on a resource while the latter is good for sending to the depot (because we don't know what resource the reporter manager will be started on).

Returns:

A string array of resource names belonging to the provided resource set.

Throws:

ConfigurationException - if unable to find resource

getResourcesByXpath

public java.lang.String[] getResourcesByXpath(java.lang.String xpath,
                                              boolean hostEquivalence)
                                       throws ConfigurationException

Recursively find the resource members (i.e., not resource sets) for the resource sets specified in the provided xpath expression.

Parameters:

xpath - A xpath expression that can be used to reference resources specified in the resource configuration file.

hostEquivalence - A value of true indicates that resources that have the .equivalent macro defined as true should be treated as one resource. A value of false indicates that that resources that have the .equivalent macro defined as true should be resolved further. The former is good for launching reporter managers (because we only need one reporter manager launched on a resource while the latter is good for sending to the depot (because we don't know what resource the reporter manager will be started on).

Returns:

A string array of resource names belonging to the provided resource set.

Throws:

ConfigurationException - if unable to retrieve resources

getValue

public java.lang.String getValue(java.lang.String resource,
                                 java.lang.String macro)
                          throws ConfigurationException

Convenience method for getValues (see getValues for more documentation) when only one value is defined for the specified macro.

Parameters:

resource - The name of the resource contained in resourceConfig

macro - The name of a macro contained in resourceConfig

Returns:

The value of the macro or null if not found

Throws:

ConfigurationException - if unable to get macro

getValues

public java.lang.String[] getValues(java.lang.String resource,
                                    java.lang.String macro)
                             throws ConfigurationException

Scan resourceConfig and return a list of values for the macro that applies to this resource. Resources can be grouped by specifying a xpath expression. Since a group of resources can contain macros, in the case that a resource defines a macro and a resource group that contains the resource also defines the same macro, the resource's macro takes precedence. For example, in the following snippet of xml, the value returned for the macro gridFTPPort will be 2812. If tg-login.sdsc.teragrid.org did not have gridFTPPort defined, then 2811 (from sdsc) would be returned.

   <resource>
     <name>sdsc</name>
     <resources>
       <resource>
         <name>tg-login.sdsc.teragrid.org</name>
         <macros>
           <macro>
             <name>gridFTPPort</name>
             <value>2812</value>
             ...
   <resource>
     <name>sdsc</name>
     <xpath>//resource[matches(name, '^*.sdsc.*$')]</xpath>
     <macros>
       <macro>
         <name>.gridFtpPort</name>
         <value>2811</value>
      </macro>
       ...
 

Parameters:

resource - The name of the resource contained in resourceConfig

macro - The name of a macro contained in resourceConfig

Returns:

A string array of values for the macro or null if not found

Throws:

ConfigurationException - if unable to find macro

hasHostEquivalence

public boolean hasHostEquivalence(java.lang.String resourceName)

Returns true if the given resource resource contains a set of hosts that are considered equivalent (i.e., only need to monitor on one of them)

Parameters:

resourceName - The name of a resource.

Returns:

True if the resource contains a set of hosts that are equivalent and false otherwise.

save

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

Save the resource configuration file to disk.

Throws:

CrypterException - if unable to encrypt file

java.io.IOException - if unable to write to disk

setFilePath

public void setFilePath(java.lang.String filePath)

Set the path to the resources file.

Parameters:

filePath - A string containing the path to where the resources file can be read/stored.

setPassphrase

public void setPassphrase(java.lang.String passphrase)

Set the passphrase associated with these resources.

Parameters:

passphrase - A string containing the passphrase

setResourceConfigDocument

public void setResourceConfigDocument(edu.sdsc.inca.dataModel.resourceConfig.ResourceConfigDocument rcDoc)
                               throws org.apache.xmlbeans.XmlException

Set the resource configuration document to the provided document.

Parameters:

rcDoc - An instance of ResourceConfigDocument, a class generated from the schema file by XML Beans

Throws:

org.apache.xmlbeans.XmlException - if unable to validate document