com.saxonica.schema

## Class Particle

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

- All Implemented Interfaces:
    ComponentReference, UserSchemaComponent, Serializable, SourceLocator, SchemaComponent
  Direct Known Subclasses:
    ElementParticle, ElementWildcard, ModelGroupParticle

      public abstract class Particle
      extends SimpleComponentReference
      implements UserSchemaComponent

  Represents a Particle as defined by XML Schema. A particle is a component of a content model, consisting of a term and a permitted cardinality range. The term may be an element declaration, a wildcard, or a model group. To allow for content models that have not been fully resolved, we also allow a model group reference as a particle (that is, a reference to a named model group definition).
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `UNBOUNDED` A constant to represent an UNBOUNDED number of occurrences

    - ### 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
    `Particle()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `compile(SchemaCompiler compiler)` Compile a particle
    `static int` | `computeParticleCardinality(int minOccurs, int maxOccurs)` Compute an XPath cardinality (e.g.
    `abstract boolean` | `containsElementWildcard()` Ask whether the particle contains an element wildcard
    `abstract boolean` | `fixup(SchemaCompiler compiler)` Check references from this component to other components
    `abstract 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.
    `FunctionItem` | `getComponentAsFunction()` Get the schema component in the form of a function item.
    `abstract 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.
    `abstract SchemaType` | `getElementParticleType(int fingerprint)` Find an element particle within this part of a content model having a given element name (identified by fingerprint), and return the schema type associated with that element particle.
    `int` | `getMaxOccurs()` Returns the maximum number of occurrences that this Particle may appear in the containing content model
    `int` | `getMinOccurs()` Returns the minimum number of occurrences that this Particle must appear in the containing content model
    `abstract Term` | `getTerm()` Get the term corresponding to this particle
    `abstract boolean` | `isEmptiable()` Determine if empty content is allowed
    `abstract boolean` | `isPointless(ModelGroup container)` Test whether the particle is pointless, as described in XML Schema Part 1 Schema Component Constraint: Particle Valid (Restriction)
    `boolean` | `isVulnerable()` Ask whether the particle is vulnerable.
    `void` | `markVulnerableSubParticles()` Mark the vulnerable subParticles of this particle
    `abstract void` | `serializeParticle(SchemaModelSerializer serializer)` Serialize this particle to an XML Schema Component Model file
    `void` | `setMaxOccurs(int maxOccurs)` Sets the maximum number of occurrences for this Particle within the containing content model
    `void` | `setMinOccurs(int minOccurs)` Sets the minimum number of occurrences for this Particle within the containing content model
    `void` | `setVulnerable(boolean vulnerable)` Mark the particle as being (or not being) vulnerable.
    `abstract boolean` | `validate(SchemaCompiler compiler)` Check the validity (consistency) of this element definition.

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

      `getFingerprint, getNameCode, getSymbolSpace, getTarget, isResolved, setNameCode, setTarget, tryToResolve`

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

      `elaborate, getColumnNumber, getConfiguration, getFixupStatus, getLineNumber, getPublicId, getRedefinitionLevel, getSchemaDocumentURI, getSystemId, getValidationStatus, lookForCycles, 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.UserSchemaComponent

      `elaborate, lookForCycles`

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

      `getRedefinitionLevel, getValidationStatus`

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

      `getConfiguration`

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

      `getColumnNumber, getLineNumber, getPublicId, getSystemId`

