com.orchestranetworks.schema
Interface SchemaNode

public interface SchemaNode

Represents an element declaration in the resolved schema.

Method Summary

Object	createNewOccurrence() Creates a new Java object that depends on this node definition.
String	displayOccurrence(Object aValue, boolean useLabels, ValueContext aValueContext, Locale aLocale) Returns a user-friendly representation of the value specified.
Object	executeRead(Object aContainerOccurrence) Reads an occurrence of the parent node so as to return the value corresponding to this node.
String	formatToXsString(Object aValue) Returns the string that corresponds to the value specified.
Object	getDefaultValue() Returns the default value that is defined in schema (attribute xs:default), or null if no value is specified.
String	getDescription(Locale aLocale) Returns the localized description defined in schema.
List	getEnumerationList(ValueContext aContext) Looks for an enumeration of values that may be taken by this node.
Nomenclature	getEnumerationNomenclature(ValueContext aContext) Looks for an underlying Nomenclature.
String	getLabel(Locale aLocale) Returns the localized label defined in schema.
UserMessage	getMandatoryUserMessage() Returns the mandatory error message (defined by schema element osd:mandatoryErrorMessage).
int	getMaxOccurs() Returns the value of xs:maxOccurs.
int	getMinOccurs() Returns the value of xs:minOccurs.
SchemaNode	getNode(Path aPath) Returns the node at the path specified, or null if no node exists at the path specified.
SchemaNode	getNode(Path aPath, boolean isTolerantRead, boolean absolutePathBeginsAtOccurrenceRoot) Returns the node at the path specified.
SchemaNode[]	getNodeChildren() Returns the schema nodes defined directly under this node.
Class	getOccurrencesJavaClass() Returns the default Class of the Java occurrences of this schema node, null if this node is above a terminal node.
Path	getPathInAdaptation() Returns the local absolute path.
Path	getPathInSchema() Returns the full absolute path of this node in the schema.
SchemaLocation	getSchemaLocation() Returns the location of the schema that defines this node.
SchemaNode	getTableOccurrenceRootNode() For a table node (see method isTableNode()), returns the root node of the occurrences' structure.
SchemaTypeName	getXsTypeName() Returns the type name of this node, or null if this node is associated to an anonymous type definition.
boolean	isComplex() Returns true if this node is a complex element declaration.
boolean	isSelectNode() Returns true if this node is a select node.
boolean	isTableNode() Returns true if this node is a table node.
boolean	isTableOccurrenceNode() Returns true if this node is in a table occurrence.
boolean	isTerminalValue() Returns true if this node is adaptation terminal.
boolean	isTerminalValueDescendant() Returns true if this node is the descendant of a terminal value node.
boolean	isValueEqual(Object aFirstValue, Object aSecondValue) Returns true if values specified are equal, according to the underlying XML Schema type.
boolean	isValueLessOrEqualTo(Object aFirstValue, Object aSecondValue) Returns true if first value is less than or equal to the second value, according to the underlying XML Schema type.
boolean	isValueStrictlyLessThan(Object aFirstValue, Object aSecondValue) Returns true if first value is stricty less than the second value, according to the underlying XML Schema type.
Object	parseXsString(String aString) Returns the value that corresponds to the string specified.

Method Detail

getMinOccurs

public int getMinOccurs()

Returns the value of xs:minOccurs.

getMaxOccurs

public int getMaxOccurs()

Returns the value of xs:maxOccurs.

getPathInAdaptation

public Path getPathInAdaptation()

Returns the local absolute path.

In a table occurrence, the local absolute path is the path that starts from the table root node (without including it), otherwise it is the one starting from the instance root node (including it). In the later case it is the same as getPathInSchema().

See Also:

getPathInSchema()

getPathInSchema

public Path getPathInSchema()

Returns the full absolute path of this node in the schema.

See Also:

getPathInAdaptation()

isComplex

public boolean isComplex()

Returns true if this node is a complex element declaration.

isValueEqual

public boolean isValueEqual(Object aFirstValue,
                            Object aSecondValue)

Returns true if values specified are equal, according to the underlying XML Schema type.

For example, if the underlying type is xs:date, both occurrences specified must be Date instances. In addition, equality checking will not take into account the hours, minutes, etc. of the Java Date. However a xs:dateTime type would take into account hours and minutes.

Throws:

ClassCastException - if a specified value is not an instance of underlying type.

