← Back to branch summary

~ubuntu-branches/ubuntu/precise/xom/precise

« back to all changes in this revision

Viewing changes to src/nu/xom/Comment.java

  • Committer: Bazaar Package Importer
  • Author(s): Varun Hiremath
  • Date: 2007-11-25 15:50:40 UTC
  • Revision ID: james.westby@ubuntu.com-20071125155040-r75ikcqf1vu0cei7
Tags: upstream-1.1
Import upstream version 1.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/nu/xom/Comment.java
 
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 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 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 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 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 data) {
 
111
        _setValue(data);
 
112
    }
 
113
 
 
114
 
 
115
    private void _setValue(String 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(
 
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 toXML() {
 
207
        StringBuffer result = new StringBuffer("<!--");
 
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 toString() {
 
225
        
 
226
        String 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
}