edu.sdsc.inca.util
Class SuiteStagesWrapper

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