KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > nu > xom > Comment


1 /* Copyright 2002-2005 Elliotte Rusty Harold
2    
3    This library is free software; you can redistribute it and/or modify
4    it under the terms of version 2.1 of the GNU Lesser General Public
5    License as published by the Free Software Foundation.
6    
7    This library is distributed in the hope that it will be useful,
8    but WITHOUT ANY WARRANTY; without even the implied warranty of
9    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10    GNU Lesser General Public License for more details.
11    
12    You should have received a copy of the GNU Lesser General Public
13    License along with this library; if not, write to the
14    Free Software Foundation, Inc., 59 Temple Place, Suite 330,
15    Boston, MA 02111-1307 USA
16    
17    You can contact Elliotte Rusty Harold by sending e-mail to
18    elharo@metalab.unc.edu. Please include the word "XOM" in the
19    subject line. The XOM home page is located at http://www.xom.nu/
20 */
21
22 package nu.xom;
23
24 /**
25  * <p>
26  * This class represents an XML comment such as
27  * <code>&lt;-- This is a comment--></code>.
28  * A comment node cannot have any child nodes.
29  * It can be a child of an <code>Element</code>
30  * or a <code>Document</code>.
31  * It has essentially no internal substructure.
32  * </p>
33  *
34  * @author Elliotte Rusty Harold
35  * @version 1.0
36  *
37  */
38 public class Comment extends Node {
39
40     
41     private String JavaDoc data;
42
43     /**
44      * <p>
45      * Creates a new <code>Comment</code> object from string data.
46      * The data is checked for legality according to XML 1.0 rules.
47      * Illegal characters such as the form feed and null are not
48      * allowed. Furthermore, the two hyphen string "--" is not allowed;
49      * and the last character of the comment may not be a hyphen.
50      * </p>
51      *
52      * @param data the initial text of the comment
53      */
54     public Comment(String JavaDoc data) {
55         _setValue(data);
56     }
57
58     
59     /**
60      * <p>
61      * Creates a new comment that's a copy of its argument.
62      * The copy has the same data but no parent node.
63      * </p>
64      *
65      * @param comment the comment to copy
66      */
67     public Comment(Comment comment) {
68         this.data = comment.data;
69     }
70     
71     
72     private Comment() {}
73     
74     static Comment build(String JavaDoc data) {
75         Comment result = new Comment();
76         result.data = data;
77         return result;
78     }
79
80     
81     /**
82      * <p>
83      * Returns the value of this comment as defined by XPath 1.0.
84      * The XPath string-value of a comment node is the string
85      * content of the node, not including the initial
86      * <code>&lt;--</code> and closing <code>--&gt;</code>.
87      * </p>
88      *
89      * @return the content of the comment
90      */
91     public final String JavaDoc getValue() {
92         return data;
93     }
94
95     
96     /**
97      * <p>
98      * Sets the content of this <code>Comment</code> object
99      * to the specified string.
100      * This string is checked for legality according to XML 1.0 rules.
101      * Characters that can be serialized such as &lt; and &amp;
102      * are allowed. However, illegal characters such as the form feed
103      * and unmatched halves of surrogate pairs are not allowed.
104      * Furthermore, the string may not contain a double hyphen
105      * (<code>--</code>) and may not end with a hyphen.
106      * </p>
107      *
108      * @param data the text to install in the comment
109      */
110     public void setValue(String JavaDoc data) {
111         _setValue(data);
112     }
113
114
115     private void _setValue(String JavaDoc data) {
116         
117         if (data == null) data = "";
118         else {
119             Verifier.checkPCDATA(data);
120             
121             if (data.indexOf("--") != -1) {
122                 IllegalDataException ex = new IllegalDataException(
123                  "Comment data contains a double hyphen (--).");
124                 ex.setData(data);
125                 throw ex;
126             }
127     
128             if (data.indexOf('\r') != -1) {
129                 IllegalDataException ex = new IllegalDataException(
130                  "Comment data cannot contain carriage returns.");
131                 ex.setData(data);
132                 throw ex;
133             }
134     
135             if (data.endsWith("-")) {
136                 IllegalDataException ex = new IllegalDataException(
137                  "Comment data ends with a hyphen.");
138                 ex.setData(data);
139                 throw ex;
140             }
141             
142         }
143         this.data = data;
144         
145     }
146
147
148     /**
149      * <p>
150      * Throws <code>IndexOutOfBoundsException</code> because
151      * comments do not have children.
152      * </p>
153      *
154      * @return never returns because comments do not have children;
155      * Always throws an exception.
156      *
157      * @param position the index of the child node to return
158      *
159      * @throws IndexOutOfBoundsException because comments
160      * do not have children
161      */
162     public final Node getChild(int position) {
163         throw new IndexOutOfBoundsException JavaDoc(
164           "LeafNodes do not have children");
165     }
166
167     
168     /**
169      * <p>
170      * Returns 0 because comments do not have children.
171      * </p>
172      *
173      * @return zero
174      */
175     public final int getChildCount() {
176         return 0;
177     }
178     
179     
180     /**
181      * <p>
182      * Returns a deep copy of this <code>Comment</code> object
183      * which contains the same text, but does not have any parent.
184      * Thus, it can be inserted into a different document.
185      * </p>
186      *
187      * @return a deep copy of this <code>Comment</code>
188      * that is not part of a document
189      *
190      */
191     public Node copy() {
192         return new Comment(data);
193     }
194
195     
196     /**
197      * <p>
198      * Returns a <code>String</code> containing the actual XML
199      * form of the comment;
200      * for example, <code>&lt;--This is a comment--&gt;</code>.
201      * </p>
202      *
203      * @return a <code>String</code> containing a well-formed
204      * XML comment
205      */
206     public final String JavaDoc toXML() {
207         StringBuffer JavaDoc result = new StringBuffer JavaDoc("<!--");
208         result.append(data);
209         result.append("-->");
210         return result.toString();
211     }
212
213
214     /**
215      * <p>
216      * Returns a string form of the comment suitable for debugging
217      * and diagnosis. It deliberately does not return an actual
218      * XML comment.
219      * </p>
220      *
221      * @return a representation of the <code>Comment</code>
222      * as a <code>String</code>
223      */
224     public final String JavaDoc toString() {
225         
226         String JavaDoc value = getValue();
227         if (value.length() <= 40) {
228             return "[" + getClass().getName() + ": "
229               + Text.escapeLineBreaksAndTruncate(value) + "]";
230         }
231         
232         return "[" + getClass().getName() + ": "
233           + Text.escapeLineBreaksAndTruncate(value.substring(0, 35)) + "...]";
234         
235     }
236
237     
238     boolean isComment() {
239         return true;
240     }
241     
242     
243 }
244
Popular Tags