edu.sdsc.inca.util
Class ResourcesWrapper

java.lang.Object
  extended by edu.sdsc.inca.util.XmlWrapper
      extended by 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