svn commit: r1215259 - in /webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments: AttachmentSet.java Attachments.java AttachmentsDelegate.java AttachmentsImpl.java MIMEMessage.java

[ve...@apache.org]

Author: veithen
Date: Fri Dec 16 20:11:13 2011
New Revision: 1215259

URL: http://svn.apache.org/viewvc?rev=1215259&view=rev
Log:
AXIOM-377: Renamed AttachmentsImpl to AttachmentsDelegate and clarified the role of that class.

Added:
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentsDelegate.java
      - copied, changed from r1212983, webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentsImpl.java
Removed:
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentsImpl.java
Modified:
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentSet.java
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/Attachments.java
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/MIMEMessage.java

Modified: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentSet.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentSet.java?rev=1215259&r1=1215258&r2=1215259&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentSet.java (original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentSet.java Fri Dec 16 20:11:13 2011
@@ -31,7 +31,11 @@ import javax.mail.internet.ContentType;
 import org.apache.axiom.attachments.lifecycle.LifecycleManager;
 import org.apache.axiom.om.OMException;
 
-class AttachmentSet extends AttachmentsImpl {
+/**
+ * {@link AttachmentsDelegate} implementation that represents a programmatically created set of
+ * attachment parts.
+ */
+class AttachmentSet extends AttachmentsDelegate {
     private final Map attachmentsMap = new LinkedHashMap();
 
     ContentType getContentType() {

Modified: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/Attachments.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/Attachments.java?rev=1215259&r1=1215258&r2=1215259&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/Attachments.java (original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/Attachments.java Fri Dec 16 20:11:13 2011
@@ -38,7 +38,7 @@ import java.util.Set;
 import java.util.Map;
 
 public class Attachments implements OMAttachmentAccessor {
-    private final AttachmentsImpl impl;
+    private final AttachmentsDelegate delegate;
    
     /**
      * <code>applicationType</code> used to distinguish between MTOM & SWA If the message is MTOM
@@ -47,11 +47,11 @@ public class Attachments implements OMAt
     private String applicationType;
 
     public LifecycleManager getLifecycleManager() {
-        return impl.getLifecycleManager();
+        return delegate.getLifecycleManager();
     }
 
     public void setLifecycleManager(LifecycleManager manager) {
-        impl.setLifecycleManager(manager);
+        delegate.setLifecycleManager(manager);
     }
 
     /**
@@ -90,7 +90,7 @@ public class Attachments implements OMAt
         } else {
             fileStorageThreshold = 1;
         }
-        impl = new MIMEMessage(manager, inStream, contentTypeString, fileCacheEnable,
+        delegate = new MIMEMessage(manager, inStream, contentTypeString, fileCacheEnable,
                 attachmentRepoDir, fileStorageThreshold, contentLength);
     }
 
@@ -144,7 +144,7 @@ public class Attachments implements OMAt
      * through the SwA API.
      */
     public Attachments() {
-        impl = new AttachmentSet();
+        delegate = new AttachmentSet();
     }
 
     /**
@@ -159,7 +159,7 @@ public class Attachments implements OMAt
      */
     public String getAttachmentSpecType() {
         if (this.applicationType == null) {
-            ContentType contentType = impl.getContentType();
+            ContentType contentType = delegate.getContentType();
             if (contentType == null) {
                 throw new OMException("Unable to determine the attachment spec type because the " +
                 		"Attachments object doesn't have a known content type");
@@ -193,7 +193,7 @@ public class Attachments implements OMAt
      *         <code>null</code> if the MIME part referred by the content ID does not exist
      */
     public DataHandler getDataHandler(String contentID) {
-        return impl.getDataHandler(contentID);
+        return delegate.getDataHandler(contentID);
     }
 
     /**
@@ -204,7 +204,7 @@ public class Attachments implements OMAt
      * @param dataHandler
      */
     public void addDataHandler(String contentID, DataHandler dataHandler) {
-        impl.addDataHandler(contentID, dataHandler);
+        delegate.addDataHandler(contentID, dataHandler);
     }
 
     /**
@@ -214,7 +214,7 @@ public class Attachments implements OMAt
      * @param blobContentID
      */
     public void removeDataHandler(String blobContentID) {
-        impl.removeDataHandler(blobContentID);
+        delegate.removeDataHandler(blobContentID);
     }
 
     /**
@@ -245,7 +245,7 @@ public class Attachments implements OMAt
      * @return the input stream for the root part
      */
     public InputStream getRootPartInputStream() throws OMException {
-        return impl.getRootPartInputStream();
+        return delegate.getRootPartInputStream();
     }
 
     /**
@@ -260,7 +260,7 @@ public class Attachments implements OMAt
      * @return the content ID of the root part (without the surrounding angle brackets)
      */
     public String getRootPartContentID() {
-        return impl.getRootPartContentID();
+        return delegate.getRootPartContentID();
     }
 
     /**
@@ -272,7 +272,7 @@ public class Attachments implements OMAt
      *             if the content type could not be determined
      */
     public String getRootPartContentType() {
-        return impl.getRootPartContentType();
+        return delegate.getRootPartContentType();
     }
 
     /**
@@ -283,7 +283,7 @@ public class Attachments implements OMAt
      */
     public IncomingAttachmentStreams getIncomingAttachmentStreams()
             throws IllegalStateException {
-        return impl.getIncomingAttachmentStreams();
+        return delegate.getIncomingAttachmentStreams();
     }
 
     /**
@@ -295,7 +295,7 @@ public class Attachments implements OMAt
      * @return an array with the content IDs in order of appearance in the message
      */
     public String[] getAllContentIDs() {
-        Set cids = impl.getContentIDs(true);
+        Set cids = delegate.getContentIDs(true);
         return (String[]) cids.toArray(new String[cids.size()]);
     }
 
@@ -308,7 +308,7 @@ public class Attachments implements OMAt
      * @return the set of content IDs
      */
     public Set getContentIDSet() {
-        return impl.getContentIDs(true);
+        return delegate.getContentIDs(true);
     }
     
     /**
@@ -320,7 +320,7 @@ public class Attachments implements OMAt
      *         {@link DataHandler} objects as values.
      */
     public Map getMap() {
-        return impl.getMap();
+        return delegate.getMap();
     }
 
     /**
@@ -334,7 +334,7 @@ public class Attachments implements OMAt
      * @return List of content IDs in order of appearance in message
      */
     public List getContentIDList() {
-        return new ArrayList(impl.getContentIDs(false));
+        return new ArrayList(delegate.getContentIDs(false));
     }
     
     /**
@@ -345,7 +345,7 @@ public class Attachments implements OMAt
      * backed by an InputStream
      */
     public long getContentLength() throws IOException {
-        return impl.getContentLength();
+        return delegate.getContentLength();
     }
 
     /**

Copied: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentsDelegate.java (from r1212983, webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentsImpl.java)
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentsDelegate.java?p2=webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentsDelegate.java&p1=webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentsImpl.java&r1=1212983&r2=1215259&rev=1215259&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentsImpl.java (original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/AttachmentsDelegate.java Fri Dec 16 20:11:13 2011
@@ -29,7 +29,26 @@ import javax.mail.internet.ContentType;
 import org.apache.axiom.attachments.lifecycle.LifecycleManager;
 import org.apache.axiom.om.OMException;
 
-abstract class AttachmentsImpl {
+/**
+ * {@link Attachments} delegate. An {@link Attachments} object may actually represent two fairly
+ * different things (depending on the constructor that is used):
+ * <ul>
+ * <li>A MIME multipart message that comprises a root part and a set of attachment parts. Axiom uses
+ * deferred parsing to process the message, i.e. the parts and their content are loaded on-demand.
+ * <li>A programmatically created set of attachment parts. In that case, the root part is not
+ * included.
+ * </ul>
+ * Since the behavior of the {@link Attachments} instance is fairly different in the two cases, this
+ * should be considered a flaw in the API design. Unfortunately it is not possible to fix this
+ * without breaking existing code. In particular, in Axis2 the {@link Attachments} API is heavily
+ * used by application code. Therefore a delegation pattern is used so that internally these two
+ * cases can be represented using distinct classes.
+ * <p>
+ * Note that this class is intentionally not public. It is for <b>internal use only</b>. However, in
+ * a later Axiom version we may want to refactor this API to make it public, in which case
+ * {@link Attachments} would simply become a legacy adapter.
+ */
+abstract class AttachmentsDelegate {
     abstract ContentType getContentType();
     abstract LifecycleManager getLifecycleManager();
     abstract void setLifecycleManager(LifecycleManager manager);

Modified: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/MIMEMessage.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/MIMEMessage.java?rev=1215259&r1=1215258&r2=1215259&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/MIMEMessage.java (original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/attachments/MIMEMessage.java Fri Dec 16 20:11:13 2011
@@ -46,7 +46,11 @@ import org.apache.james.mime4j.stream.Mi
 import org.apache.james.mime4j.stream.MimeTokenStream;
 import org.apache.james.mime4j.stream.RecursionMode;
 
-class MIMEMessage extends AttachmentsImpl {
+/**
+ * {@link AttachmentsDelegate} implementation that represents a MIME multipart message read from a
+ * stream.
+ */
+class MIMEMessage extends AttachmentsDelegate {
     private static final Log log = LogFactory.getLog(MIMEMessage.class);
 
     /** <code>ContentType</code> of the MIME message */