1/* 2 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package javax.xml.bind.annotation; 27 28import javax.xml.bind.ValidationEventHandler; 29import javax.xml.transform.Result; 30import javax.xml.transform.Source; 31 32/** 33 * Converts an element (and its descendants) 34 * from/to DOM (or similar) representation. 35 * 36 * <p> 37 * Implementations of this interface will be used in conjunction with 38 * {@link XmlAnyElement} annotation to map an element of XML into a representation 39 * of infoset such as W3C DOM. 40 * 41 * <p> 42 * Implementations hide how a portion of XML is converted into/from such 43 * DOM-like representation, allowing JAXB providers to work with arbitrary 44 * such library. 45 * 46 * <P> 47 * This interface is intended to be implemented by library writers 48 * and consumed by JAXB providers. None of those methods are intended to 49 * be called from applications. 50 * 51 * @author Kohsuke Kawaguchi 52 * @since 1.6, JAXB 2.0 53 */ 54public interface DomHandler<ElementT,ResultT extends Result> { 55 /** 56 * When a JAXB provider needs to unmarshal a part of a document into an 57 * infoset representation, it first calls this method to create a 58 * {@link Result} object. 59 * 60 * <p> 61 * A JAXB provider will then send a portion of the XML 62 * into the given result. Such a portion always form a subtree 63 * of the whole XML document rooted at an element. 64 * 65 * @param errorHandler 66 * if any error happens between the invocation of this method 67 * and the invocation of {@link #getElement(Result)}, they 68 * must be reported to this handler. 69 * 70 * The caller must provide a non-null error handler. 71 * 72 * The {@link Result} object created from this method 73 * may hold a reference to this error handler. 74 * 75 * @return 76 * null if the operation fails. The error must have been reported 77 * to the error handler. 78 */ 79 ResultT createUnmarshaller( ValidationEventHandler errorHandler ); 80 81 /** 82 * Once the portion is sent to the {@link Result}. This method is called 83 * by a JAXB provider to obtain the unmarshalled element representation. 84 * 85 * <p> 86 * Multiple invocations of this method may return different objects. 87 * This method can be invoked only when the whole sub-tree are fed 88 * to the {@link Result} object. 89 * 90 * @param rt 91 * The {@link Result} object created by {@link #createUnmarshaller(ValidationEventHandler)}. 92 * 93 * @return 94 * null if the operation fails. The error must have been reported 95 * to the error handler. 96 */ 97 ElementT getElement(ResultT rt); 98 99 /** 100 * This method is called when a JAXB provider needs to marshal an element 101 * to XML. 102 * 103 * <p> 104 * If non-null, the returned {@link Source} must contain a whole document 105 * rooted at one element, which will then be weaved into a bigger document 106 * that the JAXB provider is marshalling. 107 * 108 * @param errorHandler 109 * Receives any errors happened during the process of converting 110 * an element into a {@link Source}. 111 * 112 * The caller must provide a non-null error handler. 113 * 114 * @return 115 * null if there was an error. The error should have been reported 116 * to the handler. 117 */ 118 Source marshal( ElementT n, ValidationEventHandler errorHandler ); 119} 120