edu.sdsc.inca.util
Class SuiteStagesWrapper

java.lang.Object
  extended by edu.sdsc.inca.util.XmlWrapper
      extended by edu.sdsc.inca.util.SuiteStagesWrapper

public class SuiteStagesWrapper
extends XmlWrapper

Convenience object for accessing suite stages documents and persisting changes to them. A suite stages document stores series configs from a suite document in expanded form (i.e., macros are expanded and schedules selected). There are 3 main stages of a suite's series configs. 1) the series configs as specified by the user. These are known in the suite stages document as a "MultiResourceConfigs" meaning that each series config can potentially expand to run on multiple resources. 2) the expanded series configs per resource. These are known in the suite stages document as "PerResourceConfigs" meaning that the series config applies to a single resource.

Author:
Shava Smallen <ssmallen@sdsc.edu>

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
SuiteStagesWrapper(ResourcesWrapper resources)
          Create a SuiteStagesWrapper object with a blank SuiteStages document.
SuiteStagesWrapper(java.lang.String filename, ResourcesWrapper resources)
          Create a new SuiteStagesWrapper object from a SuiteStages file.
SuiteStagesWrapper(java.lang.String filename, java.lang.String passphrase, ResourcesWrapper resources)
          Create a new SuiteStagesWrapper object from a SuiteStages file.
 
Method Summary
static java.lang.String chooseCronFieldValue(java.lang.String field, boolean startAtOne, int count)
          Given a field in a cron line (e.g., hour or day), check it for instances of '?' meaning anytime.
static edu.sdsc.inca.dataModel.util.Schedule chooseSchedule(edu.sdsc.inca.dataModel.util.Schedule schedule)
          A schedule may contain '?' in its cron fields meaning run at any time in the field.
 edu.sdsc.inca.dataModel.suiteStages.SuiteStagesDocument getDocument()
          Return the SuiteStagesDocument contained in this SuiteStagesWrapper object.
 edu.sdsc.inca.dataModel.suite.SuiteDocument getPerResourceSuiteDocument()
          Extract a suite document with all resource series config objects contained in this SuiteStages document.
 int getResourceSeriesConfigCount()
          Return the number of per resource series configs stored in this SuiteStages document.
 java.util.HashMap<java.lang.String,SuiteWrapper> getResourceSuites()
          Iterate through the per resource series configs and extract suites for each of the resources.
static java.util.HashMap<java.lang.String,SuiteWrapper> getResourceSuites(edu.sdsc.inca.dataModel.suite.SuiteDocument suiteDoc)
          Extract suites for each of the resources from the provided SuiteDocument
 int getSeriesConfigCount()
          Return the number of multi-resource series configs stored in this SuiteStages document.
 edu.sdsc.inca.dataModel.suite.SuiteDocument getSuiteDocument()
          Extract a suite document with all multi-resource series config objects contained in this SuiteStages document.
 edu.sdsc.inca.dataModel.suite.SuiteDocument getSuiteDocumentWithVersions()
          Extract a suite document with all multi-resource series config objects contained in this SuiteStages document.
static void main(java.lang.String[] args)
          Provide a command line interface to examining existing suite stage wrapper files or expanding them.
 SuiteStagesWrapper modify(SuiteWrapper suiteChanges)
          Apply multi-resource series config changes in the provided suite to the SuiteStages document.
 void remove()
          Remove the suite document from disk.
 void save()
          Save the suite document to disk.
 java.util.Vector<edu.sdsc.inca.dataModel.util.SeriesConfig> seriesConfigCrossProduct(edu.sdsc.inca.dataModel.util.SeriesConfig seriesConfig, java.lang.String resource)
          Expand the macros contained in the suite's seriesConfig using the definitions provided in resources and create multiple seriesConfig for suiteExpanded.
 void setDocument(edu.sdsc.inca.dataModel.suiteStages.SuiteStagesDocument suiteStages)
          Set a new SuiteStages document for this object.
 edu.sdsc.inca.dataModel.suite.SuiteDocument setResources(ResourcesWrapper resources)
          Set the new resource configuration information and apply it to the existing suite.
 SuiteWrapper updatePackage(java.lang.String name, java.lang.String newVersion, java.lang.String newUri)
           
 
