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;
