com.saxonica.schema

## Class ModelGroupParticle

- java.lang.Object
- - com.saxonica.schema.SchemaStructure
  - - com.saxonica.schema.SimpleComponentReference
    - - com.saxonica.schema.Particle
      - - com.saxonica.schema.ModelGroupParticle

- All Implemented Interfaces:
    ComponentReference, UserSchemaComponent, Serializable, SourceLocator, SchemaComponent
  Direct Known Subclasses:
    Edge.MaxOccursParticle

      public class ModelGroupParticle
      extends Particle
      implements ComponentReference

  A reference within the content model of a complex type to a Model Group Definition. Corresponds to a non-top-level xs:group element in a schema document, that is, an xs:group element with a ref attribute.

  There is no direct equivalent of a ModelGroupParticle in the W3C schema component model, because in that model the structure of a complex type is always fully expanded: that is, any group references are replaced by the content of the group they refer to. This model retains group references to allow late binding and redefinition. However, methods are provided on the `ModelGroup` class to give a view of the content model in which the group references disappear.

  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from class com.saxonica.schema.Particle

      `UNBOUNDED`

    - ### Fields inherited from class com.saxonica.schema.SimpleComponentReference

      `nameCode, symbolSpace, target`

    - ### Fields inherited from interface net.sf.saxon.type.SchemaComponent

      `COMPONENT_FUNCTION_TYPE, FIXED_UP, INCOMPLETE, INVALID, UNVALIDATED, VALIDATED, VALIDATING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ModelGroupParticle(EnterpriseConfiguration config, SourceLocator locator)` Creates a new Group reference

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `compile(SchemaCompiler compiler)` Compile a particle
    `boolean` | `containsElementWildcard()` Ask whether the particle contains an element wildcard
    `void` | `elaborate(SchemaCompiler compiler)` Elaborate the schema component: after reloading a serialized schema component model, this expands the component with derived information needed during validation episodes.
    `boolean` | `fixup(SchemaCompiler compiler)` Fix up references to other elements in the schema.
    `void` | `gatherAllPermittedElements(IntHashSet result, boolean ignoreWildcards)` Find the set of all element particles allowed within the content model of this particle, identified by their integer fingerprints.
    `int` | `getElementParticleCardinality(int fingerprint)` Find an element particle within this complex type definition having a given element name (identified by fingerprint), and return the cardinality associated with that element particle, that is, the number of times the element can occur within this complex type.
    `SchemaType` | `getElementParticleType(int fingerprint)` Find an element particle within this complex type definition having a given element name (identified by fingerprint), and return the schema type associated with that element particle.
    `ModelGroup` | `getGroup()`
    `int` | `getSymbolSpace()` Get the symbol space of the target of this reference
    `SchemaComponent` | `getTarget()` Returns the group that this group object is a reference to.
    `Term` | `getTerm()` Get the term corresponding to this particle
    `boolean` | `isEmptiable()` Determine if empty content is allowed
    `boolean` | `isPointless(ModelGroup container)` Test whether the particle is pointless, as described in XML Schema Part 1 Schema Component Constraint: Particle Valid (Restriction)
    `boolean` | `isResolved()` Determine whether this reference has been resolved
    `void` | `lookForCycles(Stack references, SchemaCompiler compiler)` This method is called to look for cycles.
    `void` | `markVulnerableSubParticles()` Mark the vulnerable subParticles of this particle
    `void` | `serializeParticle(SchemaModelSerializer serializer)` Serialize the schema component as a particle
    `void` | `tryToResolve(SchemaCompiler compiler)` Attempt to resolved this reference using the groups defined in a given schema.
    `boolean` | `validate(SchemaCompiler compiler)` Checks the validity of this Schema definition.

    - ### Methods inherited from class com.saxonica.schema.Particle

      `computeParticleCardinality, getComponentAsFunction, getMaxOccurs, getMinOccurs, isVulnerable, setMaxOccurs, setMinOccurs, setVulnerable`

    - ### Methods inherited from class com.saxonica.schema.SimpleComponentReference

      `getFingerprint, getNameCode, setNameCode, setTarget`

    - ### Methods inherited from class com.saxonica.schema.SchemaStructure

      `getColumnNumber, getConfiguration, getFixupStatus, getLineNumber, getPublicId, getRedefinitionLevel, getSchemaDocumentURI, getSystemId, getValidationStatus, makeXPathExpressionPropertyRecord, setConfiguration, setFixupStatus, setLineNumber, setLocator, setRedefinitionLevel, setSchemaDocumentURI, setSystemId, setValidationStatus`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface com.saxonica.schema.ComponentReference

      `getConfiguration, getFingerprint`

    - ### Methods inherited from interface javax.xml.transform.SourceLocator

      `getColumnNumber, getLineNumber, getPublicId, getSystemId`

    - ### Methods inherited from interface net.sf.saxon.type.SchemaComponent

      `getRedefinitionLevel, getValidationStatus`