Methods inherited from class edu.sdsc.inca.util.XmlWrapper
configEqual, createCron, cryptSensitive, escape, getPrettyPrintOptions, prettyPrint, read, save, unescape, validate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SuiteStagesWrapper

public SuiteStagesWrapper(ResourcesWrapper resources)
                   throws java.lang.InstantiationException
Create a SuiteStagesWrapper object with a blank SuiteStages document.

Parameters:
resources - The resource configuration information.
Throws:
java.lang.InstantiationException - if unable to create empty document

SuiteStagesWrapper

public SuiteStagesWrapper(java.lang.String filename,
                          ResourcesWrapper resources)
                   throws java.io.IOException,
                          org.apache.xmlbeans.XmlException,
                          CrypterException
Create a new SuiteStagesWrapper object from a SuiteStages file.

Parameters:
filename - Path to a file containing suiteStages compliant XML.
resources - The resource configuration information.
Throws:
CrypterException - if unable to decrypt file
java.io.IOException - if unable to read from disk
org.apache.xmlbeans.XmlException - if unable to parse suite from disk

SuiteStagesWrapper

public SuiteStagesWrapper(java.lang.String filename,
                          java.lang.String passphrase,
                          ResourcesWrapper resources)
                   throws java.io.IOException,
                          org.apache.xmlbeans.XmlException,
                          CrypterException
Create a new SuiteStagesWrapper object from a SuiteStages file.

Parameters:
filename - Path to a file containing suiteStages compliant XML.
passphrase - Secret string used to encrypt/decrypt file to disk
resources - The resource configuration information.
Throws:
CrypterException - if trouble encrypting/decrypting file
java.io.IOException - if problem reading in file
org.apache.xmlbeans.XmlException - if problem parsing suite
Method Detail

chooseCronFieldValue

public static java.lang.String chooseCronFieldValue(java.lang.String field,
                                                    boolean startAtOne,
                                                    int count)
                                             throws ConfigurationException
Given a field in a cron line (e.g., hour or day), check it for instances of '?' meaning anytime. For example, '?' in the hour field would indicate to run at any hour of the day. Similarly, '?' in the minute field would indicate to run at any hour of the minute. '?-[max]/[number]' indicates to run every [number] seconds at any offset with an upper bound of max. For example, '?-23/8' in the hour field indicates to run every 8 hours beginning at any offset. In this latter example, this function could return ?=4-23/8 meaning run at hours 4,12, and 20.

Parameters:
field - The field from a cron line which may or may not contain '?'
startAtOne - True if the minimum value of the field is 1. Otherwise 0 is assumed. E.g., it would be false for minute and true for days.
count - The count for the field. E.g., 24 for hours, 60 for minutes, etc.
Returns:
A string where values are chose for the '?'. For, example '?=52' or '?=2-59/4'.
Throws:
ConfigurationException - if fields are out of range

chooseSchedule

public static edu.sdsc.inca.dataModel.util.Schedule chooseSchedule(edu.sdsc.inca.dataModel.util.Schedule schedule)
                                                            throws ConfigurationException
A schedule may contain '?' in its cron fields meaning run at any time in the field. E.g., ? ?/5 * * * means run every 5th hour at any minute in the day. The agent will resolve these '?' to concrete running times. In the example, the agent could decide to run on the 35th minute of the hour starting at hour 2 (i.e., 35 2-23/5 * * *). The agent will choose running times randomly.

Parameters:
schedule - A schedule that may or may not contain '?'
Returns:
A schedule with all instances of '?' resolved to concrete running times.
Throws:
ConfigurationException - if fields are out of range

updatePackage

public SuiteWrapper updatePackage(java.lang.String name,
                                  java.lang.String newVersion,
                                  java.lang.String newUri)

getDocument

public edu.sdsc.inca.dataModel.suiteStages.SuiteStagesDocument getDocument()
Return the SuiteStagesDocument contained in this SuiteStagesWrapper object.

Returns:
The SuiteStagesDocument stored in this object.

getPerResourceSuiteDocument

public edu.sdsc.inca.dataModel.suite.SuiteDocument getPerResourceSuiteDocument()
Extract a suite document with all resource series config objects contained in this SuiteStages document. This document would be appropriate for sending to the agent's reporter manager controller.

