[jira] Updated: (WSCOMMONS-263) Provide OMSourcedElement Construction During StAXBuilder Processing

["Rich Scheuerle (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/WSCOMMONS-263?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Rich Scheuerle updated WSCOMMONS-263:
-------------------------------------

    Attachment: patch.txt

Here is the patch.  I will commit the patch after I receive more input from the community.

I welcome your comments and suggestions.

Thanks,
Rich

> 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
>         Attachments: patch.txt
>
>
> 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: commons-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: commons-dev-help@ws.apache.org