- - ### Constructor Detail

    - #### ModelGroupParticle

          public ModelGroupParticle(EnterpriseConfiguration config,
                            SourceLocator locator)

      Creates a new Group reference
      Parameters:
        `config` - the Configuration to which this Group belongs
        `locator` - the location of the corresponding declaration in the source schema document

  - ### Method Detail

    - #### isResolved

          public boolean isResolved()

      Determine whether this reference has been resolved
      Specified by:
        `isResolved` in interface `ComponentReference`
      Overrides:
        `isResolved` in class `SimpleComponentReference`
      Returns:
        true if the reference has been resolved to a schema component

    - #### getGroup

          public ModelGroup getGroup()
                              throws UnresolvedReferenceException

      Throws:
        `UnresolvedReferenceException`

    - #### getSymbolSpace

          public int getSymbolSpace()

      Get the symbol space of the target of this reference
      Specified by:
        `getSymbolSpace` in interface `ComponentReference`
      Overrides:
        `getSymbolSpace` in class `SimpleComponentReference`
      Returns:
        an integer code identifying the symbol space

    - #### isEmptiable

          public boolean isEmptiable()
                              throws UnresolvedReferenceException

      Determine if empty content is allowed
      Specified by:
        `isEmptiable` in class `Particle`
      Returns:
        true if the particle matches empty content
      Throws:
        `UnresolvedReferenceException` - if the schema contains an unresolved reference to a required component

    - #### fixup

          public boolean fixup(SchemaCompiler compiler)
                        throws SchemaException

      Fix up references to other elements in the schema.
      Specified by:
        `fixup` in interface `UserSchemaComponent`
      Specified by:
        `fixup` in class `Particle`
      Parameters:
        `compiler` - the schema compiler
      Returns:
        true if successful
      Throws:
        `SchemaException` - if a fatal error occurs

    - #### lookForCycles

          public void lookForCycles(Stack references,
                           SchemaCompiler compiler)
                             throws SchemaException,
                                    UnresolvedReferenceException

      This method is called to look for cycles. The object implementing this method is required (a) to raise an exception if the object itself appears in the list of references, (b) to add itself to the list of references, and (c) to call the lookForCycles method on all the objects that it references.
      Specified by:
        `lookForCycles` in interface `UserSchemaComponent`
      Overrides:
        `lookForCycles` in class `SchemaStructure`
      Parameters:
        `references` - A list of objects that contain direct or indirect references to this object, and that must therefore not be referred to from this object.
        `compiler` - The schema compiler
      Throws:
        `SchemaException`
        `UnresolvedReferenceException`

    - #### getTarget

          public SchemaComponent getTarget()
                                    throws UnresolvedReferenceException

      Returns the group that this group object is a reference to. Note this method doesn't bind irrevocably to the target group declaration, because this may change following a redefine.
      Specified by:
        `getTarget` in interface `ComponentReference`
      Overrides:
        `getTarget` in class `SimpleComponentReference`
      Returns:
        the schema component if the reference has been resolved.
      Throws:
        `UnresolvedReferenceException` - if the reference has not been resolved. Note that this is an unchecked exception.

    - #### tryToResolve

          public void tryToResolve(SchemaCompiler compiler)

      Attempt to resolved this reference using the groups defined in a given schema. No error results if the reference cannot be resolved.
      Specified by:
        `tryToResolve` in interface `ComponentReference`
      Overrides:
        `tryToResolve` in class `SimpleComponentReference`
      Parameters:
        `compiler` - The compiler being used to compile the referring component. This is assumed to know about the schema containing the candidate target components for the reference. If null, the schema containing the reference is used.

    - #### isPointless

          public boolean isPointless(ModelGroup container)

      Test whether the particle is pointless, as described in XML Schema Part 1 Schema Component Constraint: Particle Valid (Restriction)
      Specified by:
        `isPointless` in class `Particle`
      Parameters:
        `container` - the model group containing this particle; null if there is no containing model group
      Returns:
        true if the particle is pointless (for example, a sequence of one item)

    - #### getElementParticleType

          public SchemaType getElementParticleType(int fingerprint)

      Find an element particle within this complex type definition having a given element name (identified by fingerprint), and return the schema type associated with that element particle. If there is no such particle, return null. If the fingerprint matches an element wildcard, return the type of the global element declaration with the given name if one exists, or AnyType if none exists and lax validation is permitted by the wildcard.
      Specified by:
        `getElementParticleType` in class `Particle`
      Parameters:
        `fingerprint` - Identifies the name of the child element within this content model
      Returns:
        the type of the element identified by the given name fingerprint. The consistency rule "Element Declarations Consistent" ensures that if there are multiple matching declarations, they have consistent types

    - #### getElementParticleCardinality

          public int getElementParticleCardinality(int fingerprint)

      Find an element particle within this complex type definition having a given element name (identified by fingerprint), and return the cardinality associated with that element particle, that is, the number of times the element can occur within this complex type. The value is one of `StaticProperty.EXACTLY_ONE`, `StaticProperty.ALLOWS_ZERO_OR_ONE`, `StaticProperty.ALLOWS_ZERO_OR_MORE`, `StaticProperty.ALLOWS_ONE_OR_MORE`, If there is no such particle, return `StaticProperty.ALLOWS_ZERO`.
      Specified by:
        `getElementParticleCardinality` in class `Particle`
      Parameters:
        `fingerprint` - Identifies the name of the child element within this content model
      Returns:
        the computed cardinality of this child element within the complex type

    - #### containsElementWildcard

          public boolean containsElementWildcard()

      Ask whether the particle contains an element wildcard
      Specified by:
        `containsElementWildcard` in class `Particle`
      Returns:
        true if the particle is an element wildcard, or contains one

    - #### gatherAllPermittedElements

          public void gatherAllPermittedElements(IntHashSet result,
                                        boolean ignoreWildcards)
                                          throws SchemaException

      Find the set of all element particles allowed within the content model of this particle, identified by their integer fingerprints. Ignore wildcards.
      Specified by:
        `gatherAllPermittedElements` in class `Particle`
      Parameters:
        `result` - an initially-empty integer set in which the results are accumulated
        `ignoreWildcards` - true if wildcard particles are to be ignored. If false, the resulting set will include the value -1 if wildcards are present in the content model
      Throws:
        `SchemaException` - if an error is found in the schema

    - #### markVulnerableSubParticles

          public void markVulnerableSubParticles()

      Mark the vulnerable subParticles of this particle
      Overrides:
        `markVulnerableSubParticles` in class `Particle`

    - #### validate

          public boolean validate(SchemaCompiler compiler)
                           throws SchemaException

      Checks the validity of this Schema definition.
      Specified by:
        `validate` in interface `UserSchemaComponent`
      Specified by:
        `validate` in class `Particle`
      Parameters:
        `compiler` - the schema compiler
      Returns:
        true if validation succeeded, false if errors were found.
      Throws:
        `SchemaException`

    - #### compile

          public void compile(SchemaCompiler compiler)
                       throws SchemaException

      Compile a particle
      Specified by:
        `compile` in class `Particle`
      Parameters:
        `compiler` - the schema compmiler
      Throws:
        `SchemaException` - if a fatal error occurs

    - #### getTerm

          public Term getTerm()

      Get the term corresponding to this particle
      Specified by:
        `getTerm` in class `Particle`
      Returns:
        the corresponding term

    - #### elaborate

          public void elaborate(SchemaCompiler compiler)
                         throws SchemaException

      Elaborate the schema component: after reloading a serialized schema component model, this expands the component with derived information needed during validation episodes. The model is assumed to be valid.
      Specified by:
        `elaborate` in interface `UserSchemaComponent`
      Overrides:
        `elaborate` in class `SchemaStructure`
      Parameters:
        `compiler` - the schema compiler
      Throws:
        `SchemaException` - if the schema is found to be invalid

    - #### serializeParticle

          public void serializeParticle(SchemaModelSerializer serializer)
                                 throws XPathException

      Serialize the schema component as a particle
      Specified by:
        `serializeParticle` in class `Particle`
      Parameters:
        `serializer` - the object responsible for serialization
      Throws:
        `XPathException` - if serialization fails

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.