001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.bind.annotation;
027
028 import javax.xml.bind.ValidationEventHandler;
029 import javax.xml.transform.Result;
030 import javax.xml.transform.Source;
031
032 /**
033 * Converts an element (and its descendants)
034 * from/to DOM (or similar) representation.
035 *
036 * <p>
037 * Implementations of this interface will be used in conjunction with
038 * {@link XmlAnyElement} annotation to map an element of XML into a representation
039 * of infoset such as W3C DOM.
040 *
041 * <p>
042 * Implementations hide how a portion of XML is converted into/from such
043 * DOM-like representation, allowing JAXB providers to work with arbitrary
044 * such library.
045 *
046 * <P>
047 * This interface is intended to be implemented by library writers
048 * and consumed by JAXB providers. None of those methods are intended to
049 * be called from applications.
050 *
051 * @author Kohsuke Kawaguchi
052 * @since JAXB2.0
053 */
054 public interface DomHandler<ElementT, ResultT extends Result> {
055 /**
056 * When a JAXB provider needs to unmarshal a part of a document into an
057 * infoset representation, it first calls this method to create a
058 * {@link Result} object.
059 *
060 * <p>
061 * A JAXB provider will then send a portion of the XML
062 * into the given result. Such a portion always form a subtree
063 * of the whole XML document rooted at an element.
064 *
065 * @param errorHandler
066 * if any error happens between the invocation of this method
067 * and the invocation of {@link #getElement(Result)}, they
068 * must be reported to this handler.
069 *
070 * The caller must provide a non-null error handler.
071 *
072 * The {@link Result} object created from this method
073 * may hold a reference to this error handler.
074 *
075 * @return
076 * null if the operation fails. The error must have been reported
077 * to the error handler.
078 */
079 ResultT createUnmarshaller(ValidationEventHandler errorHandler);
080
081 /**
082 * Once the portion is sent to the {@link Result}. This method is called
083 * by a JAXB provider to obtain the unmarshalled element representation.
084 *
085 * <p>
086 * Multiple invocations of this method may return different objects.
087 * This method can be invoked only when the whole sub-tree are fed
088 * to the {@link Result} object.
089 *
090 * @param rt
091 * The {@link Result} object created by {@link #createUnmarshaller(ValidationEventHandler)}.
092 *
093 * @return
094 * null if the operation fails. The error must have been reported
095 * to the error handler.
096 */
097 ElementT getElement(ResultT rt);
098
099 /**
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 }
|