isValueLessOrEqualTo

public boolean isValueLessOrEqualTo(Object aFirstValue,
                                    Object aSecondValue)

Returns true if first value is less than or equal to the second value, according to the underlying XML Schema type.

Throws:

UnsupportedOperationException - if underlying type does not support comparison.

ClassCastException - if a specified value is not an instance of underlying type.

isValueStrictlyLessThan

public boolean isValueStrictlyLessThan(Object aFirstValue,
                                       Object aSecondValue)

Returns true if first value is stricty less than the second value, according to the underlying XML Schema type.

Throws:

UnsupportedOperationException - if underlying type does not support comparison.

ClassCastException - if a specified value is not an instance of underlying type.

isTerminalValue

public boolean isTerminalValue()

Returns true if this node is adaptation terminal.

An adaptation terminal node is a node that holds a Java value in adaptation instances and this value can be inherited.

A node is terminal when:

• it is of a simple type and it is not the descendant of a terminal complex (see isTerminalValueDescendant());
• it is a complex node and the schema specifies:
  1. maxOccurs > 1 (required for a osd:table)
  2. a value function, osd:function (see Computed Values)
  3. an access property, osd:access (see Access Properties)

See Also:

isTerminalValueDescendant()

isTerminalValueDescendant

public boolean isTerminalValueDescendant()

Returns true if this node is the descendant of a terminal value node.

See Also:

isTerminalValue()

isTableNode

public boolean isTableNode()

Returns true if this node is a table node.

A table root is specified in schema by means of osd:table declaration (see Table definition).

See Also:

getTableOccurrenceRootNode()

isSelectNode

public boolean isSelectNode()

Returns true if this node is a select node.

A select node is specified in schema by means of osd:select extension.

getTableOccurrenceRootNode

public SchemaNode getTableOccurrenceRootNode()

For a table node (see method isTableNode()), returns the root node of the occurrences' structure.

This method is needed for accessing to the internal structure of a table.

Explanation: Since a table node is considered as a terminal node, it does not provide a direct access to the table node children. Instead those children can only be accessed through the root node of the occurrences' structure (the object returned by this method).

Returns:

null if this node is not a table node, the root node of the occurrences' structure otherwise.

See Also:

isTableNode()

isTableOccurrenceNode

public boolean isTableOccurrenceNode()

Returns true if this node is in a table occurrence.

getEnumerationList

public List getEnumerationList(ValueContext aContext)

Looks for an enumeration of values that may be taken by this node. It is searched through facets in the underlying schema. Returns the list of possible values as defined by enumeration facet.

If a nomenclature facet is defined, it returns the selection of its values.

Returns:

null if no enumeration facet is defined on the schema.

getEnumerationNomenclature

public Nomenclature getEnumerationNomenclature(ValueContext aContext)

Looks for an underlying Nomenclature. It is searched through facets. If no nomenclature is found, it returns null.

Returns:

null if no nomenclature facet is defined on the schema.

getDefaultValue

public Object getDefaultValue()

Returns the default value that is defined in schema (attribute xs:default), or null if no value is specified.

getLabel

public String getLabel(Locale aLocale)

Returns the localized label defined in schema.

getDescription

public String getDescription(Locale aLocale)

Returns the localized description defined in schema.

getMandatoryUserMessage

public UserMessage getMandatoryUserMessage()

Returns the mandatory error message (defined by schema element osd:mandatoryErrorMessage).

getNode

public SchemaNode getNode(Path aPath)

Returns the node at the path specified, or null if no node exists at the path specified.

If path is relative, it is interpreted regarding this node location. This method is equivalent as getNode(aPath, true, false).

See Also:

getPathInSchema()

getNode

public SchemaNode getNode(Path aPath,
                          boolean isTolerantRead,
                          boolean absolutePathBeginsAtOccurrenceRoot)
                   throws PathAccessException

Returns the node at the path specified.

Parameters:

aPath - if relative, it is interpreted regarding this node location.

isTolerantRead - if true, returns null when no node exists at the location specified; otherwise it throws PathAccessException.

absolutePathBeginsAtOccurrenceRoot - if true and aPath is absolute and this node is in a table, then the path root is the table root node.

Throws:

PathAccessException - if no node exists at the path specified and isTolerantRead is false.

getNodeChildren

public SchemaNode[] getNodeChildren()

