1 /* 2 * Copyright [2005] [University Corporation for Advanced Internet Development, Inc.] 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package org.opensaml.xml.io; 18 19 import org.opensaml.xml.XMLObject; 20 import org.w3c.dom.Document; 21 import org.w3c.dom.Element; 22 23 /** 24 * Marshallers are used to marshall a {@link org.opensaml.xml.XMLObject} into a W3C DOM element. 25 */ 26 public interface Marshaller { 27 28 /** 29 * Marshall this element, and its children, and root them in a newly created Document. The Document is created by a 30 * {@link javax.xml.parsers.DocumentBuilder} obtained from a {@link javax.xml.parsers.DocumentBuilderFactory} 31 * created without any additional parameters or properties set; that is the system defaults properties are used. 32 * 33 * @param xmlObject the object to marshall 34 * 35 * @return the W3C DOM element representing this SAML element 36 * 37 * @throws MarshallingException thrown if there is a problem marshalling the given object 38 */ 39 public Element marshall(XMLObject xmlObject) throws MarshallingException; 40 41 /** 42 * Marshall this element, and its children, into a W3C DOM element. If the document does not have a Document Element 43 * the Element resulting from this marshalling will be set as the Document Element. 44 * 45 * @param xmlObject the object to marshall 46 * @param document the DOM document the marshalled element will be placed in 47 * 48 * @return the W3C DOM element representing this XMLObject 49 * 50 * @throws MarshallingException thrown if there is a problem marshalling the given object 51 */ 52 public Element marshall(XMLObject xmlObject, Document document) throws MarshallingException; 53 54 /** 55 * Marshall the given XMLObject and append it as a child to the given parent element. 56 * 57 * <strong>NOTE:</strong> The given Element must be within a DOM tree whose root is the root of the Document owning 58 * the given Element. 59 * 60 * @param xmlObject the XMLObject to be marshalled 61 * @param parentElement the parent of the Element resulting from marshalling the given XMLObject 62 * 63 * @return the marshalled XMLObject 64 * 65 * @throws MarshallingException thrown if the given XMLObject can not be marshalled. 66 */ 67 public Element marshall(XMLObject xmlObject, Element parentElement) throws MarshallingException; 68 }