KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > xerces > xni > XMLAttributes


1 /*
2  * Copyright 2000-2002,2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16
17 package org.apache.xerces.xni;
18
19 /**
20  * The XMLAttributes interface defines a collection of attributes for
21  * an element. In the parser, the document source would scan the entire
22  * start element and collect the attributes. The attributes are
23  * communicated to the document handler in the startElement method.
24  * <p>
25  * The attributes are read-write so that subsequent stages in the document
26  * pipeline can modify the values or change the attributes that are
27  * propogated to the next stage.
28  *
29  * @see XMLDocumentHandler#startElement
30  *
31  * @author Andy Clark, IBM
32  *
33  * @version $Id: XMLAttributes.java,v 1.11 2004/10/03 21:53:25 mrglavas Exp $
34  */

35 public interface XMLAttributes {
36
37     //
38
// XMLAttributes methods
39
//
40

41     /**
42      * Adds an attribute. The attribute's non-normalized value of the
43      * attribute will have the same value as the attribute value until
44      * set using the <code>setNonNormalizedValue</code> method. Also,
45      * the added attribute will be marked as specified in the XML instance
46      * document unless set otherwise using the <code>setSpecified</code>
47      * method.
48      * <p>
49      * <strong>Note:</strong> If an attribute of the same name already
50      * exists, the old values for the attribute are replaced by the new
51      * values.
52      *
53      * @param attrName The attribute name.
54      * @param attrType The attribute type. The type name is determined by
55      * the type specified for this attribute in the DTD.
56      * For example: "CDATA", "ID", "NMTOKEN", etc. However,
57      * attributes of type enumeration will have the type
58      * value specified as the pipe ('|') separated list of
59      * the enumeration values prefixed by an open
60      * parenthesis and suffixed by a close parenthesis.
61      * For example: "(true|false)".
62      * @param attrValue The attribute value.
63      *
64      * @return Returns the attribute index.
65      *
66      * @see #setNonNormalizedValue
67      * @see #setSpecified
68      */

69     public int addAttribute(QName attrName, String JavaDoc attrType, String JavaDoc attrValue);
70
71     /**
72      * Removes all of the attributes. This method will also remove all
73      * entities associated to the attributes.
74      */

75     public void removeAllAttributes();
76
77     /**
78      * Removes the attribute at the specified index.
79      * <p>
80      * <strong>Note:</strong> This operation changes the indexes of all
81      * attributes following the attribute at the specified index.
82      *
83      * @param attrIndex The attribute index.
84      */

85     public void removeAttributeAt(int attrIndex);
86
87     /**
88      * Returns the number of attributes in the list.
89      * <p>
90      * Once you know the number of attributes, you can iterate
91      * through the list.
92      *
93      * @see #getURI(int)
94      * @see #getLocalName(int)
95      * @see #getQName(int)
96      * @see #getType(int)
97      * @see #getValue(int)
98      */

99     public int getLength();
100
101     /**
102      * Look up the index of an attribute by XML 1.0 qualified name.
103      *
104      * @param qName The qualified (prefixed) name.
105      *
106      * @return The index of the attribute, or -1 if it does not
107      * appear in the list.
108      */

109     public int getIndex(String JavaDoc qName);
110
111     /**
112      * Look up the index of an attribute by Namespace name.
113      *
114      * @param uri The Namespace URI, or the empty string if
115      * the name has no Namespace URI.
116      * @param localPart The attribute's local name.
117      *
118      * @return The index of the attribute, or -1 if it does not
119      * appear in the list.
120      */

121     public int getIndex(String JavaDoc uri, String JavaDoc localPart);
122
123     /**
124      * Sets the name of the attribute at the specified index.
125      *
126      * @param attrIndex The attribute index.
127      * @param attrName The new attribute name.
128      */

129     public void setName(int attrIndex, QName attrName);
130
131     /**
132      * Sets the fields in the given QName structure with the values
133      * of the attribute name at the specified index.
134      *
135      * @param attrIndex The attribute index.
136      * @param attrName The attribute name structure to fill in.
137      */

138     public void getName(int attrIndex, QName attrName);
139
140     /**
141      * Returns the prefix of the attribute at the specified index.
142      *
143      * @param index The index of the attribute.
144      */

145     public String JavaDoc getPrefix(int index);
146
147     /**
148      * Look up an attribute's Namespace URI by index.
149      *
150      * @param index The attribute index (zero-based).
151      *
152      * @return The Namespace URI, or the empty string if none
153      * is available, or null if the index is out of
154      * range.
155      *
156      * @see #getLength
157      */

158     public String JavaDoc getURI(int index);
159     
160     /**
161      * Look up an attribute's local name by index.
162      *
163      * @param index The attribute index (zero-based).
164      *
165      * @return The local name, or the empty string if Namespace
166      * processing is not being performed, or null
167      * if the index is out of range.
168      *
169      * @see #getLength
170      */

171     public String JavaDoc getLocalName(int index);
172
173     /**
174      * Look up an attribute's XML 1.0 qualified name by index.
175      *
176      * @param index The attribute index (zero-based).
177      *
178      * @return The XML 1.0 qualified name, or the empty string
179      * if none is available, or null if the index
180      * is out of range.
181      *
182      * @see #getLength
183      */

184     public String JavaDoc getQName(int index);
185
186     /**
187      * Sets the type of the attribute at the specified index.
188      *
189      * @param attrIndex The attribute index.
190      * @param attrType The attribute type. The type name is determined by
191      * the type specified for this attribute in the DTD.
192      * For example: "CDATA", "ID", "NMTOKEN", etc. However,
193      * attributes of type enumeration will have the type
194      * value specified as the pipe ('|') separated list of
195      * the enumeration values prefixed by an open
196      * parenthesis and suffixed by a close parenthesis.
197      * For example: "(true|false)".
198      */

199     public void setType(int attrIndex, String JavaDoc attrType);
200
201     /**
202      * Look up an attribute's type by index.
203      * <p>
204      * The attribute type is one of the strings "CDATA", "ID",
205      * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
206      * or "NOTATION" (always in upper case).
207      * <p>
208      * If the parser has not read a declaration for the attribute,
209      * or if the parser does not report attribute types, then it must
210      * return the value "CDATA" as stated in the XML 1.0 Recommentation
211      * (clause 3.3.3, "Attribute-Value Normalization").
212      * <p>
213      * For an enumerated attribute that is not a notation, the
214      * parser will report the type as "NMTOKEN".
215      *
216      * @param index The attribute index (zero-based).
217      *
218      * @return The attribute's type as a string, or null if the
219      * index is out of range.
220      *
221      * @see #getLength
222      */

223     public String JavaDoc getType(int index);
224
225     /**
226      * Look up an attribute's type by XML 1.0 qualified name.
227      * <p>
228      * See {@link #getType(int) getType(int)} for a description
229      * of the possible types.
230      *
231      * @param qName The XML 1.0 qualified name.
232      *
233      * @return The attribute type as a string, or null if the
234      * attribute is not in the list or if qualified names
235      * are not available.
236      */

237     public String JavaDoc getType(String JavaDoc qName);
238
239     /**
240      * Look up an attribute's type by Namespace name.
241      * <p>
242      * See {@link #getType(int) getType(int)} for a description
243      * of the possible types.
244      *
245      * @param uri The Namespace URI, or the empty String if the
246      * name has no Namespace URI.
247      * @param localName The local name of the attribute.
248      *
249      * @return The attribute type as a string, or null if the
250      * attribute is not in the list or if Namespace
251      * processing is not being performed.
252      */

253     public String JavaDoc getType(String JavaDoc uri, String JavaDoc localName);
254
255     /**
256      * Sets the value of the attribute at the specified index. This
257      * method will overwrite the non-normalized value of the attribute.
258      *
259      * @param attrIndex The attribute index.
260      * @param attrValue The new attribute value.
261      *
262      * @see #setNonNormalizedValue
263      */

264     public void setValue(int attrIndex, String JavaDoc attrValue);
265
266     /**
267      * Look up an attribute's value by index.
268      * <p>
269      * If the attribute value is a list of tokens (IDREFS,
270      * ENTITIES, or NMTOKENS), the tokens will be concatenated
271      * into a single string with each token separated by a
272      * single space.
273      *
274      * @param index The attribute index (zero-based).
275      *
276      * @return The attribute's value as a string, or null if the
277      * index is out of range.
278      *
279      * @see #getLength
280      */

281     public String JavaDoc getValue(int index);
282
283     /**
284      * Look up an attribute's value by XML 1.0 qualified name.
285      * <p>
286      * See {@link #getValue(int) getValue(int)} for a description
287      * of the possible values.
288      *
289      * @param qName The XML 1.0 qualified name.
290      *
291      * @return The attribute value as a string, or null if the
292      * attribute is not in the list or if qualified names
293      * are not available.
294      */

295     public String JavaDoc getValue(String JavaDoc qName);
296
297     /**
298      * Look up an attribute's value by Namespace name.
299      * <p>
300      * See {@link #getValue(int) getValue(int)} for a description
301      * of the possible values.
302      *
303      * @param uri The Namespace URI, or the empty String if the
304      * name has no Namespace URI.
305      * @param localName The local name of the attribute.
306      *
307      * @return The attribute value as a string, or null if the
308      * attribute is not in the list.
309      */

310     public String JavaDoc getValue(String JavaDoc uri, String JavaDoc localName);
311
312     /**
313      * Sets the non-normalized value of the attribute at the specified
314      * index.
315      *
316      * @param attrIndex The attribute index.
317      * @param attrValue The new non-normalized attribute value.
318      */

319     public void setNonNormalizedValue(int attrIndex, String JavaDoc attrValue);
320
321     /**
322      * Returns the non-normalized value of the attribute at the specified
323      * index. If no non-normalized value is set, this method will return
324      * the same value as the <code>getValue(int)</code> method.
325      *
326      * @param attrIndex The attribute index.
327      */

328     public String JavaDoc getNonNormalizedValue(int attrIndex);
329
330     /**
331      * Sets whether an attribute is specified in the instance document
332      * or not.
333      *
334      * @param attrIndex The attribute index.
335      * @param specified True if the attribute is specified in the instance
336      * document.
337      */

338     public void setSpecified(int attrIndex, boolean specified);
339
340     /**
341      * Returns true if the attribute is specified in the instance document.
342      *
343      * @param attrIndex The attribute index.
344      */

345     public boolean isSpecified(int attrIndex);
346
347
348     /**
349      * Look up an augmentation by attribute's index.
350      *
351      * @param attributeIndex The attribute index.
352      * @return Augmentations
353      */

354     public Augmentations getAugmentations (int attributeIndex);
355
356     /**
357      * Look up an augmentation by namespace name.
358      *
359      * @param uri The Namespace URI, or the empty string if
360      * the name has no Namespace URI.
361      * @param localPart
362      * @return Augmentations
363      */

364     public Augmentations getAugmentations (String JavaDoc uri, String JavaDoc localPart);
365
366
367     /**
368      * Look up an augmentation by XML 1.0 qualified name.
369      * <p>
370      *
371      * @param qName The XML 1.0 qualified name.
372      *
373      * @return Augmentations
374      *
375      */

376     public Augmentations getAugmentations(String JavaDoc qName);
377
378
379     /**
380      * Sets the augmentations of the attribute at the specified index.
381      *
382      * @param attrIndex The attribute index.
383      * @param augs The augmentations.
384      */

385     public void setAugmentations(int attrIndex, Augmentations augs);
386
387
388 } // interface XMLAttributes
389
Popular Tags