Package org.cristalise.kernel.persistency.outcome

Class Outcome

java.lang.Object
org.cristalise.kernel.persistency.outcome.Outcome
All Implemented Interfaces:
C2KLocalObject
public class Outcome extends Object implements C2KLocalObject
A C2KLocalObject encapsulating management of XML data. It has methods to manipulate and validate the XML, and with a valid ID it can be stored in ClusterStore. It contains lot of utility code to read and set data in the Outcome (xml).

  • Constructor Details

    • Outcome

      public Outcome(String xml) throws InvalidDataException
      Use this constructor for XML manipulation only. This Outcome cannot be validate nor it can be stored in ClusterStore.
      Parameters:
      xml - the XML string to be manipulated
      Throws:
      InvalidDataException - there was an error parsing the XML

    • Outcome

      public Outcome(String xml, Schema schema) throws InvalidDataException
      Use this constructor for XML manipulation and validation. This Outcome cannot be stored in ClusterStore.
      Parameters:
      xml - the XML string to be manipulated
      schema - the Schema of the XML
      Throws:
      InvalidDataException - there was an error parsing the XML

    • Outcome

      public Outcome(int id, String xml, String schemaName, Integer schemaVersion) throws InvalidDataException
      Throws:
      InvalidDataException

    • Outcome

      public Outcome(int id, String xml, Schema schema) throws InvalidDataException
      Use this constructor to manipulate, validate and store this outcome
      Parameters:
      id - eventID
      xml - the XML string to be manipulated
      schema - the Schema of the XML
      Throws:
      InvalidDataException - there was an error parsing the XML

    • Outcome

      public Outcome(int id, Document dom, Schema schema)
      Very basic constructor to set all members
      Parameters:
      id - eventID
      dom - parsed XML Document
      schema - the Schema instance

    • Outcome

      public Outcome(String path, String xml) throws PersistencyException, InvalidDataException
      The constructor derives all the meta data (ID and Schema) from the path
      Parameters:
      path - the actuals path used by the ClusterStorage
      xml - the XML string to parse
      Throws:
      PersistencyException - there was DB error
      InvalidDataException - Version or EventID was an invalid number

    • Outcome

      public Outcome(String path, Document data) throws PersistencyException, InvalidDataException
      The constructor derives all the meta data (ID and Schema) from the path
      Parameters:
      path - the actuals path used by the ClusterStorage
      data - the parsed xml Document
      Throws:
      PersistencyException - there was DB error
      InvalidDataException - Version or EventID was an invalid number

  • Method Details

    • getSchema

      public Schema getSchema()
      Gets the Schema object associated with the Outcome
      Returns:
      the Schema object associated with the Outcome

    • getSchema

      public Schema getSchema(TransactionKey transactionKey)
      Gets the Schema object associated with the Outcome
      Parameters:
      transactionKey - the key of the transaction
      Returns:
      the Schema object associated with the Outcome

    • setMetaDataFromPath

      protected void setMetaDataFromPath(String path) throws PersistencyException, InvalidDataException
      Retrieves the SchemaName, Version, EevetnId triplet from the path. Check getClusterPath() implementation
      Parameters:
      path - the ClusterPath to work with
      Throws:
      PersistencyException - path was incorrect
      InvalidDataException - Schema was not found or the Path has incorrect data

    • evaluateXpath

      public Object evaluateXpath(String xpathExpr, QName returnType) throws XPathExpressionException
      Evaluates the given XPath expression thread-safely and efficiently. It starts fromt he root Node.
      Parameters:
      xpathExpr - the XPath expression
      Returns:
      the result of the evaluated expression
      Throws:
      XPathExpressionException - If expression cannot be compiled.

    • evaluateXpath

      public Object evaluateXpath(Node startNode, String xpathExpr, QName returnType) throws XPathExpressionException
      Evaluates the given XPath expression thread-safely and efficiently
      Parameters:
      startNode - the starting Node
      xpathExpr - the XPath expression
      Returns:
      the result of the evaluated expression
      Throws:
      XPathExpressionException - If expression cannot be compiled.

    • validate

      public String validate() throws InvalidDataException
      Validates the actual XML Document against the provided Schema
      Returns:
      the errors found
      Throws:
      InvalidDataException - Schema was null

    • validateAndCheck

      public void validateAndCheck() throws InvalidDataException
      Validates the actual XML Document against the provided Schema
      Throws:
      InvalidDataException - XML document is not valid instance of the Schema

    • setName

      public void setName(String name)
      Description copied from interface: C2KLocalObject
      Sets the name of the C2KLocalObject
      Specified by:
      setName in interface C2KLocalObject
      Parameters:
      name - Name of the C2KLocalObject

    • getName

      public String getName()
      Description copied from interface: C2KLocalObject
      Gets the name of the C2KLocalObject
      Specified by:
      getName in interface C2KLocalObject
      Returns:
      name of the C2KLocalObject

    • setData

      public void setData(String xml) throws SAXException, IOException
      Throws:
      SAXException
      IOException

    • getNodeValue

      public String getNodeValue(Node node) throws InvalidDataException
      Gets the value of the given TEXT, CDATA, ATTRIBUTE or ELEMENT Node
      Parameters:
      node - the Node to work on
      Returns:
      the value of the node
      Throws:
      InvalidDataException - the Node is not a proper type

    • setNodeValue

      public void setNodeValue(Node node, String value) throws InvalidDataException
      Sets the value of the given TEXT, CDATA, ATTRIBUTE or ELEMENT Node
      Parameters:
      node - the Node to work on
      value - the value to set
      Throws:
      InvalidDataException - the Node is not a proper type

    • setNodeValue

      public void setNodeValue(Node node, String value, boolean useCdata) throws InvalidDataException
      Sets the value of the given TEXT, CDATA, ATTRIBUTE or ELEMENT Node
      Parameters:
      node - the Node to work on
      value - the value to set
      useCdata - force to use CDATA
      Throws:
      InvalidDataException - the Node is not a proper type

    • getFieldByXPath

      public String getFieldByXPath(String xpath) throws XPathExpressionException, InvalidDataException
      Retrieves the text, CDATA or attribute value of the Node selected by the XPath
      Parameters:
      xpath - The path to access the selected Node
      Returns:
      the value of the selected Node
      Throws:
      XPathExpressionException - xpath was not valid (e.g. there is no such node)
      InvalidDataException - xpath result is not text, CDATA or attribute

    • setAttribute

      public void setAttribute(Element element, String name, String data, boolean remove) throws InvalidDataException
      Sets an Attribute value by name of the given Element. It only updates existing Attributes. If data is null, Element exists and the remove flag is true the node is removed.
      Parameters:
      element - the Element to search
      name - the name of the Attribute
      data - the value to set
      remove - flag to remove existing node when data is null
      Throws:
      InvalidDataException - the attribute was not found

    • setAttribute

      public void setAttribute(Element element, String name, String data) throws InvalidDataException
      Sets an Attribute value by name of the given Element. It only updates existing Attributes.
      Parameters:
      element - the Element to search
      name - the name of the Attribute
      data - the value to set
      Throws:
      InvalidDataException - the Attribute was not found

    • setAttribute

      public void setAttribute(String name, String data, boolean remove) throws InvalidDataException
      Sets the value of an attribute in the root Element. It can only update existing attributes.
      Parameters:
      name - the name of the Attribute
      data - the value to be set
      remove - flag to remove the element if the data is null
      Throws:
      InvalidDataException - attribute was not found

    • setAttribute

      public void setAttribute(String name, String data) throws InvalidDataException
      Sets an Attribute value by name of the root Element.
      Parameters:
      name - the name of the Attribute
      data - the value to set
      Throws:
      InvalidDataException - the name was not found

    • setAttributeOfField

      public void setAttributeOfField(String field, String name, String data, boolean remove) throws InvalidDataException
      Sets the value of an attribute in a given Field, i.e. named Element. It can only update existing attributes.
      Parameters:
      field - the named Element in the root Element
      name - the name of the Attribute
      data - the value to be set
      remove - flag to remove the element if the data is null
      Throws:
      InvalidDataException - Element or attribute was not found

    • setAttributeOfField

      public void setAttributeOfField(String field, String name, String data) throws InvalidDataException
      Sets the value of an attribute in a given Field, i.e. named Element. It can only update existing attributes.
      Parameters:
      field - the named Element in the root Element
      name - the name of the Attribute
      data - the value to be set
      Throws:
      InvalidDataException - Element or attribute was not found

    • setField

      public void setField(Element element, String name, String data, boolean remove) throws InvalidDataException
      Sets the textNode value of the named Element of the given Element. It only updates existing Element.
      Parameters:
      element - Element to use
      name - the name of the Element
      data - the data to be set
      remove - flag to remove the element if the data is null
      Throws:
      InvalidDataException - the name was not found or there were more Elements with the given name

    • setField

      public void setField(Element element, String name, String data) throws InvalidDataException
      Sets the textNode value of the named Element of the given Element. It only updates existing Element.
      Parameters:
      element - Element to use
      name - the name of the Element
      data - the data to be set
      Throws:
      InvalidDataException - the name was not found or there were more Elements with the given name

    • setField

      public void setField(String name, String data, boolean remove) throws InvalidDataException
      Sets the textNode value of the named Element of the root Element. It only updates existing Element.
      Parameters:
      name - the name of the Element
      data - the data to be set
      remove - flag to remove the element if the data is null
      Throws:
      InvalidDataException - the name was not found or there were more Elements with the given name

    • setField

      public void setField(String name, String data) throws InvalidDataException
      Sets the textNode value of the named Element of the root Element. It only updates existing Element.
      Parameters:
      name - the name of the Element
      data - the data to be set
      Throws:
      InvalidDataException - the name was not found or there were more Elements with the given name

    • setFieldByXPath

      public void setFieldByXPath(String xpath, String data) throws XPathExpressionException, InvalidDataException
      Sets the text, CDATA or attribute value of the Node selected by the XPath. It only updates existing Nodes.
      Parameters:
      xpath - the selected Node to be updated
      data - string containing the data
      Throws:
      XPathExpressionException - xpath is invalid
      InvalidDataException - xpath result is not text, CDATA or attribute

    • setFieldByXPath

      public void setFieldByXPath(String xpath, String data, boolean remove) throws XPathExpressionException, InvalidDataException
      Sets the text, CDATA or attribute value of the Node selected by the XPath. It only updates existing Nodes. If data is null and the node exists, the node is removed
      Parameters:
      xpath - the selected Node to be updated
      data - string containing the data, it can be null
      remove - flag to remove existing node when data is null
      Throws:
      XPathExpressionException - xpath is invalid
      InvalidDataException - xpath result is not text, CDATA or attribute

    • appendXmlFragment

      public Node appendXmlFragment(String xpath, String xmlFragment) throws InvalidDataException
      Append the new Node created from xmlFragment as a child of the Node selected by the XPath
      Parameters:
      xpath - the selected parent node
      xmlFragment - string containing the xml fragment
      Returns:
      the Node just added
      Throws:
      InvalidDataException

    • getData

      public String getData()
      Returns the serialised DOM as a string without pretty printing-
      Returns:
      the xml string

    • getData

      public String getData(boolean prettyPrint)
      Returns the serialised DOM as a string -
      Parameters:
      prettyPrint - is the string should be pretty printed or not
      Returns:
      the xml string

    • getSchemaName

      public String getSchemaName()
      Gets the name or UUID of the Schema item associated with the Outcome
      Returns:
      the name or UUID of the Schema item associated with the Outcome

    • getSchemaType

      public String getSchemaType()
      Deprecated.
      use getSchemaName() instead
      Returns:

    • getSchemaVersion

      public int getSchemaVersion()
      Gets the version of the Schema item associated with the Outcome
      Returns:
      the version of the Schema item associated with the Outcome

    • getClusterType

      public ClusterType getClusterType()
      Returns ClusterType.OUTCOME
      Specified by:
      getClusterType in interface C2KLocalObject
      Returns:
      string id of the type

    • getClusterPath

      public String getClusterPath()
      Description copied from interface: C2KLocalObject
      Each C2KLocalObject is stored with a path identifier starting with the ClusterType:
      • DomainPath: /Path/Domain/Name
      • ItemPath: /Path/Item
      • AgentPath: /Path/Agent
      • RolePath: /Path/Role/Name
      • Properties: /Property/Name
      • Workflow: /LifeCycle/workflow
      • Collections: /Collection/Name/Version (default Name='last')
      • Outcomes: /Outcome/SchemaName/SchemaVersion/EventID
      • Viewpoints: /ViewPoint/SchemaName/Name (default Name='last')
      • Events: /AuditTrail/EventID
      • Jobs: /Job/JobID
      Specified by:
      getClusterPath in interface C2KLocalObject
      Returns:
      The path identifier (i.e. primary key) of the object

    • newDocument

      public static Document newDocument() throws SAXException, IOException
      Throws:
      SAXException
      IOException

    • parse

      public static Document parse(String xml) throws SAXException, IOException
      Parses the xml string into a DOM tree
      Parameters:
      xml - string to be parsed, can be null. When xml is null it creates empty Document.
      Returns:
      the parsed Document
      Throws:
      SAXException - error parsing document
      IOException - any IO errors occur

    • parse

      public static Document parse(InputSource xml) throws SAXException, IOException
      Parses the input source into a DOM tree. When input source is null it creates empty Document.
      Parameters:
      xml - string to be parsed, can be null.
      Returns:
      the parsed Document
      Throws:
      SAXException - error parsing document
      IOException - any IO errors occur

    • getAttribute

      public String getAttribute(Element element, String name)
      Retrieves an Attribute value by name of the given Element.
      Parameters:
      element - the Element to query
      name - The name of the attribute to retrieve.
      Returns:
      The value as a string, or null if that attribute does not have a specified or default value.

    • getAttribute

      public String getAttribute(String name)
      Retrieves an Attribute value by name of the root Element.
      Parameters:
      name - The name of the attribute to retrieve.
      Returns:
      The value as a string, or null if that attribute does not have a specified or default value.

    • getAttributeOfField

      public String getAttributeOfField(String field, String attribute)
      Retrieves an Attribute value by name from the named Element.
      Parameters:
      field - The name of the field.
      attribute - The name of the attribute to retrieve.
      Returns:
      The value as a string, or null if that attribute does not have a specified or default value.

    • getField

      public String getField(Element element, String name)
      Retrieves the textNode value of the named Element of the given Element.
      Parameters:
      element - the Element to query
      name - The name of the Element
      Returns:
      The value as a string, or null if that field does not exists

    • getField

      public String getField(String name)
      Retrieves the textNode value of the named Element of the root Element.
      Parameters:
      name - The name of the Element
      Returns:
      The value as a string, or null if that field does not exists

    • getNodesByXPath

      public NodeList getNodesByXPath(String xpathExpr) throws XPathExpressionException
      Gets a NodeList selected by the xpath
      Parameters:
      xpathExpr - the xpath to select the list of Nodes
      Returns:
      NodeList
      Throws:
      XPathExpressionException - invalid xpath

    • getNodeByXPath

      public Node getNodeByXPath(String xpathExpr) throws XPathExpressionException
      Gets a List selected by the xpath
      Parameters:
      xpathExpr - the xpath to select the list of Nodes
      Returns:
      Node
      Throws:
      XPathExpressionException - invalid xpath

    • removeNodeByXPath

      public Node removeNodeByXPath(String xpathExpr) throws XPathExpressionException, InvalidDataException
      Removes the node selected by the xpath
      Parameters:
      xpathExpr - xpath to select the Node
      Returns:
      the Node removed
      Throws:
      XPathExpressionException - invalid xpath
      InvalidDataException - invalid xpath

    • serialize

      public static String serialize(Node node, boolean prettyPrint) throws InvalidDataException
      Serialize the given Document
      Parameters:
      prettyPrint - if the xml is pretty printed or not
      doc - document to be serialized
      Returns:
      the xml string
      Throws:
      InvalidDataException - Transformer Exception

    • traverseChildElements

      public static void traverseChildElements(Node node, Consumer<Node> action)

    • getRecordOfNode

      public Map<String,String> getRecordOfNode(Node node)
      Reads the all Attributes and child Elements of the given Node. Use TreeMap to keep the order of Nodes.
      Parameters:
      node - the node to work with
      Returns:
      a Map as a key/value pairs of Attribute/Element names with their value

    • getRecord

      public Map<String,String> getRecord()
      Reads the all Attributes and child Elements of the root Element
      Returns:
      a Map as a key/value pairs of Attribute/Element names with their value

    • getRecord

      public Map<String,String> getRecord(String xpath) throws XPathExpressionException
      Reads the all Attributes and child Elements of the Node selected by the xpath
      Parameters:
      xpath - the xpath pointing to the Node
      Returns:
      a Map as a key/value pairs of Attribute/Element names with their value
      Throws:
      XPathExpressionException - xpath is invalid

    • getAllRecords

      public List<Map<String,String>> getAllRecords(String xpath) throws XPathExpressionException
      Reads all Attributes and child Elements of the list of Node selected by the xpath
      Parameters:
      xpath - selecting the list of Nodes
      Returns:
      List of Maps as a key/value pairs of Attribute/Element names with their value
      Throws:
      XPathExpressionException - xpath is invalid

    • getRecordOfElement

      public List<String> getRecordOfElement(Element element, List<String> names)
      Reads list of values of the Attributes and child Elements of the given Element. The values are returned in the order specified in the names parameter. It only return values for the list of names. Null is added to the result if there is no value for the given name.
      Parameters:
      element - the Element to use
      names - the the Attributes and Element names to retrieve
      Returns:
      List of values

    • getRecord

      public List<String> getRecord(List<String> names)
      Reads list of values of the Attributes and child Elements of the root Element. The values are returned in the order specified in the names parameter. It only return values for the list of names. Null is added to the result if there is no value for the given name.
      Parameters:
      names - the the Attributes and Element names to retrieve
      Returns:
      List of values

    • getRecord

      public List<String> getRecord(String xpath, List<String> names) throws XPathExpressionException
      Reads list of values of the Attributes and child Elements of the Element selected by the xpath. The values are returned in the order specified in the names parameter. It only return values for the list of names. Null is added to the result if there is no value for the given name.
      Parameters:
      xpath - to select the Element
      names - the the Attributes and Element names to retrieve
      Returns:
      List of values
      Throws:
      XPathExpressionException - invalid xpath

    • getAllRecords

      public List<List<String>> getAllRecords(String xpath, List<String> names) throws XPathExpressionException
      Reads list of list of values of the Attributes and child Elements of the list of Elements selected by the xpath. The values are returned in the order specified in the names parameter. It only return values for the list of names. Null is added to the result if there is no value for the given name.
      Parameters:
      xpath - to select the list of Element
      names - the the Attributes and Element names to retrieve
      Returns:
      List of list of values
      Throws:
      XPathExpressionException - invalid xpath

    • setRecord

      public void setRecord(Map<String,String> record) throws InvalidDataException
      Sets the values of Attributes and child Element of the root Element. It only updates existing elements.
      Parameters:
      record - Map with a key/value pairs to find the fields or attributes to update
      Throws:
      InvalidDataException - the name in the map was invalid

    • setRecord

      public void setRecord(String xpath, Map<String,String> record) throws InvalidDataException, XPathExpressionException
      Sets the values of Attributes and child Element of the Element selected by xpath. It only updates existing elements.
      Parameters:
      xpath - apth to the Element to be updated
      record - Map with a key/value pairs to find the fields or attributes to update
      Throws:
      InvalidDataException - the name in the map was invalid
      XPathExpressionException - the xpath was invalid

    • setRecord

      public void setRecord(Element element, Map<String,String> record) throws InvalidDataException
      Sets the values of Attributes and child Element of given Element. It only updates existing elements.
      Parameters:
      element - the element to be updated
      record - Map with a key/value pairs to find the fields or attributes to update
      Throws:
      InvalidDataException - the name in the map was invalid

    • isIdentical

      public boolean isIdentical(Outcome other)
      Checks if the Outcome is identical with the given input
      Parameters:
      other - the other Outcome to be compare with
      Returns:
      true if the two Outcomes are identical, otherwise returns false

    • isIdentical

      public static boolean isIdentical(Document origDocument, Document otherDocument)
      Utility method to comare 2 XML Documents
      Parameters:
      origDocument - XML document
      otherDocument - the other XML document
      Returns:
      true if the two XML Documents are identical, otherwise returns false

    • hasField

      public boolean hasField(String name)

    • hasField

      public boolean hasField(Element element, String name)

    • getRootName

      public String getRootName()

    • toString

      public String toString()
      Overrides:
      toString in class Object