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 Summary

Constructors

Constructor and Description
Outcome(int id, Document dom, Schema schema) Very basic constructor to set all members
Outcome(int id, String xml, Schema schema) Use this constructor to manipulate, validate and store this outcome
Outcome(String xml) Use this constructor for XML manipulation only.
Outcome(String path, Document data) The constructor derives all the meta data (ID and Schema) from the path
Outcome(String xml, Schema schema) Use this constructor for XML manipulation and validation.
Outcome(String path, String xml) The constructor derives all the meta data (ID and Schema) from the path

Method Summary

Modifier and Type	Method and Description
Node	appendXmlFragment(String xpath, String xmlFragment) Append the new Node created from xmlFragment as a child of the Node selected by the XPath
Object	evaluateXpath(String xpathExpr, QName returnType) Evaluates the given XPath expression thread-safely and efficiently
List<Map<String,String>>	getAllRecords(String xpath) Reads all Attributes and child Elements of the list of Node selected by the xpath
List<List<String>>	getAllRecords(String xpath, List<String> names) Reads list of list of values of the Attributes and child Elements of the list of Elements selected by the xpath.
String	getAttribute(Element element, String name) Retrieves an Attribute value by name of the given Element.
String	getAttribute(String name) Retrieves an Attribute value by name of the root Element.
String	getAttributeOfField(String field, String attribute) Retrieves an Attribute value by name from the named Element.
String	getClusterPath() Each C2KLocalObject is stored with a path identifier starting with the ClusterType: 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
ClusterType	getClusterType() Returns ClusterType.OUTCOME
String	getData() Returns the serialised DOM as a string
String	getField(Element element, String name) Retrieves the textNode value of the named Element of the given Element.
String	getField(String name) Retrieves the textNode value of the named Element of the root Element.
String	getFieldByXPath(String xpath) Retrieves the text, CDATA or attribute value of the Node selected by the XPath
String	getName() Gets the name of the C2KLocalObject
Node	getNodeByXPath(String xpathExpr) Gets a List selected by the xpath
NodeList	getNodesByXPath(String xpathExpr) Gets a NodeList selected by the xpath
String	getNodeValue(Node node) Gets the value of the given TEXT, CDATA, ATTRIBUTE or ELEMENT Node
Map<String,String>	getRecord() Reads the all Attributes and child Elements of the root Element
List<String>	getRecord(List<String> names) Reads list of values of the Attributes and child Elements of the root Element.
Map<String,String>	getRecord(String xpath) Reads the all Attributes and child Elements of the Node selected by the xpath
List<String>	getRecord(String xpath, List<String> names) Reads list of values of the Attributes and child Elements of the Element selected by the xpath.
List<String>	getRecordOfElement(Element element, List<String> names) Reads list of values of the Attributes and child Elements of the given Element.
Map<String,String>	getRecordOfNode(Node node) Reads the all Attributes and child Elements of the given Node
String	getSchemaType() Deprecated.
int	getSchemaVersion() Deprecated.
boolean	hasField(Element element, String name)
boolean	hasField(String name)
static boolean	isIdentical(Document origDocument, Document otherDOM) Utility method to comare 2 XML Documents
boolean	isIdentical(Outcome other) Checks if the Outcome is identical with the given input
static Document	newDocument()
static Document	parse(InputSource xml) Parses the input source into a DOM tree.
static Document	parse(String xml) Parses the xml string into a DOM tree
Node	removeNodeByXPath(String xpathExpr) Removes the node selected by the xpath
static String	serialize(Node node, boolean prettyPrint) Serialize the Given Document
void	setAttribute(Element element, String name, String data) Sets an Attribute value by name of the given Element.
void	setAttribute(Element element, String name, String data, boolean remove) Sets an Attribute value by name of the given Element.
void	setAttribute(String name, String data) Sets an Attribute value by name of the root Element.
void	setAttribute(String name, String data, boolean remove) Sets the value of an attribute in the root Element.
void	setAttributeOfField(String field, String name, String data) Sets the value of an attribute in a given Field, i.e.
void	setAttributeOfField(String field, String name, String data, boolean remove) Sets the value of an attribute in a given Field, i.e.
void	setData(String xml)
void	setField(Element element, String name, String data) Sets the textNode value of the named Element of the given Element.
void	setField(Element element, String name, String data, boolean remove) Sets the textNode value of the named Element of the given Element.
void	setField(String name, String data) Sets the textNode value of the named Element of the root Element.
void	setField(String name, String data, boolean remove) Sets the textNode value of the named Element of the root Element.
void	setFieldByXPath(String xpath, String data) Sets the text, CDATA or attribute value of the Node selected by the XPath.
void	setFieldByXPath(String xpath, String data, boolean remove) Sets the text, CDATA or attribute value of the Node selected by the XPath.
protected void	setMetaDataFromPath(String path) Retrieves the SchemaName, Version, EevetnId triplet from the path.
void	setName(String name) Sets the name of the C2KLocalObject
void	setNodeValue(Node node, String value) Sets the value of the given TEXT, CDATA, ATTRIBUTE or ELEMENT Node
void	setNodeValue(Node node, String value, boolean useCdata) Sets the value of the given TEXT, CDATA, ATTRIBUTE or ELEMENT Node
void	setRecord(Element element, Map<String,String> record) Sets the values of Attributes and child Element of given Element.
void	setRecord(Map<String,String> record) Sets the values of Attributes and child Element of the root Element.
void	setRecord(String xpath, Map<String,String> record) Sets the values of Attributes and child Element of the Element selected by xpath.
String	validate() Validates the actual XML Document against the provided Schema
void	validateAndCheck() Validates the actual XML Document against the provided Schema

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.cristalise.kernel.entity.C2KLocalObject

enforceValidName

Constructor Detail

Outcome

public Outcome(String xml)
        throws InvalidDataException

Use this constructor for XML manipulation only. This Outcome cannot be validate not 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,
               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 Detail

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

Parameters:

xpathExpr - the XPath exporession

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

Returns:

the xml string

getSchemaType

@Deprecated
public String getSchemaType()

Deprecated.

getSchemaVersion

@Deprecated
public int getSchemaVersion()

Deprecated.

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:

• 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:

doc - document to be serialized

prettyPrint - if the xml is pretty printed or not

Returns:

the xml string

Throws:

InvalidDataException - Transformer Exception

getRecordOfNode

public Map<String,String> getRecordOfNode(Node node)

Reads the all Attributes and child Elements of the given Node

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 otherDOM)

Utility method to comare 2 XML Documents

Parameters:

origDocument - XML document

otherDOM - the other XML

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)