- - ### Field Detail

    - #### UNBOUNDED

          public static final int UNBOUNDED

      A constant to represent an UNBOUNDED number of occurrences
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Particle

          public Particle()

  - ### Method Detail

    - #### getMaxOccurs

          public final int getMaxOccurs()

      Returns the maximum number of occurrences that this Particle may appear in the containing content model
      Returns:
        the maximum number of occurrences that this Particle may appear. A negative (n < 0) value indicates that the value is unspecified (ie. unbounded).

    - #### getMinOccurs

          public final int getMinOccurs()

      Returns the minimum number of occurrences that this Particle must appear in the containing content model
      Returns:
        the minimum number of occurrences that this Particle must appear A negative (n < 0) value indicates that the value is unspecified.

    - #### setMaxOccurs

          public final void setMaxOccurs(int maxOccurs)

      Sets the maximum number of occurrences for this Particle within the containing content model
      Parameters:
        `maxOccurs` - the maximum number of occurrences for this Particle, or -1 to indicate that the maximum is unbounded

    - #### setMinOccurs

          public final void setMinOccurs(int minOccurs)

      Sets the minimum number of occurrences for this Particle within the containing content model
      Parameters:
        `minOccurs` - the minimum number of occurrences for this Particle

    - #### getTerm

          public abstract Term getTerm()

      Get the term corresponding to this particle
      Returns:
        the corresponding term

    - #### setVulnerable

          public final void setVulnerable(boolean vulnerable)

      Mark the particle as being (or not being) vulnerable.
      Parameters:
        `vulnerable` - true if the particle is vulnerable. A particle is vulnerable if (a) it is contained in a particle that allows repetition, and (b) everything both before and after it in its enclosing particle is optional, that is, the input it accepts may be all that its enclosing particle accepts.

    - #### markVulnerableSubParticles

          public void markVulnerableSubParticles()

      Mark the vulnerable subParticles of this particle

    - #### isVulnerable

          public final boolean isVulnerable()

      Ask whether the particle is vulnerable.
      Returns:
        true if the particule is marked as vulnerable. A particle is vulnerable if (a) it is contained in a particle that allows repetition, and (b) everything both before and after it in its enclosing particle is optional, that is, the input it accepts may be all that its enclosing particle accepts. The significance of this concept arises when compiling finite state machines with counters; counters are simply not used in the case of a content model like (a(2,4))(3,5); marking the ElementParticle a as vulnerable suppresses the use of counters. Example: MS tests, particlesT014

    - #### computeParticleCardinality

          public static int computeParticleCardinality(int minOccurs,
                                       int maxOccurs)

      Compute an XPath cardinality (e.g. ONE_OR_MORE) from an XML Schema cardinality
      Parameters:
        `minOccurs` - Minimum occurrences
        `maxOccurs` - Maximum occurrences (-1 = unbounded)
      Returns:
        The XPath cardinality

    - #### containsElementWildcard

          public abstract boolean containsElementWildcard()

      Ask whether the particle contains an element wildcard
      Returns:
        true if the particle is an element wildcard, or contains one

    - #### gatherAllPermittedElements

          public abstract 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.
      Parameters:
        `result` - an initially-empty integer set in which the results are accumulated
        `ignoreWildcards` - if true, wildcards are ignored. If false, the result will be an integer set containing the value -1, meaning that it is not possible to enumerate the elements that can appear in the content.
      Throws:
        `SchemaException` - if an error is found in the schema

    - #### getElementParticleCardinality

          public abstract 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`.
      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

    - #### isEmptiable

          public abstract boolean isEmptiable()
                                       throws UnresolvedReferenceException

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

    - #### getElementParticleType

          public abstract SchemaType getElementParticleType(int fingerprint)

      Find an element particle within this part of a content model 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.
      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

    - #### fixup

          public abstract boolean fixup(SchemaCompiler compiler)
                                 throws SchemaException,
                                        UnresolvedReferenceException

      Check references from this component to other components
      Specified by:
        `fixup` in interface `UserSchemaComponent`
      Overrides:
        `fixup` in class `SchemaStructure`
      Parameters:
        `compiler` - is used for reporting errors
      Returns:
        true if all is well, false if errors found
      Throws:
        `SchemaException`
        `UnresolvedReferenceException`

    - #### validate

          public abstract boolean validate(SchemaCompiler compiler)
                                    throws SchemaException

      Check the validity (consistency) of this element definition.
      Specified by:
        `validate` in interface `UserSchemaComponent`
      Parameters:
        `compiler` - the schema compiler
      Returns:
        true if validation succeeded, false if errors were found.
      Throws:
        `SchemaException` - if an error is found and the error listener decides that the error is fatal

    - #### compile

          public abstract void compile(SchemaCompiler compiler)
                                throws SchemaException

      Compile a particle
      Parameters:
        `compiler` - the schema compiler
      Throws:
        `SchemaException` - if a fatal error occurs

    - #### isPointless

          public abstract boolean isPointless(ModelGroup container)

      Test whether the particle is pointless, as described in XML Schema Part 1 Schema Component Constraint: Particle Valid (Restriction)
      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)

    - #### serializeParticle

          public abstract void serializeParticle(SchemaModelSerializer serializer)
                                          throws XPathException

      Serialize this particle to an XML Schema Component Model file
      Parameters:
        `serializer` - the object responsible for serialization
      Throws:
        `XPathException` - if serialization fails

    - #### getComponentAsFunction

          public FunctionItem getComponentAsFunction()

      Description copied from interface: `SchemaComponent`
      Get the schema component in the form of a function item. This allows schema information to be made visible to XSLT or XQuery code. The function makes available the contents of the schema component as defined in the XSD specification. The function takes a string as argument representing a property name, and returns the corresponding property of the schema component. There is also a property "class" which returns the kind of schema component, for example "Attribute Declaration".
      Specified by:
        `getComponentAsFunction` in interface `SchemaComponent`
      Returns:
        the schema component represented as a function from property names to property values.

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