com.waveset.object
Class WavesetResult

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

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.
 
Fields inherited from class com.waveset.util.AbstractXmlObject
_trace
 
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(ErrorMessage msg)
           
 void addError(Message msg)
          Deprecated. Use addError(ErrorMessage) instead.
 void addError(ResultError err)
          Add a ResultError object.
 void addException(java.lang.Throwable t)
          Add an exception to the result.
 ResultItem addMessage(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(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.
 java.lang.String getElementName()
          Return the name of our XML element, required by XmlObject.
 Message getErrorMessage()
          Convenience method to return the first error message in the result.
 java.util.List getErrorMessages()
          Convenience method to return a list of all error messages found in this result.
 java.util.List 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.
 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 getResults()
          Return the list of results.
 java.util.List getResultsByClass(java.lang.Class c)
          Return the list of ResultItems with the given class.
 ResultTable getResultTable()
          Return the first ResultTable in the result item list.
 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 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 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(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, println, setTrace, toIdentityString, toVerboseString, toVerboseString, toXml, toXml, toXml
 
Methods inherited from class java.lang.Object
clone, equals, finalize, 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
Constructor Detail

WavesetResult

public WavesetResult()
Construct an empty result


WavesetResult

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


WavesetResult

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

Method Detail

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

getName

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


setName

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


getTitle

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


setTitle

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


isEmpty

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

getResults

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


getResourceResult

public 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.


getResultTable

public 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.


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.


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.


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.String type,
                                 java.lang.Object value)
Add a named object to the result.


addNamedResult

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


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.


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.


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.


getResultByClass

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


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.


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


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.


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.


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 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 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.


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.


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 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 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.


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.


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.


getErrorMessages

public java.util.List getErrorMessages()
Convenience method to return a list of all error messages found in this result.


getErrorMessages

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


getErrorMessage

public 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.


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.


addMessage

public ResultItem addMessage(Message msg)

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.


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.


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.


addWarning

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


addError

public void addError(Message msg)
Deprecated. Use addError(ErrorMessage) instead.

Add an error message to the result.


addError

public void addError(ErrorMessage msg)

addError

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


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

parseXml

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

Throws:
WavesetException