ws-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From veit...@apache.org
Subject svn commit: r1201861 - in /webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om: OMContainer.java OMElement.java
Date Mon, 14 Nov 2011 20:05:29 GMT
Author: veithen
Date: Mon Nov 14 20:05:28 2011
New Revision: 1201861

URL: http://svn.apache.org/viewvc?rev=1201861&view=rev
Log:
Some Javadoc improvements.

Modified:
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMContainer.java
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMElement.java

Modified: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMContainer.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMContainer.java?rev=1201861&r1=1201860&r2=1201861&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMContainer.java
(original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMContainer.java
Mon Nov 14 20:05:28 2011
@@ -127,75 +127,110 @@ public interface OMContainer extends OMS
     OMNode getFirstOMChild();
 
     /**
-     * Serializes the node with caching.
-     *
+     * Serialize the node with caching enabled.
+     * <p>
+     * This method will always serialize the infoset as plain XML. In particular, any {@link
OMText}
+     * containing optimized binary will be inlined using base64 encoding.
+     * 
      * @param output
+     *            the byte stream to write the serialized infoset to
      * @throws XMLStreamException
      */
+    // TODO: need to specify which charset encoding the method will use, in particular for
OMDocument nodes
     void serialize(OutputStream output) throws XMLStreamException;
 
     /**
-     * Serializes the node with caching.
-     *
+     * Serialize the node with caching enabled.
+     * <p>
+     * This method will always serialize the infoset as plain XML. In particular, any {@link
OMText}
+     * containing optimized binary will be inlined using base64 encoding.
+     * 
      * @param writer
+     *            the character stream to write the serialized infoset to
      * @throws XMLStreamException
      */
     void serialize(Writer writer) throws XMLStreamException;
 
     /**
-     * Serializes the node with caching.
-     *
+     * Serialize the node with caching enabled.
+     * <p>
+     * The format of the output is controlled by the provided {@link OMOutputFormat} object.
In
+     * particular, {@link OMOutputFormat#setDoOptimize(boolean)} can be used to instruct
this method
+     * to produce an XOP/MTOM encoded MIME message.
+     * 
      * @param output
+     *            the byte stream to write the serialized infoset to
      * @param format
+     *            the output format to use
      * @throws XMLStreamException
      */
     void serialize(OutputStream output, OMOutputFormat format)
             throws XMLStreamException;
 
     /**
-     * Serializes the node with caching.
+     * Serialize the node with caching enabled.
      *
      * @param writer
+     *            the character stream to write the serialized infoset to
      * @param format
+     *            the output format to use
      * @throws XMLStreamException
      */
     void serialize(Writer writer, OMOutputFormat format)
             throws XMLStreamException;
 
     /**
-     * Serializes the node without caching.
+     * Serialize the node without caching.
+     * <p>
+     * This method will always serialize the infoset as plain XML. In particular, any {@link
OMText}
+     * containing optimized binary will be inlined using base64 encoding.
      *
      * @param output
+     *            the byte stream to write the serialized infoset to
      * @throws XMLStreamException
      */
     void serializeAndConsume(OutputStream output)
             throws XMLStreamException;
 
     /**
-     * Serializes the node without caching.
+     * Serialize the node without caching.
+     * <p>
+     * This method will always serialize the infoset as plain XML. In particular, any {@link
OMText}
+     * containing optimized binary will be inlined using base64 encoding.
      *
      * @param writer
+     *            the character stream to write the serialized infoset to
      * @throws XMLStreamException
      */
     void serializeAndConsume(Writer writer) throws XMLStreamException;
 
     /**
-     * Serializes the node without caching.
+     * Serialize the node without caching.
+     * <p>
+     * The format of the output is controlled by the provided {@link OMOutputFormat} object.
In
+     * particular, {@link OMOutputFormat#setDoOptimize(boolean)} can be used to instruct
this method
+     * to produce an XOP/MTOM encoded MIME message.
      *
      * @param output
+     *            the byte stream to write the serialized infoset to
      * @param format
+     *            the output format to use
      * @throws XMLStreamException
      */
     void serializeAndConsume(OutputStream output, OMOutputFormat format)
             throws XMLStreamException;
 
     /**
-     * Serializes the node without caching.
+     * Serialize the node without caching.
      *
      * @param writer
+     *            the character stream to write the serialized infoset to
      * @param format
+     *            the output format to use
      * @throws XMLStreamException
      */
+    // TODO: need to clarify what OMOutputFormat settings are actually taken into account
+    //       (obviously the method can't produce XOP/MTOM and the charset encoding is ignored)
     void serializeAndConsume(Writer writer, OMOutputFormat format)
             throws XMLStreamException;
 

Modified: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMElement.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMElement.java?rev=1201861&r1=1201860&r2=1201861&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMElement.java
(original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMElement.java
Mon Nov 14 20:05:28 2011
@@ -497,15 +497,30 @@ public interface OMElement extends OMNod
     void setNamespaceWithNoFindInCurrentScope(OMNamespace namespace);
 
     /**
-     * This is a convenience method only. This will basically serialize the given OMElement
to a
-     * String but will build the OMTree in the memory
+     * Convenience method to serialize the element to a string with caching enabled. Caching
means
+     * that the object model tree for the element will be fully built in memory and can be
accessed
+     * after invoking this method.
+     * <p>
+     * This method produces the same result as {@link OMContainer#serialize(Writer)}. In
particular,
+     * the element is always serialized as plain XML and {@link OMText} nodes containing
optimized
+     * binary data are always inlined using base64 encoding. Since the output is accumulated
into a
+     * single string object, this may result in high memory consumption. Therefore this method
+     * should be used with care.
+     * 
+     * @return the serialized object model
      */
     String toString();
 
     /**
-     * This is a convenience method only. This basically serializes the given OMElement to
a String
-     * but will NOT build the OMTree in the memory. So you are at your own risk of losing
-     * information.
+     * Convenience method to serialize the element to a string without caching. This method
will not
+     * built the object model tree in memory. This means that an attempt to access the object
model
+     * after invoking this method may result in an error (unless the object model was already
fully
+     * built before, e.g. because it was created programmatically).
+     * <p>
+     * As for {@link #toString()}, this method may cause high memory consumption for object
model
+     * trees containing optimized binary data and should therefore be used with care.
+     * 
+     * @return the serialized object model
      */
     String toStringWithConsume() throws XMLStreamException;
 
@@ -537,9 +552,13 @@ public interface OMElement extends OMNod
     int getLineNumber();
 
     /**
-     * Serializes the node with caching.
-     *
+     * Serialize the node with caching enabled.
+     * <p>
+     * This method will always serialize the infoset as plain XML. In particular, any {@link
OMText}
+     * containing optimized binary will be inlined using base64 encoding.
+     * 
      * @param output
+     *            the byte stream to write the serialized infoset to
      * @throws XMLStreamException
      */
     // Note: This method is inherited from both OMNode and OMContainer, but it is deprecated
in
@@ -548,9 +567,13 @@ public interface OMElement extends OMNod
     void serialize(OutputStream output) throws XMLStreamException;
 
     /**
-     * Serializes the node with caching.
-     *
+     * Serialize the node with caching enabled.
+     * <p>
+     * This method will always serialize the infoset as plain XML. In particular, any {@link
OMText}
+     * containing optimized binary will be inlined using base64 encoding.
+     * 
      * @param writer
+     *            the character stream to write the serialized infoset to
      * @throws XMLStreamException
      */
     // Note: This method is inherited from both OMNode and OMContainer, but it is deprecated
in
@@ -559,10 +582,16 @@ public interface OMElement extends OMNod
     void serialize(Writer writer) throws XMLStreamException;
 
     /**
-     * Serializes the node with caching.
-     *
+     * Serialize the node with caching enabled.
+     * <p>
+     * The format of the output is controlled by the provided {@link OMOutputFormat} object.
In
+     * particular, {@link OMOutputFormat#setDoOptimize(boolean)} can be used to instruct
this method
+     * to produce an XOP/MTOM encoded MIME message.
+     * 
      * @param output
+     *            the byte stream to write the serialized infoset to
      * @param format
+     *            the output format to use
      * @throws XMLStreamException
      */
     // Note: This method is inherited from both OMNode and OMContainer, but it is deprecated
in
@@ -572,10 +601,12 @@ public interface OMElement extends OMNod
             throws XMLStreamException;
 
     /**
-     * Serializes the node with caching.
+     * Serialize the node with caching enabled.
      *
      * @param writer
+     *            the character stream to write the serialized infoset to
      * @param format
+     *            the output format to use
      * @throws XMLStreamException
      */
     // Note: This method is inherited from both OMNode and OMContainer, but it is deprecated
in
@@ -585,9 +616,13 @@ public interface OMElement extends OMNod
             throws XMLStreamException;
 
     /**
-     * Serializes the node without caching.
+     * Serialize the node without caching.
+     * <p>
+     * This method will always serialize the infoset as plain XML. In particular, any {@link
OMText}
+     * containing optimized binary will be inlined using base64 encoding.
      *
      * @param output
+     *            the byte stream to write the serialized infoset to
      * @throws XMLStreamException
      */
     // Note: This method is inherited from both OMNode and OMContainer, but it is deprecated
in
@@ -597,9 +632,13 @@ public interface OMElement extends OMNod
             throws XMLStreamException;
 
     /**
-     * Serializes the node without caching.
+     * Serialize the node without caching.
+     * <p>
+     * This method will always serialize the infoset as plain XML. In particular, any {@link
OMText}
+     * containing optimized binary will be inlined using base64 encoding.
      *
      * @param writer
+     *            the character stream to write the serialized infoset to
      * @throws XMLStreamException
      */
     // Note: This method is inherited from both OMNode and OMContainer, but it is deprecated
in
@@ -608,10 +647,16 @@ public interface OMElement extends OMNod
     void serializeAndConsume(Writer writer) throws XMLStreamException;
 
     /**
-     * Serializes the node without caching.
+     * Serialize the node without caching.
+     * <p>
+     * The format of the output is controlled by the provided {@link OMOutputFormat} object.
In
+     * particular, {@link OMOutputFormat#setDoOptimize(boolean)} can be used to instruct
this method
+     * to produce an XOP/MTOM encoded MIME message.
      *
      * @param output
+     *            the byte stream to write the serialized infoset to
      * @param format
+     *            the output format to use
      * @throws XMLStreamException
      */
     // Note: This method is inherited from both OMNode and OMContainer, but it is deprecated
in
@@ -621,10 +666,12 @@ public interface OMElement extends OMNod
             throws XMLStreamException;
 
     /**
-     * Serializes the node without caching.
+     * Serialize the node without caching.
      *
      * @param writer
+     *            the character stream to write the serialized infoset to
      * @param format
+     *            the output format to use
      * @throws XMLStreamException
      */
     // Note: This method is inherited from both OMNode and OMContainer, but it is deprecated
in



Mime
View raw message