Returns the schema nodes defined directly under this node. A terminal node returns an empty array (see isTerminalValue()). As a table node is also considered as a terminal node, it will also return an empty array (for getting the structure of the table, it is necessary to use method getTableOccurrenceRootNode())

getSchemaLocation

public SchemaLocation getSchemaLocation()

Returns the location of the schema that defines this node.

getXsTypeName

public SchemaTypeName getXsTypeName()

Returns the type name of this node, or null if this node is associated to an anonymous type definition.

displayOccurrence

public String displayOccurrence(Object aValue,
                                boolean useLabels,
                                ValueContext aValueContext,
                                Locale aLocale)

Returns a user-friendly representation of the value specified.

Value display:

A value can have a display that is different from the standard XML formatted value (see method formatToXsString):

1. Numbers and dates formats: If element is a number (xs:int, xs:decimal, etc.), or a date (xs:date, xs:dateTime, xs:time), it is formatted according to the formatting policy associated to the locale specified.
2. Value labeling: If useLabels is true and element has a declaration that enables value labeling.

Value labeling is possible for:

• a foreign key constraint (osd:tableRef
);
• a labelled enumeration (osd:label inside xs:enumeration);
• a dynamic enumeration on a labelled enumeration (osd:enumeration);
• a programmatic enumeration constraint (osd:constraintEnumeration, this display is furthermore localized since it calls ConstraintEnumeration.displayOccurrence)
• a programmatic nomenclature constraint (osd:constraintNomenclature, display used is NomenclatureItem.getDefaultLabel).

Contexts' limitations:

If ValueContext specified is retrieved on ProcedureContext this method will throw an IllegalArgumentException when dynamic or programmatic labeling involves a call to ValueContext.getValue(Path) with a relative path.

Parameters:

aValue - The value must be compatible with the current node's type. If the current node has its maxOccurs > 1, then value passed as argument must be an element of the List instance, not the List itself.

useLabels - If true and labeling is enabled (see above), specifies that the label associated to the value must be returned. Otherwise the formatted value is returned.

aValueContext - Context holding the value. It must be specified and positionned to this SchemaNode if label to return depends on a contextual and dynamic resolution based on a relative path (see above). Otherwise, null is accepted.

aLocale - Locale for formatting numbers, dates or getting localized labels (if enabled).

See Also:

getEnumerationList(ValueContext), getEnumerationNomenclature(ValueContext)

formatToXsString

public String formatToXsString(Object aValue)

Returns the string that corresponds to the value specified. This method uses the underlying XML Schema type for performing the Object-to-String conversion.

For example, if the underlying type is xs:date, the occurrence specified must be a Date instance and this method will return the XML Schema representation of this date.

See Also:

parseXsString(String)

parseXsString

public Object parseXsString(String aString)

Returns the value that corresponds to the string specified. This method uses the underlying XML Schema type for performing the String-to-Object conversion.

For example, if the underlying type is xs:date, the string must conform to the XML Schema representation of dates (eg "1999-05-31") and this method returns a Date instance.

See Also:

formatToXsString(Object)

getOccurrencesJavaClass

public Class getOccurrencesJavaClass()

Returns the default Class of the Java occurrences of this schema node, null if this node is above a terminal node.

See Also:

isTerminalValue()

createNewOccurrence

public Object createNewOccurrence()

Creates a new Java object that depends on this node definition.

The returned value is in conformity with the following rules:

• If element declaration has maxOccurs > 1, it does not take account this fact (that is it returns an occurrence of the List, not a List instance).
• If element if of a simple type and no default value is defined, it returns null.
• If element if of a simple type and a default value is defined, it returns this default value (a clone of it if this is a mutable object).
• If element if of a complex type, it returns a new instance, either of the class specified in osd:class="" attribute, or of a default internal class (such an instance may be accessed by executeRead(Object)).

executeRead

public Object executeRead(Object aContainerOccurrence)

Reads an occurrence of the parent node so as to return the value corresponding to this node.

Use example

The parent element has maxOccurs > 1 and it refers to a complex content. Hence, the parent value will be a Java List of Java objects. For each object in the list, this method is able to get the value that is associated to this child node.

Precondition

The parent element must be a terminal value (see isTerminalValue()) or the descendant of a terminal value.

Parameters:

aContainerOccurrence - must be an instance (in XML Schema meaning) of the parent node.