svn commit: r727380 - in /webservices/commons/trunk/modules/axiom/modules: axiom-api/src/main/java/org/apache/axiom/om/OMAbstractFactory.java axiom-dom/src/main/java/org/apache/axiom/om/impl/dom/factory/OMDOMFactory.java

[ve...@apache.org]

Author: veithen
Date: Wed Dec 17 05:43:59 2008
New Revision: 727380

URL: http://svn.apache.org/viewvc?rev=727380&view=rev
Log:
WSCOMMONS-348: Updated the Javadoc to explain the restrictions that apply to OMDOMFactory.

Modified:
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMAbstractFactory.java
    webservices/commons/trunk/modules/axiom/modules/axiom-dom/src/main/java/org/apache/axiom/om/impl/dom/factory/OMDOMFactory.java

Modified: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMAbstractFactory.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMAbstractFactory.java?rev=727380&r1=727379&r2=727380&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMAbstractFactory.java (original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMAbstractFactory.java Wed Dec 17 05:43:59 2008
@@ -54,9 +54,12 @@
  *     <td>{@link org.apache.axiom.soap.impl.llom.soap12.SOAP12Factory}</td>
  *   </tr>
  * </table>
- * <p>Since {@link OMFactory} instances are supposed to be stateless, each method in this class
- * returns the same instance on every invocation, i.e. the factory for each OM type is instantiated
- * only once.</p>
+ * <p>The methods in this class assume that {@link OMFactory} instances are stateless and
+ * return the same instance on every invocation, i.e. the factory for each OM type is instantiated
+ * only once. Configuring the system properties with factory implementation that are not
+ * stateless will lead to unexpected results. It should be noted that the factories provided
+ * by the DOOM implementation are not stateless and should therefore never be used as default
+ * factories.</p>
  * <p>Each method in this class uses {@link System#getProperty(String)} to determine the value of
  * the relevant system property. A {@link SecurityException} thrown by this method is simply ignored
  * and the default factory implementation is used.</p> 

Modified: webservices/commons/trunk/modules/axiom/modules/axiom-dom/src/main/java/org/apache/axiom/om/impl/dom/factory/OMDOMFactory.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-dom/src/main/java/org/apache/axiom/om/impl/dom/factory/OMDOMFactory.java?rev=727380&r1=727379&r2=727380&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-dom/src/main/java/org/apache/axiom/om/impl/dom/factory/OMDOMFactory.java (original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-dom/src/main/java/org/apache/axiom/om/impl/dom/factory/OMDOMFactory.java Wed Dec 17 05:43:59 2008
@@ -20,6 +20,7 @@
 package org.apache.axiom.om.impl.dom.factory;
 
 
+import org.apache.axiom.om.OMAbstractFactory;
 import org.apache.axiom.om.OMAttribute;
 import org.apache.axiom.om.OMComment;
 import org.apache.axiom.om.OMContainer;
@@ -49,6 +50,30 @@
 
 import javax.xml.namespace.QName;
 
+/**
+ * OM factory implementation for DOOM. It creates nodes that implement
+ * DOM as defined by the interfaces in {@link org.w3c.dom}.
+ * <p>
+ * Since DOM requires every node to have an owner document even if it has not yet
+ * been added to a tree, this factory internally maintains a reference to a
+ * {@link DocumentImpl} instance. The document can be set explicitly using the
+ * {@link #OMDOMFactory(DocumentImpl)} constructor or the {@link #setDocument(DocumentImpl)}
+ * method. If none is set, it will be implicitly created when the first node is created.
+ * All nodes created by this factory will have this {@link DocumentImpl} instance as owner
+ * document.
+ * <p>
+ * This has several important consequences:
+ * <ul>
+ *   <li>The same instance of this class should not be used to parse or construct
+ *       multiple documents unless {@link #setDocument(DocumentImpl)} is used
+ *       to reset the {@link DocumentImpl} instance before processing the next document.</li>
+ *   <li>Instances of this class are not thread safe and using a single instance concurrently
+ *       will lead to undefined results.</li>
+ *   <li>Since instances are not stateless, this class (as well as its subclasses) must
+ *       not be used in conjunction with {@link OMAbstractFactory}. In particular,
+ *       the <tt>om.factory</tt> system property must not be set to this class.</li> 
+ * </ul>
+ */
 public class OMDOMFactory implements OMFactory {
 
     protected DocumentImpl document;