org.apache.tuscany.sdo.api
Interface SDOHelper

All Known Implementing Classes:
SDOHelperBase, SDOHelperImpl

public interface SDOHelper

This interface provides helper functions which are not included in the SDO specification itself. Use of the functions in this interface is recommended, instead of resorting to low-level implementation-specific APIs.


Nested Class Summary
static interface SDOHelper.MetaDataBuilder
          This interface provides methods which can be used to programatically create SDO Types and Properties.
static interface SDOHelper.XMLOptions
          This interface contains options that can be passed to the XMLHelper load() and save() methods.
 
Field Summary
static int UNBOUNDED
           
static int UNSPECIFIED
           
 
Method Summary
 void addChangeListener(DataObject dob, EventListener listener)
          An experimental interface, subject to possible change that permits registration of an event listener with a DataObject instance
 String convertToString(Type dataType, Object value)
          Converts an instance of a data type to a string literal representation.
 CopyHelper createCrossScopeCopyHelper(HelperContext targetScope)
          Create a new cross scope CopyHelper.
 DataGraph createDataGraph()
          Create an empty data graph.
 DataObject createDataTypeWrapper(Type dataType, Object value)
          Create a DataObject wrapper for an instance of the specified dataType.
 Object createFromString(Type dataType, String literal)
          Creates an instance of a data type from the specified string.
 HelperContext createHelperContext()
          Create a non-extensible HelperContext to provide access to a consistent set of Helpers which make use of a new TypeHelper instance to provide scope for type definitions.
 HelperContext createHelperContext(boolean extensibleNamespaces)
          Create a HelperContext to provide access to a consistent set of Helpers which make use of a new TypeHelper instance to provide scope for type definitions.
 HelperContext createHelperContext(boolean extensibleNamespaces, Map options)
          Create a non-extensible HelperContext to provide access to a consistent set of Helpers which make use of a new TypeHelper instance to provide scope for type definitions.
 HelperContext createHelperContext(Map options)
          create a non-extensible HelperContext with default load/save options
 ObjectInputStream createObjectInputStream(InputStream inputStream, HelperContext helperContext)
          Create a new ObjectInputStream in the specifice HelperContext scope.
 ObjectOutputStream createObjectOutputStream(OutputStream outputStream, HelperContext helperContext)
          Create a new ObjectOutputStream in the specifice HelperContext scope.
 XMLStreamHelper createXMLStreamHelper(HelperContext hc)
          Create a new XMLStreamHelper, with visibility to types in the specified HelperContext scope.
 List getEnumerationFacet(Type type)
          Return Enumeration facet
 Type getJavaSDOType(Class javaClass)
          Get the SDO built-in type corresponding to the specified Java instanceClass.
 int getLowerBound(Property property)
          Return the lower bound of the specified property or 1 by default
 SDOHelper.MetaDataBuilder getMetaDataBuilder()
          Gets a MetaDataBuilder which can be used to programatically create SDO Types and Properties.
 List getOpenContentProperties(DataObject dataObject)
          Gets the open content subset of the specified DataObject's instance properties.
 List getPatternFacet(Type type)
          Return Pattern facet
 Sequence getSubstitutionValues(DataObject dataObject, Property head)
          Gets the Sequence corresponding to the specified substitutable Property of the specified DataObject.
 List getTypes(HelperContext hc, String uri)
          Gets all of the types associated with a uri.
 int getUpperBound(Property property)
          Return the upper bound of the specified property or -1 if unbounded.
 String getXPath(DataObject dataObject)
          Return an XPath from the containment root to the specified DataObject.
 Type getXSDSDOType(String xsdType)
          Get the SDO built-in type corresponding to the specified XSD type in the XML Schema namespace ("http://www.w3.org/2001/XMLSchema").
 boolean isDocumentRoot(Type type)
          Return true if the specified type is a special DocumentRoot Type.
 boolean isMany(Property property, DataObject context)
          Returns whether the Property is many-valued given the specified context.
 boolean isRequired(Property property)
          Return whether at least one value is required for a valid instance of the specified property.
 DataGraph loadDataGraph(InputStream inputStream, Map options, HelperContext hc)
          Load a serialized data graph from the specified insputStream.
 void registerDataGraphTypes(DataGraph dataGraph, List types)
          Registers the specified type(s) to be serialized along with the data object(s) in the graph.
 void removeChangeListener(DataObject dob, EventListener listener)
          An experimental interface, subject to possible change that permits deregistration of an event listener with a DataObject instance
 void saveDataGraph(DataGraph dataGraph, OutputStream outputStream, Map options)
          Serialize the specified data graph to the specified outputStream.
 void setRootObject(DataGraph dataGraph, DataObject rootObject)
          Set the root object of a data graph.
 

