Java > Open Source Codes > javax > xml > transform > dom > DOMResult


1 // $Id: DOMResult.java,v 1.4.16.5 2004/07/13 22:27:49 jsuttor Exp $
2 /*
3  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
4  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
5  */
6
7  /*
8   * @(#)DOMResult.java 1.15 04/07/13
9   */
10
11 package javax.xml.transform.dom;
12
13 import javax.xml.transform.Result ;
14 import org.w3c.dom.Node ;
15
16 /**
17  * <p>Acts as a holder for a transformation result tree in the form of a Document Object Model (DOM) tree.</p>
18  *
19  * <p>If no output DOM source is set, the transformation will create a Document node as the holder for the result of the transformation,
20  * which may be retrieved with {@link #getNode()}.</p>
21  *
22  * @author <a HREF="Jeff.Suttor@Sun.com">Jeff Suttor</a>
23  * @version $Revision: 1.4.16.5 $, $Date: 2004/07/13 22:27:49 $
24  */
25 public class DOMResult implements Result {
26
27     /** <p>If {@link javax.xml.transform.TransformerFactory#getFeature}
28      * returns <code>true</code> when passed this value as an argument,
29      * the <code>Transformer</code> supports <code>Result</code> output of this type.</p>
30      */
31     public static final String FEATURE = "http://javax.xml.transform.dom.DOMResult/feature";
32
33     /**
34      * <p>Zero-argument default constructor.</p>
35      *
36      * <p><code>node</code>,
37      * <code>siblingNode</code> and
38      * <code>systemId</code>
39      * will be set to <code>null</code>.</p>
40      */
41     public DOMResult() {
42         setNode(null);
43         setNextSibling(null);
44         setSystemId(null);
45     }
46
47     /**
48      * <p>Use a DOM node to create a new output target.</p>
49      *
50      * <p>In practice, the node should be
51      * a {@link org.w3c.dom.Document} node,
52      * a {@link org.w3c.dom.DocumentFragment} node, or
53      * a {@link org.w3c.dom.Element} node.
54      * In other words, a node that accepts children.</p>
55      *
56      * <p><code>siblingNode</code> and
57      * <code>systemId</code>
58      * will be set to <code>null</code>.</p>
59      *
60      * @param node The DOM node that will contain the result tree.
61      */
62     public DOMResult(Node node) {
63         setNode(node);
64         setNextSibling(null);
65         setSystemId(null);
66     }
67
68     /**
69      * <p>Use a DOM node to create a new output target with the specified System ID.<p>
70      *
71      * <p>In practice, the node should be
72      * a {@link org.w3c.dom.Document} node,
73      * a {@link org.w3c.dom.DocumentFragment} node, or
74      * a {@link org.w3c.dom.Element} node.
75      * In other words, a node that accepts children.</p>
76      *
77      * <p><code>siblingNode</code> will be set to <code>null</code>.</p>
78      *
79      * @param node The DOM node that will contain the result tree.
80      * @param systemId The system identifier which may be used in association with this node.
81      */
82     public DOMResult(Node node, String systemId) {
83         setNode(node);
84         setNextSibling(null);
85         setSystemId(systemId);
86     }
87
88     /**
89      * <p>Use a DOM node to create a new output target specifying the child node where the result nodes should be inserted before.</p>
90      *
91      * <p>In practice, <code>node</code> and <code>nextSibling</code> should be
92      * a {@link org.w3c.dom.Document} node,
93      * a {@link org.w3c.dom.DocumentFragment} node, or
94      * a {@link org.w3c.dom.Element} node.
95      * In other words, a node that accepts children.</p>
96      *
97      * <p>Use <code>nextSibling</code> to specify the child node
98      * where the result nodes should be inserted before.
99      * If <code>nextSibling</code> is not a sibling of <code>node</code>,
100      * then an <code>IllegalArgumentException</code> is thrown.
101      * If <code>node</code> is <code>null</code> and <code>nextSibling</code> is not <code>null</code>,
102      * then an <code>IllegalArgumentException</code> is thrown.
103      * If <code>nextSibling</code> is <code>null</code>,
104      * then the behavior is the same as calling {@link #DOMResult(Node node)},
105      * i.e. append the result nodes as the last child of the specified <code>node</code>.</p>
106      *
107      * <p><code>systemId</code> will be set to <code>null</code>.</p>
108      *
109      * @param node The DOM node that will contain the result tree.
110      * @param nextSibling The child node where the result nodes should be inserted before.
111      *
112      * @throws IllegalArgumentException If <code>nextSibling</code> is not a sibling of <code>node</code>.
113      * @throws IllegalArgumentException If <code>node</code> is <code>null</code> and <code>nextSibling</code> is not <code>null</code>.
114      *
115      * @since 1.5
116      */
117     public DOMResult(Node node, Node nextSibling) {
118         
119         // does the corrent parent/child relationship exist?
120 if (nextSibling != null) {
121             // cannot be a sibling of a null node
122 if (node == null) {
123                 throw new IllegalArgumentException ("Cannot create a DOMResult when the nextSibling is contained by the \"null\" node.");
124             }
125             
126             // nextSibling contained by node?
127 if ((node.compareDocumentPosition(nextSibling)&Node.DOCUMENT_POSITION_CONTAINED_BY)==0) {
128                 throw new IllegalArgumentException ("Cannot create a DOMResult when the nextSibling is not contained by the node.");
129             }
130         }
131
132         setNode(node);
133         setNextSibling(nextSibling);
134         setSystemId(null);
135     }
136
137     /**
138      * <p>Use a DOM node to create a new output target specifying the child node where the result nodes should be inserted before and
139      * the specified System ID.</p>
140      *
141      * <p>In practice, <code>node</code> and <code>nextSibling</code> should be
142      * a {@link org.w3c.dom.Document} node,
143      * a {@link org.w3c.dom.DocumentFragment} node, or a
144      * {@link org.w3c.dom.Element} node.
145      * In other words, a node that accepts children.</p>
146      *
147      * <p>Use <code>nextSibling</code> to specify the child node
148      * where the result nodes should be inserted before.
149      * If <code>nextSibling</code> is not a sibling of <code>node</code>,
150      * then an <code>IllegalArgumentException</code> is thrown.
151      * If <code>node</code> is <code>null</code> and <code>nextSibling</code> is not <code>null</code>,
152      * then an <code>IllegalArgumentException</code> is thrown.
153      * If <code>nextSibling</code> is <code>null</code>,
154      * then the behavior is the same as calling {@link #DOMResult(Node node, String systemId)},
155      * i.e. append the result nodes as the last child of the specified node and use the specified System ID.</p>
156      *
157      * @param node The DOM node that will contain the result tree.
158      * @param nextSibling The child node where the result nodes should be inserted before.
159      * @param systemId The system identifier which may be used in association with this node.
160      *
161      * @throws IllegalArgumentException If <code>nextSibling</code> is not a sibling of <code>node</code>.
162      * @throws IllegalArgumentException If <code>node</code> is <code>null</code> and <code>nextSibling</code> is not <code>null</code>.
163      *
164      * @since 1.5
165      */
166     public DOMResult(Node node, Node nextSibling, String systemId) {
167
168         // does the corrent parent/child relationship exist?
169 if (nextSibling != null) {
170             // cannot be a sibling of a null node
171 if (node == null) {
172                 throw new IllegalArgumentException ("Cannot create a DOMResult when the nextSibling is contained by the \"null\" node.");
173             }
174             
175             // nextSibling contained by node?
176 if ((node.compareDocumentPosition(nextSibling)&Node.DOCUMENT_POSITION_CONTAINED_BY)==0) {
177                 throw new IllegalArgumentException ("Cannot create a DOMResult when the nextSibling is not contained by the node.");
178             }
179         }
180
181         setNode(node);
182         setNextSibling(nextSibling);
183         setSystemId(systemId);
184     }
185
186     /**
187      * <p>Set the node that will contain the result DOM tree.<p>
188      *
189      * <p>In practice, the node should be
190      * a {@link org.w3c.dom.Document} node,
191      * a {@link org.w3c.dom.DocumentFragment} node, or
192      * a {@link org.w3c.dom.Element} node.
193      * In other words, a node that accepts children.</p>
194      *
195      * <p>An <code>IllegalStateException</code> is thrown if <code>nextSibling</code> is not <code>null</code> and
196      * <code>node</code> is not a parent of <code>nextSibling</code>.
197      * An <code>IllegalStateException</code> is thrown if <code>node</code> is <code>null</code> and
198      * <code>nextSibling</code> is not <code>null</code>.</p>
199      *
200      * @param node The node to which the transformation will be appended.
201      *
202      * @throws IllegalStateException If <code>nextSibling</code> is not <code>null</code> and
203      * <code>nextSibling</code> is not a child of <code>node</code>.
204      * @throws IllegalStateException If <code>node</code> is <code>null</code> and
205      * <code>nextSibling</code> is not <code>null</code>.
206      */
207     public void setNode(Node node) {
208         // does the corrent parent/child relationship exist?
209 if (nextSibling != null) {
210             // cannot be a sibling of a null node
211 if (node == null) {
212                 throw new IllegalStateException ("Cannot create a DOMResult when the nextSibling is contained by the \"null\" node.");
213             }
214             
215             // nextSibling contained by node?
216 if ((node.compareDocumentPosition(nextSibling)&Node.DOCUMENT_POSITION_CONTAINED_BY)==0) {
217                 throw new IllegalArgumentException ("Cannot create a DOMResult when the nextSibling is not contained by the node.");
218             }
219         }
220
221         this.node = node;
222     }
223
224     /**
225      * <p>Get the node that will contain the result DOM tree.</p>
226      *
227      * <p>If no node was set via
228      * {@link #DOMResult(Node node)},
229      * {@link #DOMResult(Node node, String systeId)},
230      * {@link #DOMResult(Node node, Node nextSibling)},
231      * {@link #DOMResult(Node node, Node nextSibling, String systemId)} or
232      * {@link #setNode(Node node)},
233      * then the node will be set by the transformation, and may be obtained from this method once the transformation is complete.
234      * Calling this method before the transformation will return <code>null</code>.</p>
235      *
236      * @return The node to which the transformation will be appended.
237      */
238     public Node getNode() {
239         return node;
240     }
241
242     /**
243      * <p>Set the child node before which the result nodes will be inserted.</p>
244      *
245      * <p>Use <code>nextSibling</code> to specify the child node
246      * before which the result nodes should be inserted.
247      * If <code>nextSibling</code> is not a descendant of <code>node</code>,
248      * then an <code>IllegalArgumentException</code> is thrown.
249      * If <code>node</code> is <code>null</code> and <code>nextSibling</code> is not <code>null</code>,
250      * then an <code>IllegalStateException</code> is thrown.
251      * If <code>nextSibling</code> is <code>null</code>,
252      * then the behavior is the same as calling {@link #DOMResult(Node node)},
253      * i.e. append the result nodes as the last child of the specified <code>node</code>.</p>
254      *
255      * @param nextSibling The child node before which the result nodes will be inserted.
256      *
257      * @throws IllegalArgumentException If <code>nextSibling</code> is not a descendant of <code>node</code>.
258      * @throws IllegalStateException If <code>node</code> is <code>null</code> and <code>nextSibling</code> is not <code>null</code>.
259      *
260      * @since 1.5
261      */
262     public void setNextSibling(Node nextSibling) {
263         
264         // does the corrent parent/child relationship exist?
265 if (nextSibling != null) {
266             // cannot be a sibling of a null node
267 if (node == null) {
268                 throw new IllegalStateException ("Cannot create a DOMResult when the nextSibling is contained by the \"null\" node.");
269             }
270             
271             // nextSibling contained by node?
272 if ((node.compareDocumentPosition(nextSibling)&Node.DOCUMENT_POSITION_CONTAINED_BY)==0) {
273                 throw new IllegalArgumentException ("Cannot create a DOMResult when the nextSibling is not contained by the node.");
274             }
275         }
276
277         this.nextSibling = nextSibling;
278     }
279
280     /**
281      * <p>Get the child node before which the result nodes will be inserted.</p>
282      *
283      * <p>If no node was set via
284      * {@link #DOMResult(Node node, Node nextSibling)},
285      * {@link #DOMResult(Node node, Node nextSibling, String systemId)} or
286      * {@link #setNextSibling(Node nextSibling)},
287      * then <code>null</code> will be returned.</p>
288      *
289      * @return The child node before which the result nodes will be inserted.
290      *
291      * @since 1.5
292      */
293     public Node getNextSibling() {
294         return nextSibling;
295     }
296
297     /**
298      * <p>Set the systemId that may be used in association with the node.</p>
299      *
300      * @param systemId The system identifier as a URI string.
301      */
302     public void setSystemId(String systemId) {
303         this.systemId = systemId;
304     }
305
306     /**
307      * <p>Get the System Identifier.</p>
308      *
309      * <p>If no System ID was set via
310      * {@link #DOMResult(Node node, String systemId)},
311      * {@link #DOMResult(Node node, Node nextSibling, String systemId)} or
312      * {@link #setSystemId(String systemId)},
313      * then <code>null</code> will be returned.</p>
314      *
315      * @return The system identifier.
316      */
317     public String getSystemId() {
318         return systemId;
319     }
320
321     //////////////////////////////////////////////////////////////////////
322 // Internal state.
323 //////////////////////////////////////////////////////////////////////
324
325     /**
326      * <p>The node to which the transformation will be appended.</p>
327      */
328     private Node node = null;
329
330     /**
331      * <p>The child node before which the result nodes will be inserted.</p>
332      *
333      * @since 1.5
334      */
335     private Node nextSibling = null;
336
337     /**
338      * <p>The System ID that may be used in association with the node.</p>
339      */
340     private String systemId = null;
341 }
342

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags