com.waveset.object
Class WavesetResult

java.lang.Object
  extended by com.waveset.util.AbstractXmlObject
      extended by com.waveset.object.WavesetResult
All Implemented Interfaces:
XmlObject, javax.naming.Referenceable

public class WavesetResult
extends AbstractXmlObject

An object used to encapsulate a complex set of results. Originally developed to capture status from background workflow tasks, now also being used by provisioning operations that may affect more than one resource.

A result is a list of items, defined by the ResultItem class. Each item has a value which may be any XmlObject. Items may have an optional name and an optional type.

Some item values are self describing and need no type qualifier. Others may use the type to indicate the semantics of the value. For example the value of an item containing a message may be a simple String object. To indicate that this is a displayable message the item type ResultItem.TYPE_MESSAGE is used.

NOTE: This has evolved several times. We originally supported the notion of a "status" on each item which was an indication of error severity: ok, warning, and error. This was confusing since not all items have a severity level. The new ErrorMessage object is a better way to express this. // *

// * I thought about eliminating the ResultItem object and instead just // * maintaining a list of things, but this would require a different // * kind of wrapper object for simple items like messages to distinguish // * them from non-displayable data values. So we either get rid of // * ResultItem and introduce ResultMessage and ResultData, or keep // * ResultItem and live with a sometimes unnecessary level of indirection. // * Having ResultItem also allows us to give items names, which comes // * in handy with workflow, where we may wish to modify previously // * added results. // *

See Also:
ResultItem

Field Summary
static java.lang.String code_id
           
static java.lang.String ELEMENT
          The name of our XML element.
static java.lang.String ITEM_TYPE
          Value for the ResultItem type of a nested result object.
static java.lang.String PROVISION_STATUS
          ResultItem name commonly added to result indicating the status of the provisioning operation when workflow is involved.
 
Constructor Summary
WavesetResult()
          Construct an empty result
WavesetResult(org.w3c.dom.Element e)
          Construct a result object from its DOM representation.
WavesetResult(java.lang.String xml)
          Create a result object by parsing its XML representation.
 