Field Detail

UNBOUNDED

static final int UNBOUNDED
See Also:
Constant Field Values

UNSPECIFIED

static final int UNSPECIFIED
See Also:
Constant Field Values
Method Detail

createHelperContext

HelperContext createHelperContext()
Create a non-extensible HelperContext to provide access to a consistent set of Helpers which make use of a new TypeHelper instance to provide scope for type definitions.

Returns:
the new HelperContext
See Also:
createHelperContext(boolean)

createHelperContext

HelperContext createHelperContext(boolean extensibleNamespaces,
                                  Map options)
Create a non-extensible HelperContext to provide access to a consistent set of Helpers which make use of a new TypeHelper instance to provide scope for type definitions.

Parameters:
options - Map of default XMLOptions
Returns:
the new HelperContext
See Also:
createHelperContext(boolean)

createHelperContext

HelperContext createHelperContext(boolean extensibleNamespaces)
Create a HelperContext to provide access to a consistent set of Helpers which make use of a new TypeHelper instance to provide scope for type definitions.

Parameters:
extensibleNamespaces - true if the contents of a namespaces should be incrementally modifiable over time
Returns:
the new HelperContext

createHelperContext

HelperContext createHelperContext(Map options)
create a non-extensible HelperContext with default load/save options

Parameters:
options - default load/save options from XMLOptions
Returns:
the new HelperContext

createFromString

Object createFromString(Type dataType,
                        String literal)
Creates an instance of a data type from the specified string.

Parameters:
dataType - a Type, for which isDataType() returns true, to instantiate.
literal - the string value of the dataType.
Returns:
an instance of the dataType.
See Also:
convertToString(Type, Object)

convertToString

String convertToString(Type dataType,
                       Object value)
Converts an instance of a data type to a string literal representation.

Parameters:
dataType - the Type, for which isDataType() returns true, of the value to convert.
value - a value of the dataType.
Returns:
the string literal representation of the value.
See Also:
createFromString(Type, String)

createDataTypeWrapper

DataObject createDataTypeWrapper(Type dataType,
                                 Object value)
Create a DataObject wrapper for an instance of the specified dataType. This method is typically used to create a root object that can be passed to the XMLHelper.save() method when the root element to be serialized is an XMLSchema simpleType.

Parameters:
dataType - a Type for which isDataType() returns true.
value - the instance value.
Returns:
a DataObject wrapper for the specified value.

getXSDSDOType

Type getXSDSDOType(String xsdType)
Get the SDO built-in type corresponding to the specified XSD type in the XML Schema namespace ("http://www.w3.org/2001/XMLSchema").

Parameters:
xsdType - a type name in the XML Schema namespace.
Returns:
the SDO built-in Type corresponding to the specified XSD type.

getSubstitutionValues

Sequence getSubstitutionValues(DataObject dataObject,
                               Property head)
Gets the Sequence corresponding to the specified substitutable Property of the specified DataObject.

Parameters:
dataObject - the data object.
head - a substitution group head property.
Returns:
the Sequence corresponding to the specified substitutable Property of the specified DataObject or null if the specified Property isn't a substitution head.

getJavaSDOType

Type getJavaSDOType(Class javaClass)
Get the SDO built-in type corresponding to the specified Java instanceClass.

Parameters:
javaClass - the Java instanceClass of the type.
Returns:
the SDO built-in Type corresponding to the specified instanceClass.

isRequired

boolean isRequired(Property property)
Return whether at least one value is required for a valid instance of the specified property.

Parameters:
the - property in question.
Returns:
true if the property is required.

getUpperBound

int getUpperBound(Property property)
Return the upper bound of the specified property or -1 if unbounded.

Parameters:
the - property in question.
Returns:
the upper bound.

getLowerBound

int getLowerBound(Property property)
Return the lower bound of the specified property or 1 by default

Parameters:
the - property in question.
Returns:
the lower bound.

getEnumerationFacet

List getEnumerationFacet(Type type)
Return Enumeration facet

Parameters:
type -
Returns:
List of enum facets in a Type

getPatternFacet

List getPatternFacet(Type type)
Return Pattern facet

Parameters:
type -
Returns:
List of pattern facets in a Type

isMany

boolean isMany(Property property,
               DataObject context)
Returns whether the Property is many-valued given the specified context.

Parameters:
property - The Property in question
context - The context to check whether the specified Property is many-valued
Returns:
true if the Property is many-valued given the specified context.

createDataGraph

