Source code: org/jdom/Text.java
1 /*--
2
3 $Id: Text.java,v 1.24 2004/02/27 11:32:57 jhunter Exp $
4
5 Copyright (C) 2000-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 /**
60 * Character-based XML content. Provides a modular, parentable method of
61 * representing text. Text makes no guarantees about the underlying textual
62 * representation of character data, but does expose that data as a Java String.
63 *
64 * @version $Revision: 1.24 $, $Date: 2004/02/27 11:32:57 $
65 * @author Brett McLaughlin
66 * @author Jason Hunter
67 * @author Bradley S. Huffman
68 */
69 public class Text extends Content {
70
71 private static final String CVS_ID =
72 "@(#) $RCSfile: Text.java,v $ $Revision: 1.24 $ $Date: 2004/02/27 11:32:57 $ $Name: jdom_1_0 $";
73
74 static final String EMPTY_STRING = "";
75
76 /** The actual character content */
77 // XXX See http://www.servlets.com/archive/servlet/ReadMsg?msgId=8612
78 // from elharo for a description of why Java characters may not suffice
79 // long term
80 protected String value;
81
82 /**
83 * This is the protected, no-args constructor standard in all JDOM
84 * classes. It allows subclassers to get a raw instance with no
85 * initialization.
86 */
87 protected Text() { }
88
89 /**
90 * This constructor creates a new <code>Text</code> node, with the
91 * supplied string value as it's character content.
92 *
93 * @param str the node's character content.
94 * @throws IllegalDataException if <code>str</code> contains an
95 * illegal character such as a vertical tab (as determined
96 * by {@link org.jdom.Verifier#checkCharacterData})
97 */
98 public Text(String str) {
99 setText(str);
100 }
101
102 /**
103 * This returns the value of this <code>Text</code> node as a Java
104 * <code>String</code>.
105 *
106 * @return <code>String</code> - character content of this node.
107 */
108 public String getText() {
109 return value;
110 }
111
112 /**
113 * This returns the textual content with all surrounding whitespace
114 * removed. If only whitespace exists, the empty string is returned.
115 *
116 * @return trimmed text content or empty string
117 */
118 public String getTextTrim() {
119 return getText().trim();
120 }
121
122 /**
123 * This returns the textual content with all surrounding whitespace
124 * removed and internal whitespace normalized to a single space. If
125 * only whitespace exists, the empty string is returned.
126 *
127 * @return normalized text content or empty string
128 */
129 public String getTextNormalize() {
130 return normalizeString(getText());
131 }
132
133 /**
134 * This returns a new string with all surrounding whitespace
135 * removed and internal whitespace normalized to a single space. If
136 * only whitespace exists, the empty string is returned.
137 * <p>
138 * Per XML 1.0 Production 3 whitespace includes: #x20, #x9, #xD, #xA
139 * </p>
140 *
141 * @param str string to be normalized.
142 * @return normalized string or empty string
143 */
144 public static String normalizeString(String str) {
145 if (str == null)
146 return EMPTY_STRING;
147
148 char[] c = str.toCharArray();
149 char[] n = new char[c.length];
150 boolean white = true;
151 int pos = 0;
152 for (int i = 0; i < c.length; i++) {
153 if (" \t\n\r".indexOf(c[i]) != -1) {
154 if (!white) {
155 n[pos++] = ' ';
156 white = true;
157 }
158 }
159 else {
160 n[pos++] = c[i];
161 white = false;
162 }
163 }
164 if (white && pos > 0) {
165 pos--;
166 }
167 return new String(n, 0, pos);
168 }
169
170 /**
171 * This will set the value of this <code>Text</code> node.
172 *
173 * @param str value for node's content.
174 * @return the object on which the method was invoked
175 * @throws IllegalDataException if <code>str</code> contains an
176 * illegal character such as a vertical tab (as determined
177 * by {@link org.jdom.Verifier#checkCharacterData})
178 */
179 public Text setText(String str) {
180 String reason;
181
182 if (str == null) {
183 value = EMPTY_STRING;
184 return this;
185 }
186
187 if ((reason = Verifier.checkCharacterData(str)) != null) {
188 throw new IllegalDataException(str, "character content", reason);
189 }
190 value = str;
191 return this;
192 }
193
194 /**
195 * This will append character content to whatever content already
196 * exists within this <code>Text</code> node.
197 *
198 * @param str character content to append.
199 * @throws IllegalDataException if <code>str</code> contains an
200 * illegal character such as a vertical tab (as determined
201 * by {@link org.jdom.Verifier#checkCharacterData})
202 */
203 public void append(String str) {
204 String reason;
205
206 if (str == null) {
207 return;
208 }
209 if ((reason = Verifier.checkCharacterData(str)) != null) {
210 throw new IllegalDataException(str, "character content", reason);
211 }
212
213 if (str == EMPTY_STRING)
214 value = str;
215 else value += str;
216 }
217
218 /**
219 * This will append the content of another <code>Text</code> node
220 * to this node.
221 *
222 * @param text Text node to append.
223 */
224 public void append(Text text) {
225 if (text == null) {
226 return;
227 }
228 value += text.getText();
229 }
230
231 /**
232 * Returns the XPath 1.0 string value of this element, which is the
233 * text itself.
234 *
235 * @return the text
236 */
237 public String getValue() {
238 return value;
239 }
240
241 /**
242 * This returns a <code>String</code> representation of the
243 * <code>Text</code> node, suitable for debugging. If the XML
244 * representation of the <code>Text</code> node is desired,
245 * either <code>{@link #getText}</code> or
246 * {@link org.jdom.output.XMLOutputter#outputString(Text)}</code>
247 * should be used.
248 *
249 * @return <code>String</code> - information about this node.
250 */
251 public String toString() {
252 return new StringBuffer(64)
253 .append("[Text: ")
254 .append(getText())
255 .append("]")
256 .toString();
257 }
258
259 /**
260 * This will return a clone of this <code>Text</code> node, with the
261 * same character content, but no parent.
262 *
263 * @return <code>Text</code> - cloned node.
264 */
265 public Object clone() {
266 Text text = (Text)super.clone();
267 text.value = value;
268 return text;
269 }
270
271 }