Package org.dlese.dpc.xml.schema

Class SchemaHelper

java.lang.Object
org.dlese.dpc.xml.schema.SchemaHelper
public class SchemaHelper extends Object
Class encapsluting semantics of XML Schemas.

Aggregates tools and data structures for working with XML Schemas, and is in turn encapsulated in the MetaDataFramework object. Major components include

  • instanceDocument - an xml document representing a "normalized" schema (i.e., in which all elements are defined in-line rather than as dataTypes). An schema instance document is x-path equivalent to a valid xml document for the schema, but contains no values.
  • XSDatatypeManager for performing iterative validation of xml documents using datatypes defined in the Schema.
  • DefinitionMiner which traverses an XML Schema and builds a dictionary of GlobalElement objects, one for each element defined in the Schema.
  • SchemaNodeMap that represents the structure defined by the Schema as a tree of SchemaNode objects.
The SchemaHelper constructors take either a URI or File and builds these structures as it traverseses the schema definition, which may consist of several files.

NOTE: The SchemaHelper assumes that XML Schemas are represented using the "Venetian Blind" technique.

Author:
ostwald

  • Field Details

  • Constructor Details

    • SchemaHelper

      public SchemaHelper(File schemaFile) throws SchemaHelperException
      Constructor for the SchemaHelper object
      Parameters:
      schemaFile - NOT YET DOCUMENTED
      Throws:
      SchemaHelperException - NOT YET DOCUMENTED

    • SchemaHelper

      public SchemaHelper(File schemaFile, String rootElementName) throws SchemaHelperException
      Constructor for the SchemaHelper object for disk-based schema
      Parameters:
      schemaFile - path to root file of schema
      rootElementName - NOT YET DOCUMENTED
      Throws:
      SchemaHelperException - Description of the Exception

    • SchemaHelper

      public SchemaHelper(URL schemaURL) throws SchemaHelperException
      Constructor for the SchemaHelper object
      Parameters:
      schemaURL - NOT YET DOCUMENTED
      Throws:
      SchemaHelperException - NOT YET DOCUMENTED

    • SchemaHelper

      public SchemaHelper(URL schemaURL, String rootElementName) throws SchemaHelperException
      Constructor for the SchemaHelper object using web-based schema.
      Parameters:
      schemaURL - URL to root file of schema
      rootElementName - NOT YET DOCUMENTED
      Throws:
      SchemaHelperException - Description of the Exception

  • Method Details

    • getNamespaceEnabled

      public boolean getNamespaceEnabled()
      Gets the namespaceEnabled attribute of the SchemaHelper object
      Returns:
      The namespaceEnabled value

    • getSchemaProps

      public SchemaProps getSchemaProps()
      Gets the schemaProps attribute of the SchemaHelper object
      Returns:
      The schemaProps value

    • getSchemaLocation

      public String getSchemaLocation()
      Gets the rootURI attribute of the SchemaHelper object
      Returns:
      The rootURI value

    • getSchemaNamespace

      public org.dom4j.Namespace getSchemaNamespace()

    • getVersion

      public String getVersion()
      Gets the version attribute of the SchemaHelper object
      Returns:
      The version value

    • getRootElementName

      public String getRootElementName()
      Gets the rootElementName attribute of the SchemaHelper object
      Returns:
      The rootElementName value

    • getTargetNamespace

      public String getTargetNamespace()
      Gets the targetNamespace attribute of the SchemaHelper object
      Returns:
      The targetNamespace value

    • getGlobalDef

      public GlobalDef getGlobalDef(String typeName)
      Gets a globalDef from the default namespace of the globalDefMap.
      Parameters:
      typeName - the name of the globalDef object
      Returns:
      a GlobalDef object, or null if not found.

    • getGlobalDef

      public GlobalDef getGlobalDef(SchemaNode schemaNode)
      Gets a globalDef from the globalDefMap.
      Parameters:
      schemaNode - a SchemaNode object
      Returns:
      a GlobalDef object, or null if not found.

    • getCompositor

      public Compositor getCompositor(String xpath)
      Gets the compositor attribute of the SchemaHelper object
      Parameters:
      xpath - NOT YET DOCUMENTED
      Returns:
      The compositor value

    • getCompositor

      public Compositor getCompositor(SchemaNode schemaNode)
      Gets the compositor attribute of the SchemaHelper object
      Parameters:
      schemaNode - NOT YET DOCUMENTED
      Returns:
      The compositor value

    • getInstanceDocNode

      public org.dom4j.Node getInstanceDocNode(String xpath)
      Gets a Node from the instanceDocument
      Parameters:
      xpath - xpath specifying the desired node
      Returns:
      The instanceDocument Node (or null if Node is not found)

    • getInstanceDocNodes

      public List getInstanceDocNodes(String xpath)
      Gets the instanceDocNodes attribute of the SchemaHelper object
      Parameters:
      xpath - NOT YET DOCUMENTED
      Returns:
      The instanceDocNodes value

    • getSchemaNode

      public SchemaNode getSchemaNode(String xpath)
      Gets a schemaNode from the schemaNodeMap. Note: the schemaNodeMap is indexed by "normalized" xpaths (i.e., having no indexing). Since normalizing is idempotent, perhaps we normalize the path before accessing the map . . .
      Parameters:
      xpath - A string representation of an XPath
      Returns:
      SchemaNode object , or null if not found

    • setSchemaNodeReadOnly

      public void setSchemaNodeReadOnly(String xpath)
      set the isReadOnly attribute of the schemaNode specified by the given xpath to true
      Parameters:
      xpath - The new schemaNodeReadOnly value

    • getParentSchemaNode

      public SchemaNode getParentSchemaNode(String xpath)
      Gets the parent of the SchemaNode associated with a given xpath
      Parameters:
      xpath - A string representation of an XPath
      Returns:
      The parent SchemaNode

    • getParentSchemaNode

      public SchemaNode getParentSchemaNode(SchemaNode schemaNode)
      Gets the parent of a SchemaNode
      Parameters:
      schemaNode - a SchemaNode
      Returns:
      The parent SchemaNode

    • main

      public static void main(String[] args)
      The main program for the SchemaHelper class
      Parameters:
      args - The command line arguments

    • getXSDataType

      public com.sun.msv.datatype.xsd.XSDatatype getXSDataType(String dataTypeName)
      Get a named XSDatatype object used to validate input. Used only by EditorAction in the "suggest" package org.dlese.dpc.to validate the email field. this is necessary because the email field is not really specified as being of this type and therefore another way is necessary for finding a validating type.
      Parameters:
      dataTypeName - The name of a XSDatatype object
      Returns:
      The xSDataType object

    • getXSDatatypeManager

      public XSDatatypeManager getXSDatatypeManager()
      Gets the xsdDatatypeManager attribute of the SchemaHelper object.
      Returns:
      The xSDatatypeManager value

    • getGlobalDefMap

      public GlobalDefMap getGlobalDefMap()
      Gets the globalDefMap attribute of the SchemaHelper object. Currently only used by SchemaHelperTester and therefore can be eliminated when not debugging.
      Returns:
      The globalDefMap value

    • getInstanceDocument

      public org.dom4j.Document getInstanceDocument()
      Gets the instanceDocument attribute of the SchemaHelper object
      Returns:
      The instanceDocument value

    • getDefinitionMiner

      public DefinitionMiner getDefinitionMiner()
      Gets the definitionMiner attribute of the SchemaHelper object
      Returns:
      The definitionMiner value

    • checkValidValue

      public boolean checkValidValue(String typeName, String value) throws Exception
      Checks to see if a value is valid against a specified datatype. The paramName is from a request and has the form of "valueOf(/itemRecord/education/blah_1_/@url)". The paraName is used to obtain a XSDatatype.
      Parameters:
      typeName - Name of the DataType to be validated against
      value - Value to be validated
      Returns:
      true if value is valid
      Throws:
      Exception - If the value is not valid. The exception usually contains helpful information

    • getSchemaNodeMap

      public SchemaNodeMap getSchemaNodeMap()
      Gets the schemaNodeMap attribute of the SchemaHelper object
      Returns:
      The schemaNodeMap value

    • toSchemaPath

      public static String toSchemaPath(String encodedXPath)
      convert a jsp-encoded path into a normalized form for accessing schemaNodes
      Parameters:
      encodedXPath - Description of the Parameter
      Returns:
      Description of the Return Value

    • isRepeatingElement

      public boolean isRepeatingElement(String encodedXPath)
      Gets the repeatingElement attribute of the SchemaHelper object
      Parameters:
      encodedXPath - Description of the Parameter
      Returns:
      The repeatingElement value

    • isRepeatingElement

      public boolean isRepeatingElement(SchemaNode schemaNode)
      Gets the repeatingElement attribute of the SchemaHelper object
      Parameters:
      schemaNode - Description of the Parameter
      Returns:
      The repeatingElement value

    • isRepeatingElement

      public boolean isRepeatingElement(SchemaNode schemaNode, GlobalDef typeDef)
      Determines whether an instanceDocumentNode is a repeating element (i.e., it has maxOccurs > 1 and is NOT an enumerationType). Note: we pass in the dataTypeName explicitly, rather than obtain it from the schemaNode, because sometimes the Renderer is asked to render a particular schemaNode as specific type (e.g., in the case of derived Content Models) rather than the type it is declared as in the typeDefinition.
      Parameters:
      schemaNode - a wrapper to a Node in the instanceDocument
      typeDef - a DataType to be tested for isEumeration
      Returns:
      The repeatingElement value

    • isRecursiveElement

      public boolean isRecursiveElement(String encodedXPath)

    • isSingleton

      public boolean isSingleton(String xpath)
      Gets the singleton attribute of the SchemaHelper object
      Parameters:
      xpath - NOT YET DOCUMENTED
      Returns:
      The singleton value

    • isSingleton

      public boolean isSingleton(SchemaNode schemaNode)
      Returns true if this schemaNode is the only child of it's parent.
      Parameters:
      schemaNode - NOT YET DOCUMENTED
      Returns:
      The singleton value

    • isRepeatingComplexSingleton

      public boolean isRepeatingComplexSingleton(String xpath)
      Returns true if the provided path meets the requirememts for a repeating complex singleton element. Requirements are:
      • a ComplexType element
      • has a maxOccurs of more than 1
      • is the only child of it's parent element
      Parameters:
      xpath - NOT YET DOCUMENTED
      Returns:
      The repeatingComplexSingleton value

    • hasRepeatingComplexSingleton

      public boolean hasRepeatingComplexSingleton(String xpath)
      Returns true if the node at the provided path contains a Single, Complex element with maxOccurs of more than 1.
      Parameters:
      xpath - NOT YET DOCUMENTED
      Returns:
      NOT YET DOCUMENTED

    • getRepeatingComplexSingletonChildName

      public String getRepeatingComplexSingletonChildName(String xpath)
      Gets the qualified element name of the repeatingComplexSingleton child of the node specified by the provided path, or an empty string if such a child does not exist.
      Parameters:
      xpath - NOT YET DOCUMENTED
      Returns:
      The repeatingComplexSingletonChildName value

    • isAnyTypeElement

      public boolean isAnyTypeElement(String xpath)

    • isMultiChoiceElement

      public boolean isMultiChoiceElement(String encodedXPath)
      Returns true if the given path corresponds to a schemaNode that allows for multiple choice children elements.
      Parameters:
      encodedXPath - xpath corresponding to a schemaNode to be tested
      Returns:
      The multiChoiceElement value

    • isMultiChoiceElement

      public boolean isMultiChoiceElement(SchemaNode schemaNode)
      Returns true if the given schemaNode allows for multiple choice children elements.
      Parameters:
      schemaNode - schemaNode to be tested
      Returns:
      true if schemaNode has a choice compositor and has a maxOccurs value greater than 1

    • isChoiceElement

      public boolean isChoiceElement(String encodedXPath)
      Gets the choiceElement attribute of the SchemaHelper object
      Parameters:
      encodedXPath - NOT YET DOCUMENTED
      Returns:
      The choiceElement value

    • isChoiceElement

      public boolean isChoiceElement(SchemaNode schemaNode)
      Return true if this element is a member of a choice compositor.

      This is determined by the typeDefinition of the element's parent.

      Parameters:
      schemaNode - Description of the Parameter
      Returns:
      The choiceElement value

    • hasChoiceCompositor

      public boolean hasChoiceCompositor(String encodedXPath)
      NOT YET DOCUMENTED
      Parameters:
      encodedXPath - NOT YET DOCUMENTED
      Returns:
      NOT YET DOCUMENTED

    • hasCompositor

      public boolean hasCompositor(String encodedXPath)
      Returns true if the schemaNode for the specified path has a compositor.
      Parameters:
      encodedXPath - NOT YET DOCUMENTED
      Returns:
      NOT YET DOCUMENTED

    • hasChoiceCompositor

      public boolean hasChoiceCompositor(SchemaNode schemaNode)
      Returns true if the Node's type definition specifies a choice compositor
      Parameters:
      schemaNode - Description of the Parameter
      Returns:
      Description of the Return Value

    • hasSequenceCompositor

      public boolean hasSequenceCompositor(String encodedXPath)
      NOT YET DOCUMENTED
      Parameters:
      encodedXPath - NOT YET DOCUMENTED
      Returns:
      NOT YET DOCUMENTED

    • hasSequenceCompositor

      public boolean hasSequenceCompositor(SchemaNode schemaNode)
      Returns true if the Node's type definition specifies a sequence compositor
      Parameters:
      schemaNode - Description of the Parameter
      Returns:
      Description of the Return Value

    • isMultiSelect

      public boolean isMultiSelect(String encodedXPath)
      Gets the multiSelect attribute of the SchemaHelper object
      Parameters:
      encodedXPath - Description of the Parameter
      Returns:
      The multiSelect value

    • isMultiSelect

      public boolean isMultiSelect(SchemaNode schemaNode)
      Determines if the SchemaNode should rendered as a MultiSelect Element (e.g., checkboxes). Returns true IFF an element:
      • is an enumeration type
        • , AND
      • has a minOccurs of 1
        • , AND
      • maxOccurs of "unbounded"
      Parameters:
      schemaNode - Description of the Parameter
      Returns:
      The MultiSelect value

    • hasMultiSelect

      public boolean hasMultiSelect(SchemaNode schemaNode)
      multiselect iff
      • isComplex
      • hasSequenceCompositor
        • containing a single multiSelect element
      Parameters:
      schemaNode - NOT YET DOCUMENTED
      Returns:
      NOT YET DOCUMENTED

    • hasOptionalMultiSelect

      public boolean hasOptionalMultiSelect(String pathArg)
      Test a JSP-encoded pathArg for whether it refers to an element that satisfies the hasOptionalMultiSelect(SchemaNode) predicate.

      NOTE: NEVER REFERENCED

      Parameters:
      pathArg - an JSP-encoded XPath
      Returns:
      true if pathArg refers to an element that has an optionalMultiSelect child element

    • hasOptionalMultiSelect

      public boolean hasOptionalMultiSelect(SchemaNode schemaNode)
      Returns true if this element is optional and contains only a single multiSelect element. More specifically it returns true if an element:
      • isOptional
      • isComplex
      • hasSequenceCompositor
        • containing a single multiSelect element
      NOTE: NEVER REFERENCED
      Parameters:
      schemaNode - Description of the Parameter
      Returns:
      Description of the Return Value

    • hasRequiredMultiSelect

      public boolean hasRequiredMultiSelect(SchemaNode schemaNode)
      NOT YET DOCUMENTED
      Parameters:
      schemaNode - NOT YET DOCUMENTED
      Returns:
      NOT YET DOCUMENTED

    • isRequiredBranch

      public boolean isRequiredBranch(SchemaNode schemaNode)
      Returns true if the schemaNode is an element, a complexType (a branch) and is required.
      Parameters:
      schemaNode - Description of the Parameter
      Returns:
      The requiredBranch value

    • isRequiredContentElement

      public boolean isRequiredContentElement(SchemaNode schemaNode)
      Returns true if the given schemaNode must have a text value (in addition to possibly having subelements). The tricky part of this method is that we are treating "stringTextType" as required (enforcing an implicit convention used in DLESE schemas).

      NOTE: currently we are calling ANY extended element (besides stringTextType) optional. I don't even know how you would define it as required in the schema, but I'm not worrying about it for now ...

      Parameters:
      schemaNode - Description of the Parameter
      Returns:
      true if the schemaNode represents an element that must have content

    • isRequiredAttribute

      public boolean isRequiredAttribute(SchemaNode schemaNode)
      Returns true if a SchemaNode defines a required attribute.
      Parameters:
      schemaNode - Description of the Parameter
      Returns:
      The requiredAttribute value

    • isComboUnionType

      public boolean isComboUnionType(GlobalDef typeDef)
      Gets the comboUnionType attribute of the SchemaHelper object
      Parameters:
      typeDef - NOT YET DOCUMENTED
      Returns:
      The comboUnionType value

    • isEnumerationType

      public boolean isEnumerationType(GlobalDef typeDef)
      Returns true if the given typeDef represents an eumeration datatype
      Parameters:
      typeDef - Description of the Parameter
      Returns:
      The enumerationType value

    • isEnumerationType

      public boolean isEnumerationType(String typeName)
      Returns true if the typeName corresponds to datatype that represents an enumeration. Union-types are Enumerations IFF all the member types are also enumerations.
      Parameters:
      typeName - the name of a datatype defined by a schema
      Returns:
      true if the datatype specifies an enumeration

    • getChildrenOrder

      public List getChildrenOrder(String xpath)
      Returns a list of element names for the given path from the instanceDoc. Used to enforce ordering of elements having sequence compositor.
      Parameters:
      xpath - NOT YET DOCUMENTED
      Returns:
      The childrenOrder value

    • getEnumerationValues

      public List getEnumerationValues(GlobalDef globalDef, boolean getLeafValues)
      Gets the enumerationValues that are specified by the typeName. If the getLeafValues parameter is true, then human-readable values (e.g., "DLESE:" would be stripped from "DLESE:author")are returned, if possible.
      Parameters:
      globalDef - NOT YET DOCUMENTED
      getLeafValues - specifies whether human-readable values are returned
      Returns:
      The enumerationValues value, or null if the typeNode is not found.

    • getEnumerationValues

      public List getEnumerationValues(String typeName, boolean getLeafValues)
      Gets the enumerationValues attribute of the SchemaHelper object
      Parameters:
      typeName - NOT YET DOCUMENTED
      getLeafValues - NOT YET DOCUMENTED
      Returns:
      The enumerationValues value

    • getGlobalDefFromXPath

      public GlobalDef getGlobalDefFromXPath(String xpath)
      Finds a globalDef object for a given xpath. This is done by first obtaining the globalDef NAME from the SchemaNodeMap and then using the name as an index into the GlobalDefMap.
      Parameters:
      xpath - an xpath to a specific node
      Returns:
      an GlobalDef object

    • getMinimalDocument

      public org.dom4j.Document getMinimalDocument()
      Create a miminal instance document that is used as the starting point for a new document. The miminal document should contain only those elements that are required for a valid document for the current framework.
      Returns:
      The minimalDocument as a Document

    • getNewElement

      public org.dom4j.Element getNewElement(String encodedPath)
      Creates a "miminalElement" (one that contains only required elements) from the instanceDocument.
      Parameters:
      encodedPath - JSP-encoded xpath that specifies the element to create
      Returns:
      An element from the instanceDocument pruned to eliminate non-required branches.

    • getMaxOccurs

      public static int getMaxOccurs(org.dom4j.Element e)
      Utility to extract the maxOccurs attribute of the given element and returns an int equivalent. Returns default value if element does not contain maxOccurs attribute.
      Parameters:
      e - element from a xml schema
      Returns:
      The maxOccurs value as or default as int

    • getMinOccurs

      public static int getMinOccurs(org.dom4j.Element e)
      Extract the minOccurs attribute of the given element and returns an int equivalent. Returns default value if element does not contain minOccurs attribute.
      Parameters:
      e - element from a xml schema
      Returns:
      The minOccurs value as or default as int

    • encodePathIfAnyType

      public String encodePathIfAnyType(String xpath)

    • encodeAnyTypeXpath

      public String encodeAnyTypeXpath(String xpath)
      Replaces xpath having node name of "any" with a wild-card version that can actually access the any element (which is anonymous) in the XML Document.

    • decodeAnyTypeXpath

      public String decodeAnyTypeXpath(String xpath)
      Replaces xpath used to access an "anyType" node in the XML Document with a version that is known to the schema. I.e., Replaces the node-name of '*' with 'any' while preserving any indexing.

    • destroy

      public void destroy()
      Description of the Method

    • setDebug

      public static void setDebug(boolean d)
      Sets the debug attribute of the SchemaHelper class
      Parameters:
      d - The new debug value

    • setVerbose

      public static void setVerbose(boolean v)
      Sets the verbose attribute of the SchemaHelper class
      Parameters:
      v - The new verbose value

    • box

      public static void box(String s, String prefix)
      NOT YET DOCUMENTED
      Parameters:
      s - NOT YET DOCUMENTED
      prefix - NOT YET DOCUMENTED