# Package net.sf.saxon.s9api

This package provides Saxon's preferred Java API for XSLT, XQuery, XPath, and XML Schema processing. The interface is designed to hide as much as possible of the detail of the implementation. However, the API architecture faithfully reflects the internal architecture of the Saxon product, unlike standard APIs such as JAXP and XQJ which in many cases force compromises in the design and performance of the application.

An application starts by loading a `Processor`, which allows configuration options to be set. As far as possible, an application should instantiate a single `Processor`.

The interfaces for XSLT, XQuery, and XPath processing all follow the same pattern. There is a three-stage execution model: first a compiler is created using a factory method in the `Processor` object. The compiler holds compile-time options and the static context information. Then the compiler's `compile()` method is called to create an executable, a representation of the compiled stylesheet, query, or expression. This is thread-safe and immutable once created. To run the query or transformation, first call the `load()` method to create a run-time object called variously an `XsltTransformer`, `XQueryEvaluator`, or `XPathSelector`. This holds run-time context information such as parameter settings and the initial context node; the object is therefore not shareable and should only be run in a single thread; indeed it should normally only be used once. This object also provides methods allowing the transformation or query to be executed.

In Saxon-EE the `Processor` owns a `SchemaManager` that holds the cache of schema components and can be used to load new schema components from source schema documents. It can also be used to create a `SchemaValidator`, which in turn is used to validate instance documents.

Source documents can be constructed using a `DocumentBuilder`, which holds all the options and parameters to control document building.

The output of a transformation, or of any other process that generates an XML tree, can be sent to a `Destination`. There are a number of implementations of this interface, including a `Serializer` which translates the XML document tree into lexical XML form.

There are classes to represent the objects of the XDM data model, including `XdmValue`, `XdmItem`, `XdmNode`, and `XdmAtomicValue`. These can be manipulated using methods based on the Java 8 streams processing model: for details see package `net.sf.saxon.s9api.streams`.

- Interface Summary
  Interface | Description
  --- | ---
  Action | A completely general functional interface for functions that take no arguments, return void, and potentially throw a `SaxonApiException`.
  BuildingContentHandler | A SAX `ContentHandler` that builds a Saxon tree, and allows the node at the root of the tree to be retrieved on completion.
  BuildingStreamWriter | A BuildingStreamWriter allows a document to be constructed by calling the methods defined in the `XMLStreamWriter` interface; after the document has been constructed, its root node may be retrieved by calling the `getDocumentNode()` method.
  Destination | A `Destination` represents a place where XDM values can be sent.
  ExtensionFunction | This is an interface for simple external/extension functions.
  Location | Saxon interface to represent a location, typically the location of an expression within a query or stylesheet.
  MessageListener | A user-written implementation of the MessageListener interface may be registered with the XsltTransformer to receive notification of xsl:message output.
  MessageListener2 | A user-written implementation of the MessageListener interface may be registered with the XsltTransformer to receive notification of xsl:message output.
  Push | An interface designed for applications to generate XML documents by issuing events.
  Push.Container | The `Container` interface represents a document node or element node under construction; there are concrete subclasses representing document nodes and element nodes respectively.
  Push.Document | A `Push.Container` representing a document node.
  Push.Element | A `Push.Container` representing an element node.
  StaticError | The StaticError interface is retained in Saxon 10.0 as a marker interface so that the methods `XsltCompiler.setErrorList(List)` and `XQueryCompiler.setErrorList(List)` continue to function.
  XmlProcessingError | The XmlProcessingError class contains information about an error detected during compilation or execution of a stylesheet, query, XPath expression, or schema

