Text


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:  $";
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 }
272
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags