net.sf.saxon.functions

## Class Collection

- java.lang.Object
- - net.sf.saxon.expr.Expression
  - - net.sf.saxon.expr.FunctionCall
    - - net.sf.saxon.functions.SystemFunctionCall
      - - net.sf.saxon.functions.Collection

- All Implemented Interfaces:
    Serializable, SourceLocator, LocationProvider, SaxonLocator, Callable, InstructionInfo, Locator

      public class Collection
      extends SystemFunctionCall
      implements Callable

  Implement the fn:collection() function. This is responsible for calling the registered `CollectionURIResolver`. For the effect of the default system-supplied CollectionURIResolver, see `StandardCollectionURIResolver`
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `EMPTY_COLLECTION` URI representing a collection that is always empty, regardless of any collection URI resolver

    - ### Fields inherited from class net.sf.saxon.functions.SystemFunctionCall

      `operation`

    - ### Fields inherited from class net.sf.saxon.expr.FunctionCall

      `argument`

    - ### Fields inherited from class net.sf.saxon.expr.Expression

      `EFFECTIVE_BOOLEAN_VALUE, EVALUATE_METHOD, EVENT_FEED_METHOD, INHERITED_CONTEXT, INSPECTION_CONTEXT, ITEM_FEED_METHOD, ITERATE_METHOD, locationId, MAX_SEQUENCE_LENGTH, MAX_STRING_LENGTH, NAVIGATION_CONTEXT, NODE_VALUE_CONTEXT, PROCESS_METHOD, PUSH_SELECTION, staticProperties, UNBOUNDED_LOWER, UNBOUNDED_UPPER, W3C_CONSUMING, W3C_FREE_RANGING, W3C_GROUP_CONSUMING, W3C_MOTIONLESS, WATCH_METHOD`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Collection()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `PathMap.PathMapNodeSet` | `addToPathMap(PathMap pathMap, PathMap.PathMapNodeSet pathMapNodeSet)` Add a representation of this expression to a PathMap.
    `Sequence` | `call(XPathContext context, Sequence[] arguments)` Call the Callable.
    `void` | `checkArguments(ExpressionVisitor visitor)` Method called during static type checking
    `int` | `computeSpecialProperties()` Determine the special properties of this expression.
    `static SequenceIterator` | `getResolverResults(SequenceIterator iter, String baseURI, XPathContext context, SourceLocator locator)` Return the results of iterating over the results returned by the CollectionURIResolver.
    `String` | `getStaticBaseURI()`
    `SequenceIterator<Item>` | `iterate(XPathContext context)` Iterate over the contents of the collection
    `Expression` | `preEvaluate(ExpressionVisitor visitor)` preEvaluate: this method suppresses compile-time evaluation by doing nothing

    - ### Methods inherited from class net.sf.saxon.functions.SystemFunctionCall

      `addContextDocumentArgument, addDocToPathMap, bindStaticContext, computeCardinality, copy, equalOrNull, equals, getContextNode, getConvertingCallable, getDefaultArgumentNode, getDetails, getErrorCodeForTypeErrors, getFunctionItemType, getImplementationMethod, getItemType, getOperation, getRequiredType, iterateSubExpressionInfo, makeSystemFunction, optimize, setDetails, useContextItemAsDefault`

    - ### Methods inherited from class net.sf.saxon.expr.FunctionCall

      `addExternalFunctionCallToPathMap, checkArgumentCount, explain, getArguments, getDisplayName, getExpressionName, getFunctionName, getNumberOfArguments, hashCode, iterateSubExpressions, promote, replaceSubExpression, setArguments, setFunctionName, simplify, simplifyArguments, toString, typeCheck`

    - ### Methods inherited from class net.sf.saxon.expr.Expression

      `adoptChildExpression, checkForUpdatingSubexpressions, checkPermittedContents, computeDependencies, computeStaticProperties, doPromotion, dynamicError, effectiveBooleanValue, evaluateAsString, evaluateItem, evaluatePendingUpdates, explain, getCardinality, getColumnNumber, getColumnNumber, getConstructType, getContainer, getDependencies, getEvaluationMethod, getExecutable, getExpressionCompiler, getHostLanguage, getIntegerBounds, getIntrinsicDependencies, getLineNumber, getLineNumber, getLocationId, getLocationProvider, getObjectName, getProperties, getProperty, getPublicId, getSlotsUsed, getSpecialProperties, getStreamability, getStreamingAdjunct, getSystemId, getSystemId, hasVariableBinding, implementsStaticTypeCheck, isSubtreeExpression, isUpdatingExpression, isVacuousExpression, iterateEvents, markTailFunctionCalls, process, resetLocalStaticProperties, setContainer, setEvaluationMethod, setFiltered, setFlattened, setLocationId, staticTypeCheck, suppressValidation, toPattern, toStreamingPattern, typeError`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### EMPTY_COLLECTION

          public static String EMPTY_COLLECTION

      URI representing a collection that is always empty, regardless of any collection URI resolver

  - ### Constructor Detail

    - #### Collection

          public Collection()

  - ### Method Detail

    - #### getStaticBaseURI

          public String getStaticBaseURI()

    - #### checkArguments

          public void checkArguments(ExpressionVisitor visitor)
                              throws XPathException

      Description copied from class: `SystemFunctionCall`
      Method called during static type checking
      Overrides:
        `checkArguments` in class `SystemFunctionCall`
      Parameters:
        `visitor` - the expression visitor
      Throws:
        `XPathException` - if the arguments are incorrect

    - #### computeSpecialProperties

          public int computeSpecialProperties()

      Description copied from class: `SystemFunctionCall`
      Determine the special properties of this expression. The general rule is that a system function call is non-creative if its return type is atomic, or if all its arguments are non-creative. This is overridden for the generate-id() function, which is considered creative if its operand is creative (because the result depends on the identity of the operand)
      Overrides:
        `computeSpecialProperties` in class `SystemFunctionCall`
      Returns:
        the special properties, as a bit-significant integer

    - #### preEvaluate

          public Expression preEvaluate(ExpressionVisitor visitor)

      preEvaluate: this method suppresses compile-time evaluation by doing nothing
      Overrides:
        `preEvaluate` in class `FunctionCall`
      Parameters:
        `visitor` - an expression visitor
      Returns:
        the result of the early evaluation, or the original expression, or potentially a simplified expression

    - #### addToPathMap

          public PathMap.PathMapNodeSet addToPathMap(PathMap pathMap,
                                            PathMap.PathMapNodeSet pathMapNodeSet)

      Add a representation of this expression to a PathMap. The PathMap captures a map of the nodes visited by an expression in a source tree.
      Overrides:
        `addToPathMap` in class `Expression`
      Parameters:
        `pathMap` - the PathMap to which the expression should be added
        `pathMapNodeSet` - the PathMapNodeSet to which the paths embodied in this expression should be added
      Returns:
        the pathMapNode representing the focus established by this expression, in the case where this expression is the first operand of a path expression or filter expression

    - #### iterate

          public SequenceIterator<Item> iterate(XPathContext context)
                                         throws XPathException

      Iterate over the contents of the collection
      Overrides:
        `iterate` in class `Expression`
      Parameters:
        `context` - the dynamic context
      Returns:
        an iterator, whose items will always be nodes (typically but not necessarily document nodes)
      Throws:
        `XPathException`

    - #### getResolverResults

          public static SequenceIterator getResolverResults(SequenceIterator iter,
                                            String baseURI,
                                            XPathContext context,
                                            SourceLocator locator)

      Return the results of iterating over the results returned by the CollectionURIResolver.

      Note, this method is called by generated code

      Parameters:
        `iter` - iterator over the results of the CollectionURIResolver
        `baseURI` - the base URI
        `context` - the dynamic context
        `locator` - location of the instruction
      Returns:
        an iterator over the documents in the collection.

    - #### call

          public Sequence call(XPathContext context,
                      Sequence[] arguments)
                        throws XPathException

      Description copied from interface: `Callable`
      Call the Callable.
      Specified by:
        `call` in interface `Callable`
      Parameters:
        `context` - the dynamic evaluation context
        `arguments` - the values of the arguments, supplied as Sequences.

        Generally it is advisable, if calling iterate() to process a supplied sequence, to call it only once; if the value is required more than once, it should first be converted to a `GroundedValue` by calling the utility methd SequenceTool.toGroundedValue().

        If the expected value is a single item, the item should be obtained by calling Sequence.head(): it cannot be assumed that the item will be passed as an instance of `Item` or `AtomicValue`.

        It is the caller's responsibility to perform any type conversions required to convert arguments to the type expected by the callee. An exception is where this Callable is explicitly an argument-converting wrapper around the original Callable.

      Returns:
        the result of the evaluation, in the form of a Sequence. It is the responsibility of the callee to ensure that the type of result conforms to the expected result type.
      Throws:
        `XPathException` - if a dynamic error occurs during the evaluation of the expression

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