- Class Summary
  Class | Description
  --- | ---
  AbstractDestination | An abstract class providing reusable code for implementing the `Destination` interface}
  BuildingStreamWriterImpl | This class is an implementation of `XMLStreamWriter`, allowing a document to be constructed by means of a series of XMLStreamWriter method calls such as writeStartElement(), writeAttribute(), writeCharacters(), and writeEndElement().
  DestinationHelper | A helper class for implementing the `Destination` interface
  DocumentBuilder | A document builder holds properties controlling how a Saxon document tree should be built, and provides methods to invoke the tree construction.
  DOMDestination | This class represents a Destination (for example, the destination of the output of a transformation) in which the results are written to a newly constructed DOM tree in memory.
  ItemType | An item type, as defined in the XPath/XQuery specifications.
  ItemTypeFactory | This class is used for creating ItemType objects.
  NullDestination | A NullDestination is a Destination that discards all output sent to it.
  Processor | The `Processor` class serves three purposes: it allows global Saxon configuration options to be set; it acts as a factory for generating XQuery, XPath, and XSLT compilers; and it owns certain shared resources such as the Saxon NamePool and compiled schemas.
  QName | The QName class represents an instance of xs:QName, as defined in the XPath 2.0 data model.
  RawDestination | An `RawDestination` is a `Destination` that accepts a sequence output by a stylesheet or query and returns it directly as an `XdmValue`, without constructing an XML tree, and without serialization.
  SAXDestination | This class represents a `Destination` (for example, the destination of the output of a transformation) in which events representing the XML document are sent to a user-supplied SAX2 `ContentHandler`, as if the `ContentHandler` were receiving the document directly from an XML parser.
  SchemaManager | The SchemaManager is used to load schema documents, and to set options for the way in which they are loaded.
  SchemaValidator | A `SchemaValidator` is an object that is used for validating instance documents against a schema.
  SequenceType | A SequenceType is the combination of an ItemType and an OccurrenceIndicator
  Serializer | A `Serializer` takes a tree representation of XML and turns it into lexical XML markup.
  TeeDestination | A TeeDestination allows writing to two destinations at once.
  WhitespaceStrippingPolicy | WhitespaceStrippingPolicy is class defining the possible policies for handling whitespace text nodes in a source document.
  XdmArray | An array in the XDM data model.
  XdmAtomicValue | The class XdmAtomicValue represents an item in an XPath 2.0 sequence that is an atomic value.
  XdmDestination | An `XdmDestination` is a `Destination` in which an `XdmNode` is constructed to hold the output of a query or transformation: that is, a tree using Saxon's implementation of the XDM data model
  XdmEmptySequence | The class `XdmEmptySequence` represents an empty sequence in the XDM Data Model.
  XdmExternalObject | The class XdmExternalObject represents an XDM item that wraps an external (Java or .NET) object.
  XdmFunctionItem | The class XdmFunctionItem represents a function item
  XdmItem | The class XdmItem represents an item in a sequence, as defined by the XDM data model.
  XdmMap | A map in the XDM data model.
  XdmNode | This class represents a node in the XDM data model.
  XdmSequenceIterator<T extends XdmItem> | An iterator over an XPath sequence.
  XdmValue | A value in the XDM data model.
  XPathCompiler | An `XPathCompiler` object allows XPath queries to be compiled.
  XPathExecutable | An XPathExecutable represents the compiled form of an XPath expression.
  XPathSelector | An XPathSelector represents a compiled and loaded XPath expression ready for execution.
  XQueryCompiler | An `XQueryCompiler` object allows XQuery 1.0 queries to be compiled.
  XQueryEvaluator | An `XQueryEvaluator` represents a compiled and loaded query ready for execution.
  XQueryExecutable | An XQueryExecutable represents the compiled form of a query.
  Xslt30Transformer | An `Xslt30Transformer` represents a compiled and loaded stylesheet ready for execution.
  XsltCompiler | An XsltCompiler object allows XSLT 2.0 and XSLT 3.0 stylesheets to be compiled.
  XsltExecutable | An XsltExecutable represents the compiled form of a stylesheet.
  XsltPackage | An XsltPackage object represents the result of compiling an XSLT 3.0 package, as represented by an XML document containing an `xsl:package` element.
  XsltTransformer | An `XsltTransformer` represents a compiled and loaded stylesheet ready for execution.

- Enum Summary
  Enum | Description
  --- | ---
  Axis | This is an enumeration class containing constants representing the thirteen XPath axes
  HostLanguage | Identifies a host language in which XPath expressions appear.
  OccurrenceIndicator | Represents one of the possible occurrence indicators in a SequenceType.
  Serializer.Property | Enumeration class defining the permitted serialization properties
  UnprefixedElementMatchingPolicy | An enumeration defining possible strategies for resolving unprefixed element names appearing as name tests in the steps of a path expression or XSLT match pattern
  ValidationMode | Enumeration class defining different schema validation (or construction) modes
  XdmNodeKind | Enumeration class defining the seven kinds of node defined in the XDM model

- Exception Summary
  Exception | Description
  --- | ---
  SaxonApiException | An exception thrown by the Saxon s9api API.
  SaxonApiUncheckedException | An unchecked exception thrown by the Saxon API.