<!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements. See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership. The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License. You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied. See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->
<html>
<body>
Defines Axiom specific extensions to the StAX API.
<p>
This package defines several extensions to the StAX API, more precisely for the
{@link javax.xml.stream.XMLStreamReader} and {@link javax.xml.stream.XMLStreamWriter} classes.
The reader or writer wishing to support the
extension MAY implement the corresponding interface directly, but a consumer MUST use
the property mechanism to get a reference to this extension interface, i.e. it MUST call
{@link javax.xml.stream.XMLStreamReader#getProperty(String)} or
{@link javax.xml.stream.XMLStreamWriter#getProperty(String)}. Each of the extension interfaces in
this package defines a constant for the property name to use.
<p>
The rationale for this requirement is that a property based approach continues to work even if the
stream implementing the extension is accessed indirectly through a proxy implementing the
{@link javax.xml.stream.XMLStreamReader} or {@link javax.xml.stream.XMLStreamWriter} interface but unaware
of the extensions defined in this package. Note that this assumes that the proxy correctly delegates calls to the
<code>getProperty</code> methods.
<p>
The property returning the extension interface MUST be available regardless of the current state of
the stream. In addition it is assumed to be immutable, i.e. its value MUST NOT not change during the
lifetime of the {@link javax.xml.stream.XMLStreamReader} or {@link javax.xml.stream.XMLStreamWriter}
implementation. For a consumer it is therefore sufficient to look up the extension once and to
continue using the obtained reference during the entire lifetime of the stream.
</body>
</html>