Method Summary
 ResultItem add(java.lang.Object object)
          Add an object to the result.
 void addError(com.waveset.msgcat.ErrorMessage msg)
           
 void addError(ResultError err)
          Add a ResultError object.
 void addException(java.lang.Throwable t)
          Add an exception to the result.
 ResultItem addMessage(com.waveset.msgcat.Message msg)
           
 ResultItem addMessage(java.lang.String msg)
          Add an pre-formatted ordinary message to the result.
 ResultItem addNamedResult(java.lang.String name, java.lang.Object value)
          Add a named data object to the result.
 ResultItem addNamedResult(java.lang.String name, java.lang.String type, java.lang.Object value)
          Add a named object to the result.
 void addResult(ResultItem item)
          Add a new item to the result object.
 ResultItem addResult(java.lang.String type, java.lang.Object value)
          Add a typed string result.
 void addWarning(com.waveset.msgcat.Message msg)
          Add an warning message to the result.
 void assimilate(WavesetResult res)
          Appends the items in one result with this one.
 void assimilateMessages(WavesetResult src)
          Append the messages or errors from another result.
 GenericObject findAsynchInfo()
          Get the optional GenericObject object containing the asynchronous info on this or any contained WavesetResult.
 GenericObject getAsynchInfo()
          Get the optional GenericObject object containing the asynchronous info.
 java.lang.String getElementName()
          Return the name of our XML element, required by XmlObject.
 com.waveset.msgcat.Message getErrorMessage()
          Convenience method to return the first error message in the result.
 java.util.List<com.waveset.msgcat.Message> getErrorMessages()
          Convenience method to return a list of all error messages found in this result.
 java.util.List<com.waveset.msgcat.Message> getErrorMessages(int maxMessages)
          Convenience method to return up to the specified number of error messages from this result.
 java.util.List getErrors()
          Convenience method to extract a flat list of String objects for each error item in the result, formatted according to the current locale.
 void getErrors(java.util.List errors)
          Convenience method to extract a flat list of String objects for each error item in the result, formatted according to the current locale.
 void getErrors(java.util.List errors, java.util.Locale locale)
          Convenience method to extract a flat list of String objects for each error item in the result, formatted according to the given locale.
 java.util.List getErrors(java.util.Locale locale)
          Convenience method to extract a flat list of String objects for each error item in the result, formatted according to the given locale.
 java.util.List getMessages()
          Convenience method to extract a flat list of String objects for each non-error message in the result, formatted according to the current locale.
 void getMessages(java.util.List messages)
          Convenience method to extract a flat list of String objects for each non-error message in the result, formatted according to the current locale.
 void getMessages(java.util.List messages, java.util.Locale locale)
          Convenience method to extract a flat list of String objects for each non-error message in the result, formatted according to the given locale.
 java.util.List getMessages(java.util.Locale locale)
          Convenience method to extract a flat list of String objects for each non-error message in the result, formatted according to the given locale.
 java.lang.String getName()
          Get the result name.
 java.lang.Object getNamedResultValue(java.lang.String name)
          Convenience method to return the value of the first item that has a given name.
 WavesetResult getNestedResult(java.lang.String name)
          Recursively search for a nested WavesetResult with the given name.
 com.waveset.object.ResourceResult getResourceResult(java.lang.String name)
          Return a specific resource result.
 java.lang.Object getResult(java.lang.String type)
          Convenience method to return the value of the first item that has a given type.
 ResultItem getResultByClass(java.lang.Class c)
          Search for a result value by class.
 ResultItem getResultByName(java.lang.String name)
          Return the first ResultItem with the given name.
 ResultItem getResultByType(java.lang.String type)
          Return the first ResultItem with the given type.
 ResultItem getResultItem(java.lang.String type)
          Return the first ResultItem with the given type.
 java.util.List getResultItemList(java.lang.String type)
          Return a list of ResultItems with the given type.
 java.util.ArrayList<ResultItem> getResults()
          Return the list of results.
 java.util.List getResultsByClass(java.lang.Class c)
          Return the list of ResultItems with the given class.
 com.waveset.object.ResultTable getResultTable()
          Return the first ResultTable in the result item list.
 com.waveset.msgcat.Message getTitle()
          Get the optional Message object containing the result title.
 boolean hasError()
          Originally we tried to maintain the _status field as an indication of whether there were any error in this result.
 boolean hasWarning()
          Originally we tried to maintain the _status field as an indication of whether there were any error in this result.
 boolean isAsynchronous()
          Indicates whether or not this is the result of an asynchronous result.
 boolean isEmpty()
           
 boolean isError()
          The first version of the class defined this method which checked a field we tried to keep up to date.
 void parseXml(org.w3c.dom.Element e)
          Parse the DOM representation of a result, and set the corresponding fields.
 void removeResult(ResultItem item)
          Remove a result item.
 void removeResultByName(java.lang.String name)
          Remove a result item with the given name.
 void removeResultByType(java.lang.String type)
          Remove a result item with the given type.
 void setAsynchInfo(GenericObject asynchInfo)
          Set the asynchronous info.
 void setAsynchronous(boolean async)
          Indicates that this is the result of an asynchronous task.
 void setName(java.lang.String name)
          Set the result name.
 ResultItem setNamedResult(java.lang.String name, java.lang.String type, java.lang.Object value)
          Add or update a result item.
 ResultItem setResult(java.lang.String type, java.lang.Object value)
          Assing a result by type, overwriting any current result with that type.
 void setTitle(com.waveset.msgcat.Message msg)
          Set the title message.
 void toXml(java.lang.StringBuffer b, int indent)
          Serialize the result to an XML buffer.
 
Methods inherited from class com.waveset.util.AbstractXmlObject
addXmlHeader, cloneObject, dump, dumpFile, getReference, setTrace, toIdentityString, toVerboseString, toVerboseString, toXml, toXml, toXml
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

code_id

public static final java.lang.String code_id
See Also:
Constant Field Values

ELEMENT

public static final java.lang.String ELEMENT
The name of our XML element.

See Also:
Constant Field Values

ITEM_TYPE

public static final java.lang.String ITEM_TYPE
Value for the ResultItem type of a nested result object.

See Also:
Constant Field Values

PROVISION_STATUS

public static final java.lang.String PROVISION_STATUS
ResultItem name commonly added to result indicating the status of the provisioning operation when workflow is involved.

See Also:
Constant Field Values
Constructor Detail

WavesetResult

public WavesetResult()
Construct an empty result


WavesetResult

public WavesetResult(org.w3c.dom.Element e)
              throws com.waveset.util.WavesetException
Construct a result object from its DOM representation. Required by XmlObject.

Throws:
com.waveset.util.WavesetException

WavesetResult

public WavesetResult(java.lang.String xml)
              throws com.waveset.util.WavesetException
Create a result object by parsing its XML representation.

Throws:
com.waveset.util.WavesetException
Method Detail

add

public ResultItem add(java.lang.Object object)
Add an object to the result. We maintain item types for some of the self describing ones just because we've always done so, though this isn't really necessary.


addError

public void addError(com.waveset.msgcat.ErrorMessage msg)

