svn commit: r1209136 - /webservices/commons/trunk/modules/axiom/src/site/apt/roadmap.apt

[ve...@apache.org]

Author: veithen
Date: Thu Dec  1 16:10:16 2011
New Revision: 1209136

URL: http://svn.apache.org/viewvc?rev=1209136&view=rev
Log:
Some more Axiom 1.3 stuff.

Modified:
    webservices/commons/trunk/modules/axiom/src/site/apt/roadmap.apt

Modified: webservices/commons/trunk/modules/axiom/src/site/apt/roadmap.apt
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/src/site/apt/roadmap.apt?rev=1209136&r1=1209135&r2=1209136&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/src/site/apt/roadmap.apt (original)
+++ webservices/commons/trunk/modules/axiom/src/site/apt/roadmap.apt Thu Dec  1 16:10:16 2011
@@ -100,10 +100,8 @@ Removal of unnecessary or irrelevant API
    * The <<<OMAttachmentAccessor>>> API is required in conjunction with the <<<setInlineMTOM>>> method
      defined by <<<OMXMLStreamReader>>>. However, that method is deprecated.
    
-   * The <<<XOPBuilder>>> interface extends <<<OMAttachmentAccessor>>>. However, <<<XOPBuilder>>> (as well
-     as its implementing classes <<<XOPAwareStAXOMBuilder>>> and <<<MTOMStAXSOAPModelBuilder>>>) is part
-     of an <<<impl>>> package and is not expected to be referenced directly by application code. With the changes in
-     r1164997 and r1207662, <<<XOPBuilder>>> is also no longer used internally by Axiom.
+   * The <<<XOPBuilder>>> interface extends <<<OMAttachmentAccessor>>>. However, as explained below,
+     that API will be removed in Axiom 1.3.
 
 * <<<org.apache.axiom.om.impl.builder.BuilderAwareReader>>>
 
@@ -119,6 +117,25 @@ Removal of unnecessary or irrelevant API
   
   TODO: analyze the use cases for this API to see if we still need it 
 
+* <<<org.apache.axiom.om.impl.builder.XOPBuilder>>>
+
+  The <<<XOPBuilder>>> interface is implemented by <<<XOPAwareStAXOMBuilder>>> and <<<MTOMStAXSOAPModelBuilder>>>.
+  With the changes in r1164997 and r1207662, it is no longer used internally by Axiom.
+  The interface declares methods that give access to the <<<Attachments>>> object that was
+  used to create the builder. That is undesirable for two reasons:
+  
+   * For XOP/MTOM encoded messages, optimized binary data should always be accessed
+     through the <<<OMText>>> API and not by accessing MIME parts directly through
+     the <<<Attachments>>> API.
+   
+   * The existence of the <<<XOPBuilder>>> API (and in particular the <<<getAttachments>>>
+     method defined by that interface) implies that an XOP/MTOM builder is necessarily
+     created from an <<<Attachments>>> object. However, it may be desirable to support other
+     ways to supply the MIME parts to the builder (e.g. using an implementation of the
+     <<<MimePartProvider>>> API).
+  
+  Therefore the <<<XOPBuilder>>> API will be removed in Axiom 1.3.
+
 Classes to be moved from <<<axiom-api>>> to <<<axiom-common-impl>>>
 
   Up to version 1.2.12, the core Axiom code was organized in three modules,
@@ -176,7 +193,7 @@ Classes to be moved from <<<axiom-api>>>
   Together with these classes, the following interfaces and helper classes should also
   be moved to <<<axiom-common-impl>>>:
   
-   * <<<org.apache.axiom.om.impl.builder.XOPBuilder>>> (TODO: probably no longer required)
+   * TODO
 
 Public APIs that need to be moved to another package