Returns:
A suite document containing all resource series configs in this SuiteStages document.

getResourceSeriesConfigCount

public int getResourceSeriesConfigCount()
Return the number of per resource series configs stored in this SuiteStages document.

Returns:
The number of resource series configs stored in this SuiteStages document.

getSeriesConfigCount

public int getSeriesConfigCount()
Return the number of multi-resource series configs stored in this SuiteStages document.

Returns:
The number of multi-resource configs stored in this SuiteStages document.

getResourceSuites

public java.util.HashMap<java.lang.String,SuiteWrapper> getResourceSuites()
Iterate through the per resource series configs and extract suites for each of the resources.

Returns:
A HashMap where the keys are resource names and the entries are the suite wrapper objects.

getResourceSuites

public static java.util.HashMap<java.lang.String,SuiteWrapper> getResourceSuites(edu.sdsc.inca.dataModel.suite.SuiteDocument suiteDoc)
Extract suites for each of the resources from the provided SuiteDocument

Parameters:
suiteDoc - A suite document with resource series configs.
Returns:
A HashMap where the keys are resource names and the entries are the suites documents.

getSuiteDocument

public edu.sdsc.inca.dataModel.suite.SuiteDocument getSuiteDocument()
Extract a suite document with all multi-resource series config objects contained in this SuiteStages document. This document is appropriate for sending to the user.

Returns:
A suite document containing all multi-resource series configs in this SuiteStages document.

getSuiteDocumentWithVersions

public edu.sdsc.inca.dataModel.suite.SuiteDocument getSuiteDocumentWithVersions()
Extract a suite document with all multi-resource series config objects contained in this SuiteStages document. This document is appropriate for sending to the user. This document is identical to the user's config except that latest version is filled in with concrete version numbers.

Returns:
A suite document containing all multi-resource series configs in this SuiteStages document.

modify

public SuiteStagesWrapper modify(SuiteWrapper suiteChanges)
                          throws SuiteModificationException
Apply multi-resource series config changes in the provided suite to the SuiteStages document.

Parameters:
suiteChanges - A suite document containing multi-resource series config adds/deletes to be applied to the existing suiteStages document.
Returns:
A SuiteStages document containing the expanded multi-resource series config adds/deletes that were applied to the SuiteStages document.
Throws:
SuiteModificationException - if unable to merge changes

remove

public void remove()
Remove the suite document from disk.


save

public void save()
          throws CrypterException,
                 java.io.IOException
Save the suite document to disk.

Throws:
CrypterException - if unable to encrypt document
java.io.IOException - if unable to write to disk

seriesConfigCrossProduct

public java.util.Vector<edu.sdsc.inca.dataModel.util.SeriesConfig> seriesConfigCrossProduct(edu.sdsc.inca.dataModel.util.SeriesConfig seriesConfig,
                                                                                            java.lang.String resource)
                                                                                     throws ConfigurationException
Expand the macros contained in the suite's seriesConfig using the definitions provided in resources and create multiple seriesConfig for suiteExpanded.

Parameters:
seriesConfig - The seriesConfig from a SeriesConfig object from the suite that may contain macros that need to be expanded.
resource - The name of the resource this seriesConfig is being expanded for.
Returns:
A vector or seriesConfig objects that can be inserted into a suite expanded document.
Throws:
ConfigurationException - if unable to expand series config

setDocument

public void setDocument(edu.sdsc.inca.dataModel.suiteStages.SuiteStagesDocument suiteStages)
Set a new SuiteStages document for this object.

Parameters:
suiteStages - A SuiteStages document.

setResources

public edu.sdsc.inca.dataModel.suite.SuiteDocument setResources(ResourcesWrapper resources)
                                                         throws java.lang.Exception
Set the new resource configuration information and apply it to the existing suite. The changes will be returned.

Parameters:
resources - The new resource configuration information
Returns:
The resulting changes of the new resource configuration.
Throws:
java.lang.Exception - if unable to apply to existing resources

main

public static void main(java.lang.String[] args)
Provide a command line interface to examining existing suite stage wrapper files or expanding them. SuiteStagesWrapper [] where suiteFile can be a suite stages doc or a plain suite doc. If dir argument is present, will print out the suites for each host.

Parameters:
args - The command line arguments