Provide OMSourcedElement Construction During StAXBuilder Processing
-------------------------------------------------------------------
Key: WSCOMMONS-263
URL: https://issues.apache.org/jira/browse/WSCOMMONS-263
Project: WS-Commons
Issue Type: Improvement
Components: AXIOM
Reporter: Rich Scheuerle
Assignee: Rich Scheuerle
Problem:
---------
During outbound processing, an OMSourcedElement may be added to the Axiom tree
to represent part of the message.
An OMSourcedElement is efficient and performant.
During inbound processing, we don't have a symmetrical capability. Instead of
building an expensive
sub-tree for a header or payload, it would be nice to represent the xml as an
efficient OMSourcedElement.
Usage Scenario 1:
-----------------
A message contains WS-A headers. These are expanded into Axiom sub-trees as
the message is parsed.
During Axis2 processing, this information is converted into
EndpointReferenceTypes (POJOs).
It would be more efficient to do this conversion when the message is parsed.
This would eliminate a translation step, excess garbage collection, etc.
Usage Scenario 2:
-----------------
A message contains a payload. The payload is expanded into an Axiom sub-tree
as the message is parsed.
(For example, assume that a handler added trace to read the whole message).
During Axis2 processing, this information is converted into an ADB or JAXB
object.
It would be more efficient to do this conversion when the message is parsed.
This would eliminate a translation step, excess garbage collection, etc.
Solution:
---------
Introduce a new interface to Axiom, CustomBuilder.
A CustomBuilder has one method.
/**
* Create an OMElement for this whole subtree.
* A null is returned if the default StAXBuilder behavior should be used.
* @param namespace
* @param localPart
* @param parent
* @param reader
* @return null or OMElement
*/
public OMElement create(String namespace,
String localPart,
OMContainer parent,
XMLStreamReader reader,
OMFactory factory)
throws OMException;
Introduce two methods on StAXBuilder.
/**
* Register a CustomBuilder for a payload.
* The payload is defined as the elements inside a SOAPBody or the
* document element of a REST message.
* @param customBuilder
* @return replaced CustomBuilder or null
*/
public CustomBuilder registerCustomBuilderForPayload(CustomBuilder
customBuilder);
/**
* Register a CustomBuilder associated with the indicated QName.
* The CustomBuilder will be used when an element of that qname is
encountered.
* @param qName
* @param maxDepth indicate the maximum depth that this qname will be
found. (root = 0)
* @param customBuilder
* @return replaced CustomBuilder or null
*/
public CustomBuilder registerCustomBuilder(QName qName, int maxDepth,
CustomBuilder customBuilder);
A consumer of Axiom (i.e. Axis2) can register a CustomBuilder on the
StAXBuilder.
For example, Axis2 could register a CustomBuilder for the WS-A headers
(Scenario 1).
For example, Axis2 JAX-WS could register a CustomBuilder for the JAXB payload
(Scenario 2).
Contribution
------------
The patch contains the interface changes defined above, plus the implementation
details.
I have also provided a conventient CustomBuilder implementation,
ByteArrayCustomBuilder.
The ByteArrayCustomBuilder will build an OMSourcedElement backed by a byte[].
This is convenient
for compressing large nested trees to a single byte[]. This CustomBuilder also
is a useful pattern
for building other CustomBuilder classes.
I have also provided a validation test (CustomBuilderTest) that uses
ByteArrayCustomBuilder.
Caveats
-------
When a CustomBuilder is used, the CustomBuilder must ONLY provide an OMElement
that represents the given
sub-tree.
The CustomBuilder is not permitted to alter information or do any work. This
would be a violation.
The expectation is that the CustomBuilder is an interface used by the direct
consumers of Axiom (i.e. Axis2) for
specific scenarios (i.e. JAX-WS JAXB)
There is no intention to expose the CustomBuilder to users of Axis2.
The lifecycle of a CustomBuilder is initially undefined. The thread-safety of
a CustomBuilder is initially undefined.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
