You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ws.apache.org by ve...@apache.org on 2011/11/14 21:05:29 UTC
svn commit: r1201861 - in
/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om:
OMContainer.java OMElement.java
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