[java-opensaml COMMIT] in /trunk/opensaml-core/src: main/java/org/opensaml/core/xml/util/XMLObjectSupport.java test/j...

[noreply at shibboleth.net]

Author: putmanb
Date: Thu Nov  5 16:13:00 2015
New Revision: 4386

URL: http://svn.shibboleth.net/view/java-opensaml?rev=4386&view=rev
Log:
OSJ-139: Change and improve options for XMLObject clone output vis-a-vis DOM

Modified:
    trunk/opensaml-core/src/main/java/org/opensaml/core/xml/util/XMLObjectSupport.java
    trunk/opensaml-core/src/test/java/org/opensaml/core/xml/util/XMLObjectSupportTest.java

Modified: trunk/opensaml-core/src/main/java/org/opensaml/core/xml/util/XMLObjectSupport.java
URL: http://svn.shibboleth.net/view/java-opensaml/trunk/opensaml-core/src/main/java/org/opensaml/core/xml/util/XMLObjectSupport.java?rev=4386&r1=4385&r2=4386&view=diff
==============================================================================
--- trunk/opensaml-core/src/main/java/org/opensaml/core/xml/util/XMLObjectSupport.java	(original)
+++ trunk/opensaml-core/src/main/java/org/opensaml/core/xml/util/XMLObjectSupport.java	Thu Nov  5 16:13:00 2015
@@ -58,6 +58,22 @@
  */
 public final class XMLObjectSupport {
     
+    /** Options for handling output of XMLObject cloning. */
+    public enum CloneOutputOption {
+        
+        /** Completely and recursively drop the DOM from the cloned object and its children. */
+        DropDOM,
+        
+        /** The cloned XMLObject's DOM will be the root document element of a new {@link Document},
+         * that is it will be the {@link Element} returned by {@link Document#getDocumentElement()}. */
+        RootDOMInNewDocument,
+        
+        /** The cloned XMLObject's DOM will be owned by the same {@link Document} as the input object
+         * (the latter possibly newly created by marshalling internally), but will not be disconnected
+         * and not be connected to the node tree associated with the {@link Document#getDocumentElement()}.*/
+        UnrootedDOM,
+    }
+    
     /** Constructor. */
     private XMLObjectSupport() { }
     
@@ -71,7 +87,8 @@
      * </p>
      * 
      * <p>
-     * This method variant is equivalent to <code>cloneXMLObject(originalXMLObject, false).</code>
+     * This method variant is equivalent to 
+     * <code>cloneXMLObject(originalXMLObject, CloneOutputOption.DropDOM).</code>
      * </p>
      * 
      * 
@@ -85,7 +102,7 @@
      */
     public static <T extends XMLObject> T cloneXMLObject(T originalXMLObject)
             throws MarshallingException, UnmarshallingException {
-        return cloneXMLObject(originalXMLObject, false);
+        return cloneXMLObject(originalXMLObject, CloneOutputOption.DropDOM);
     }
     
     /**
@@ -97,6 +114,14 @@
      * 3) Unmarshall a new XMLObject tree around it.
      * </p>
      * 
+     * <p>
+     * This method variant is equivalent to 
+     * <code>cloneXMLObject(originalXMLObject, CloneOutputOption.RootDOMInNewDocument)</code>
+     * or
+     * <code>cloneXMLObject(originalXMLObject, CloneOutputOption.UnrootedDOM)</code>,
+     * depending on the value of <code>rootInNewDocument</code>
+     * </p>
+     * 
      * @param originalXMLObject the object to be cloned
      * @param rootInNewDocument if true the cloned object's cached DOM will be rooted
      *          in a new Document; if false, the original object's underlying DOM is cloned,
@@ -107,9 +132,39 @@
      * @throws UnmarshallingException if cloned object tree can not be unmarshalled
      * 
      * @param <T> the type of object being cloned
-     */
+     * 
+     * @deprecated use instead {@link #cloneXMLObject(XMLObject, CloneOutputOption)}.
+     */
+    @Deprecated
     @Nullable public static <T extends XMLObject> T cloneXMLObject(@Nullable T originalXMLObject,
             boolean rootInNewDocument) throws MarshallingException, UnmarshallingException {
+        if (rootInNewDocument) {
+            return cloneXMLObject(originalXMLObject, CloneOutputOption.RootDOMInNewDocument);
+        } else {
+            return cloneXMLObject(originalXMLObject, CloneOutputOption.UnrootedDOM);
+        }
+    }
+    
+    /**
+     * Clone an XMLObject by brute force:
+     * 
+     * <p>
+     * 1) Marshall the original object if necessary
+     * 2) Clone the resulting DOM Element
+     * 3) Unmarshall a new XMLObject tree around it.
+     * </p>
+     * 
+     * @param originalXMLObject the object to be cloned
+     * @param cloneOutputOption  the option for handling the cloned object output
+     * @return a clone of the original object
+     * 
+     * @throws MarshallingException if original object can not be marshalled
+     * @throws UnmarshallingException if cloned object tree can not be unmarshalled
+     * 
+     * @param <T> the type of object being cloned
+     */
+    @Nullable public static <T extends XMLObject> T cloneXMLObject(@Nullable T originalXMLObject,
+            @Nonnull final CloneOutputOption cloneOutputOption) throws MarshallingException, UnmarshallingException {
         
         if (originalXMLObject == null) {
             return null;
@@ -124,17 +179,23 @@
         
         Element clonedElement = null;
         
-        if (rootInNewDocument) {
-            try {

[... 162 lines stripped ...]