addError

public void addError(ResultError err)
Add a ResultError object.


addException

public void addException(java.lang.Throwable t)
Add an exception to the result.

This gets converted into a MESSAGE item, with a status of ERROR, and whose value is the text of the message.

Note that we store the com.waveset.msgcat.Message object if the exception has one since we may want to reformat the message for a different locale when it is eventually rendered. If the exception has no Message, we just store the message text.

We might have to store more here, possibly the class name of the exception, that would potentially allow us to recreate the exception object when the item is deserialized.


addMessage

public ResultItem addMessage(com.waveset.msgcat.Message msg)

addMessage

public ResultItem addMessage(java.lang.String msg)
Add an pre-formatted ordinary message to the result.

You should be using Message objects, but this is supported to ease the transition to message catalogs, or for emergency "can't happen" messages.


addNamedResult

public ResultItem addNamedResult(java.lang.String name,
                                 java.lang.Object value)
Add a named data object to the result.


addNamedResult

public ResultItem addNamedResult(java.lang.String name,
                                 java.lang.String type,
                                 java.lang.Object value)
Add a named object to the result.


addResult

public void addResult(ResultItem item)
Add a new item to the result object.

The global status will be updated if the item status is more severe than the current global status.


addResult

public ResultItem addResult(java.lang.String type,
                            java.lang.Object value)
Add a typed string result.

You would call this if you wanted your own item type, beyond the build-in types for messages and errors.


addWarning

public void addWarning(com.waveset.msgcat.Message msg)
Add an warning message to the result.


assimilate

public void assimilate(WavesetResult res)
Appends the items in one result with this one.

This may be used in places where a "master" result is being maintained and sub-operations produce result objects of their own that need to be assimilated into the master result.


assimilateMessages

public void assimilateMessages(WavesetResult src)
Append the messages or errors from another result.


findAsynchInfo

public GenericObject findAsynchInfo()
Get the optional GenericObject object containing the asynchronous info on this or any contained WavesetResult.


getAsynchInfo

public GenericObject getAsynchInfo()
Get the optional GenericObject object containing the asynchronous info.


getElementName

public java.lang.String getElementName()
Return the name of our XML element, required by XmlObject.

Specified by:
getElementName in interface XmlObject
Specified by:
getElementName in class AbstractXmlObject
Returns:
the element name

getErrorMessage

public com.waveset.msgcat.Message getErrorMessage()
Convenience method to return the first error message in the result. This is not recommended for applications, since there may be more than one error in the result, and you probably need to display all of them. This should only be used by the unit tests that aren't really expecting errors, but want to display something if they hit one.

Similar to hasError, but we look specifically for Message objects whereas hasError will stop on the first item with an error status.


getErrorMessages

public java.util.List<com.waveset.msgcat.Message> getErrorMessages()
Convenience method to return a list of all error messages found in this result.


getErrorMessages

public java.util.List<com.waveset.msgcat.Message> getErrorMessages(int maxMessages)
Convenience method to return up to the specified number of error messages from this result.


getErrors

public java.util.List getErrors()
Convenience method to extract a flat list of String objects for each error item in the result, formatted according to the current locale.


getErrors

public void getErrors(java.util.List errors)
Convenience method to extract a flat list of String objects for each error item in the result, formatted according to the current locale.


getErrors

public void getErrors(java.util.List errors,
                      java.util.Locale locale)
Convenience method to extract a flat list of String objects for each error item in the result, formatted according to the given locale.


getErrors

public java.util.List getErrors(java.util.Locale locale)
Convenience method to extract a flat list of String objects for each error item in the result, formatted according to the given locale.


getMessages

public java.util.List getMessages()
Convenience method to extract a flat list of String objects for each non-error message in the result, formatted according to the current locale.


getMessages

public void getMessages(java.util.List messages)
Convenience method to extract a flat list of String objects for each non-error message in the result, formatted according to the current locale.


getMessages

public void getMessages(java.util.List messages,
                        java.util.Locale locale)
Convenience method to extract a flat list of String objects for each non-error message in the result, formatted according to the given locale.


getMessages

public java.util.List getMessages(java.util.Locale locale)
Convenience method to extract a flat list of String objects for each non-error message in the result, formatted according to the given locale.


getName

public java.lang.String getName()
Get the result name.


getNamedResultValue

public java.lang.Object getNamedResultValue(java.lang.String name)
Convenience method to return the value of the first item that has a given name.


getNestedResult

public WavesetResult getNestedResult(java.lang.String name)
Recursively search for a nested WavesetResult with the given name.


getResourceResult

