| <!-- |
| ~ 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> |
