Source code: org/jdom/Content.java
1 /*--
2
3 $Id: Content.java,v 1.5 2004/09/07 06:37:20 jhunter Exp $
4
5 Copyright (C) 2004 Jason Hunter & Brett McLaughlin.
6 All rights reserved.
7
8 Redistribution and use in source and binary forms, with or without
9 modification, are permitted provided that the following conditions
10 are met:
11
12 1. Redistributions of source code must retain the above copyright
13 notice, this list of conditions, and the following disclaimer.
14
15 2. Redistributions in binary form must reproduce the above copyright
16 notice, this list of conditions, and the disclaimer that follows
17 these conditions in the documentation and/or other materials
18 provided with the distribution.
19
20 3. The name "JDOM" must not be used to endorse or promote products
21 derived from this software without prior written permission. For
22 written permission, please contact <request_AT_jdom_DOT_org>.
23
24 4. Products derived from this software may not be called "JDOM", nor
25 may "JDOM" appear in their name, without prior written permission
26 from the JDOM Project Management <request_AT_jdom_DOT_org>.
27
28 In addition, we request (but do not require) that you include in the
29 end-user documentation provided with the redistribution and/or in the
30 software itself an acknowledgement equivalent to the following:
31 "This product includes software developed by the
32 JDOM Project (http://www.jdom.org/)."
33 Alternatively, the acknowledgment may be graphical using the logos
34 available at http://www.jdom.org/images/logos.
35
36 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39 DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
40 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47 SUCH DAMAGE.
48
49 This software consists of voluntary contributions made by many
50 individuals on behalf of the JDOM Project and was originally
51 created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
52 Brett McLaughlin <brett_AT_jdom_DOT_org>. For more information
53 on the JDOM Project, please see <http://www.jdom.org/>.
54
55 */
56
57 package org.jdom;
58
59 import java.io.*;
60
61 /**
62 * Superclass for JDOM objects which can be legal child content
63 * of {@link org.jdom.Parent} nodes.
64 *
65 * @see org.jdom.Comment
66 * @see org.jdom.DocType
67 * @see org.jdom.Element
68 * @see org.jdom.EntityRef
69 * @see org.jdom.Parent
70 * @see org.jdom.ProcessingInstruction
71 * @see org.jdom.Text
72 *
73 * @author Bradley S. Huffman
74 * @author Jason Hunter
75 * @version $Revision: 1.5 $, $Date: 2004/09/07 06:37:20 $
76 */
77 public abstract class Content implements Cloneable, Serializable {
78
79 protected Parent parent = null;
80
81 protected Content() {}
82
83 /**
84 * Detaches this child from its parent or does nothing if the child
85 * has no parent.
86 *
87 * @return this child detached
88 */
89 public Content detach() {
90 if (parent != null) {
91 parent.removeContent(this);
92 }
93 return this;
94 }
95
96 /**
97 * Return this child's parent, or null if this child is currently
98 * not attached. The parent can be either an {@link Element}
99 * or a {@link Document}.
100 *
101 * @return this child's parent or null if none
102 */
103 public Parent getParent() {
104 return parent;
105 }
106
107 /**
108 * A convenience method that returns any parent element for this element,
109 * or null if the element is unattached or is a root element. This was the
110 * original behavior of getParent() in JDOM Beta 9 which began returning
111 * Parent in Beta 10. This method provides a convenient upgrade path for
112 * JDOM Beta 10 and 1.0 users.
113 *
114 * @return the containing Element or null if unattached or a root element
115 */
116 public Element getParentElement() {
117 Parent parent = getParent();
118 return (Element) ((parent instanceof Element) ? parent : null);
119 }
120
121 /**
122 * Sets the parent of this Content. The caller is responsible for removing
123 * any pre-existing parentage.
124 *
125 * @param parent new parent element
126 * @return the target element
127 */
128 protected Content setParent(Parent parent) {
129 this.parent = parent;
130 return this;
131 }
132
133 /**
134 * Return this child's owning document or null if the branch containing
135 * this child is currently not attached to a document.
136 *
137 * @return this child's owning document or null if none
138 */
139 public Document getDocument() {
140 if (parent == null) return null;
141 return parent.getDocument();
142 }
143
144
145 /**
146 * Returns the XPath 1.0 string value of this child.
147 *
148 * @return xpath string value of this child.
149 */
150 public abstract String getValue();
151
152 /**
153 * Returns a deep, unattached copy of this child and its descendants
154 * detached from any parent or document.
155 *
156 * @return a detached deep copy of this child and descendants
157 */
158 public Object clone() {
159 try {
160 Content c = (Content)super.clone();
161 c.parent = null;
162 return c;
163 } catch (CloneNotSupportedException e) {
164 //Can not happen ....
165 //e.printStackTrace();
166 return null;
167 }
168 }
169
170 /**
171 * This tests for equality of this Content object to the supplied object.
172 * Content items are considered equal only if they are referentially equal
173 * (i.e. the same object). User code may choose to compare objects
174 * based on their properties instead.
175 *
176 * @param ob <code>Object</code> to compare to.
177 * @return <code>boolean</code> - whether the <code>Content</code> is
178 * equal to the supplied <code>Object</code>.
179 */
180 public final boolean equals(Object ob) {
181 return (ob == this);
182 }
183
184 /**
185 * This returns the hash code for this <code>Content</code> item.
186 *
187 * @return <code>int</code> - hash code.
188 */
189 public final int hashCode() {
190 return super.hashCode();
191 }
192 }