DataGraph createDataGraph()
Create an empty data graph.

Returns:
the new data graph instance.

setRootObject

void setRootObject(DataGraph dataGraph,
                   DataObject rootObject)
Set the root object of a data graph.

Parameters:
dataGraph - the data graph in which to set the root object.
rootObject - the root object.

loadDataGraph

DataGraph loadDataGraph(InputStream inputStream,
                        Map options,
                        HelperContext hc)
                        throws IOException
Load a serialized data graph from the specified insputStream.

Parameters:
inputStream - the inputStream of the data graph.
options - loader control options, or null.
hc - the HelperContext in which to register deserialized Types and to find Types when creating DataObject instances, or null for default HelperContext.
Returns:
the de-serialized data graph.
Throws:
IOException

saveDataGraph

void saveDataGraph(DataGraph dataGraph,
                   OutputStream outputStream,
                   Map options)
                   throws IOException
Serialize the specified data graph to the specified outputStream.

Parameters:
dataGraph - the data graph to save.
outputStream - the outputStream for the data graph.
options - serializer control options, or null.
Throws:
IOException

registerDataGraphTypes

void registerDataGraphTypes(DataGraph dataGraph,
                            List types)
Registers the specified type(s) to be serialized along with the data object(s) in the graph. For example, the list of types returned from TypeHelper.define(commonj.sdo.DataObject) can be registered with this method, allowing deserialization of instances of a dynamically defined model.

Parameters:
dataGraph - the DataGraph in which to register the specified type(s).
types - a list containing the type(s) to be registered (TBD or null to automatically register all types used by the objects in the DataGraph).

createCrossScopeCopyHelper

CopyHelper createCrossScopeCopyHelper(HelperContext targetScope)
Create a new cross scope CopyHelper.

Parameters:
hc - the HelperContext containing the Types to use to create the copy objects.
Returns:
the new CopyHelper.

createXMLStreamHelper

XMLStreamHelper createXMLStreamHelper(HelperContext hc)
Create a new XMLStreamHelper, with visibility to types in the specified HelperContext scope.

Parameters:
hc - the HelperContext to use for locating types.
Returns:
the new XMLStreamHelper.

createObjectInputStream

ObjectInputStream createObjectInputStream(InputStream inputStream,
                                          HelperContext helperContext)
                                          throws IOException
Create a new ObjectInputStream in the specifice HelperContext scope.

Parameters:
inputStream - the inputStream with which to create the ObjectInputStream.
helperContext - the HelperContext scope.
Returns:
the new ObjectInputStream.
Throws:
IOException

createObjectOutputStream

ObjectOutputStream createObjectOutputStream(OutputStream outputStream,
                                            HelperContext helperContext)
                                            throws IOException
Create a new ObjectOutputStream in the specifice HelperContext scope.

Parameters:
outputStream - the outputStream with which to create the ObjectOutputStream.
helperContext - the HelperContext scope.
Returns:
the new ObjectOutputStream.
Throws:
IOException

getTypes

List getTypes(HelperContext hc,
              String uri)
Gets all of the types associated with a uri.

Parameters:
hc - the HelperContext to use for locating types.
uri - the URI of the Types
Returns:
a List containing instances of Type, null if uri is not found.

getOpenContentProperties

List getOpenContentProperties(DataObject dataObject)
Gets the open content subset of the specified DataObject's instance properties.

Parameters:
dataObject - the DataObject instance
Returns:
a List containing any open content properties of the DataObject

isDocumentRoot

boolean isDocumentRoot(Type type)
Return true if the specified type is a special DocumentRoot Type.

Parameters:
type - the Type in question
Returns:
true if type is a DocumentRoot

getXPath

String getXPath(DataObject dataObject)
Return an XPath from the containment root to the specified DataObject.

Parameters:
dataObject - a DataObject
Returns:
the XPath from the containment root.

getMetaDataBuilder

SDOHelper.MetaDataBuilder getMetaDataBuilder()
Gets a MetaDataBuilder which can be used to programatically create SDO Types and Properties.

Returns:
a MetaDataBuilder instance

addChangeListener

void addChangeListener(DataObject dob,
                       EventListener listener)
An experimental interface, subject to possible change that permits registration of an event listener with a DataObject instance

Parameters:
dob - DataObject
listener - EventListener

removeChangeListener

void removeChangeListener(DataObject dob,
                          EventListener listener)
An experimental interface, subject to possible change that permits deregistration of an event listener with a DataObject instance

Parameters:
dob - DataObject
listener - EventListener


Copyright © 2013 The Apache Software Foundation. All Rights Reserved.