This is an automated email from the ASF dual-hosted git repository.
veithen pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ws-axiom.git
The following commit(s) were added to refs/heads/master by this push:
new bbcda6cb9 Extract StAX-independence principle from roadmap into ADR
0003
bbcda6cb9 is described below
commit bbcda6cb9bc3a7acf015fa59bc5083ba65c12776
Author: Andreas Veithen-Knowles <[email protected]>
AuthorDate: Sun Feb 22 07:58:39 2026 +0000
Extract StAX-independence principle from roadmap into ADR 0003
---
docs/adr/0003-no-stax-assumption-in-api.md | 61 ++++++++++++++++++++++++++++++
docs/roadmap.md | 16 ++++----
2 files changed, 68 insertions(+), 9 deletions(-)
diff --git a/docs/adr/0003-no-stax-assumption-in-api.md
b/docs/adr/0003-no-stax-assumption-in-api.md
new file mode 100644
index 000000000..c1ce57310
--- /dev/null
+++ b/docs/adr/0003-no-stax-assumption-in-api.md
@@ -0,0 +1,61 @@
+<!--
+ ~ 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.
+ -->
+
+The Axiom API should not assume that StAX is used as the XML parser
+====================================================================
+
+## Decision
+
+The Axiom API must not be designed around the assumption that a StAX
+implementation is used as the underlying XML parser. Although existing Axiom
+implementations (LLOM and DOOM) use StAX, this is not a strict requirement.
+The only strict requirements for an Axiom implementation are:
+
+* It is able to construct a tree from an `XMLStreamReader` supplied by
+ application code.
+
+* It is able to serialize a tree to an `XMLStreamWriter`.
+
+* It is able to construct an `XMLStreamReader` from a tree.
+
+In particular:
+
+* Methods defined by the Axiom API should only declare `XMLStreamException`
if
+ they interact directly with a StAX object supplied by application code.
Other
+ error conditions (such as I/O errors or parser errors during deferred
parsing)
+ should use Axiom's own exception types.
+
+* API types such as `StAXParserConfiguration` that inherently assume StAX
should
+ be replaced by more generic abstractions that are independent of the parser
+ technology.
+
+## Rationale
+
+* An Axiom implementation could use a parser API other than StAX, or provide
its
+ own XML parser. Coupling the public API to StAX would unnecessarily prevent
+ such implementations.
+
+* Keeping StAX concerns out of the API results in a cleaner separation of
+ concerns: the public API defines the object model contract, while the
choice of
+ parser is an implementation detail.
+
+* Avoiding `XMLStreamException` on methods that don't directly interact with
a
+ caller-supplied StAX object gives application code a more meaningful
exception
+ hierarchy, making it possible to distinguish I/O errors from parser errors
+ during deferred parsing.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 15a54c946..c49a941c0 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -48,12 +48,10 @@ The way exceptions are used in Axiom 1.2.x is not very
consistent. In addition i
code to distinguish between different types of error cases. This should be
improved in
Axiom 1.3 to meet the following requirements:
-* Although the two implementations of the Axiom API (LLOM and DOOM) use StAX
as XML parser, this
- is not a strict requirement. The only strict requirements are that the
implementation is able to
- construct a tree from a `XMLStreamReader` supplied by application code, is
able to serialize
- a tree to an `XMLStreamWriter` and is able to construct an
`XMLStreamReader` from a tree.
- Therefore methods defined by the Axiom API should only declare
`XMLStreamException` if they interact
- directly with a StAX object supplied by application code.
+* As noted in [ADR 0003](adr/0003-no-stax-assumption-in-api.md), the Axiom
API should not be
+ designed around the assumption that StAX is used as the XML parser.
Therefore methods defined
+ by the Axiom API should only declare `XMLStreamException` if they interact
directly with a
+ StAX object supplied by application code.
* Axiom should have well-defined (and distinct) exceptions for at least the
following two error cases:
@@ -124,9 +122,9 @@ methods should be removed.
#### `StAXParserConfiguration`
The `StAXParserConfiguration` API relies on the assumption that the XML parser
used by Axiom is
-an implementation of StAX. However, as noted above, this is not a strict
requirement; an Axiom
-implementation could equally well use another API or provide its own XML
parser.
-Therefore `StAXParserConfiguration` should be replaced by something more
generic.
+an implementation of StAX. However, as noted in [ADR
0003](adr/0003-no-stax-assumption-in-api.md),
+this is not a strict requirement. Therefore `StAXParserConfiguration` should
be replaced by
+something more generic.
#### `OMMetaFactory`