public com.waveset.object.ResourceResult getResourceResult(java.lang.String name)
Return a specific resource result. If more than one account on a resource was processed, we return the first result on the list.


getResult

public java.lang.Object getResult(java.lang.String type)
Convenience method to return the value of the first item that has a given type.

This should only be used if you know from context that there will only be one item of this type in the result. It should not be used for displaying messages, since there can be more than one message in the result.


getResultByClass

public ResultItem getResultByClass(java.lang.Class c)
Search for a result value by class.


getResultByName

public ResultItem getResultByName(java.lang.String name)
Return the first ResultItem with the given name.


getResultByType

public ResultItem getResultByType(java.lang.String type)
Return the first ResultItem with the given type.


getResultItem

public ResultItem getResultItem(java.lang.String type)
Return the first ResultItem with the given type.

This should only be used if you know from context that there will only be one item of this type in the result. It should not be used for displaying messages, since there can be more than one message in the result. !! Would like to change the behavior to search by name only


getResultItemList

public java.util.List getResultItemList(java.lang.String type)
Return a list of ResultItems with the given type.

This should only be used if you know from context that there will only be one item of this type in the result. It should not be used for displaying messages, since there can be more than one message in the result. !! Would like to change the behavior to search by name only


getResults

public java.util.ArrayList<ResultItem> getResults()
Return the list of results. This is a java collection of ResultItem objects.


getResultsByClass

public java.util.List getResultsByClass(java.lang.Class c)
Return the list of ResultItems with the given class. Calling code can assume that the list contains ResultItems (no nulls) and that the ResultItems all have non-null values that are instances of the specified class.


getResultTable

public com.waveset.object.ResultTable getResultTable()
Return the first ResultTable in the result item list. A convenience method used by ResourceResult to locate the result table that is ordinarilly created by the provisining engine.


getTitle

public com.waveset.msgcat.Message getTitle()
Get the optional Message object containing the result title.


hasError

public boolean hasError()
Originally we tried to maintain the _status field as an indication of whether there were any error in this result. This turns out to be unreliable to maintain especially with nested results and things like ResourceResult. Since we normally don't have many results, we should move to using hasError instead and get rid of the _state field.


hasWarning

public boolean hasWarning()
Originally we tried to maintain the _status field as an indication of whether there were any error in this result. This turns out to be unreliable to maintain especially with nested results and things like ResourceResult.


isAsynchronous

public boolean isAsynchronous()
Indicates whether or not this is the result of an asynchronous result.

Returns:
boolean where true indicates this is the result of an asynchronous task; false otherwise

isEmpty

public boolean isEmpty()
Returns:
true if this result is devoid of meaning.

isError

public boolean isError()
The first version of the class defined this method which checked a field we tried to keep up to date. Changed to hasError to do a traversal. This is still used by a lot of adapter tests, so keep it around.


parseXml

public void parseXml(org.w3c.dom.Element e)
              throws com.waveset.util.WavesetException
Parse the DOM representation of a result, and set the corresponding fields.

Throws:
com.waveset.util.WavesetException

removeResult

public void removeResult(ResultItem item)
Remove a result item. Should we have a recursive variant of this?


removeResultByName

public void removeResultByName(java.lang.String name)
Remove a result item with the given name.


removeResultByType

public void removeResultByType(java.lang.String type)
Remove a result item with the given type.


setAsynchInfo

public void setAsynchInfo(GenericObject asynchInfo)
Set the asynchronous info.


setAsynchronous

public void setAsynchronous(boolean async)
Indicates that this is the result of an asynchronous task. This method can be used if there is no further information that would be useful to setAsynchInfo.

Parameters:
async - boolean where true indicates that this is the result of an asynchronous task.

setName

public void setName(java.lang.String name)
Set the result name.


setNamedResult

public ResultItem setNamedResult(java.lang.String name,
                                 java.lang.String type,
                                 java.lang.Object value)
Add or update a result item.

You would call this if for result items that can be changed after having been added. If the value is null, the existing item will be removed.


setResult

public ResultItem setResult(java.lang.String type,
                            java.lang.Object value)
Assing a result by type, overwriting any current result with that type. Used only by ExtendedResultsMonitor, should convert that to use named results.


setTitle

public void setTitle(com.waveset.msgcat.Message msg)
Set the title message.


toXml

public void toXml(java.lang.StringBuffer b,
                  int indent)
Serialize the result to an XML buffer.

Specified by:
toXml in interface XmlObject
Specified by:
toXml in class AbstractXmlObject
Parameters:
b - StringBuffer in which to write the generated xml
indent - Number of spaces to indent the generated xml block