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   attrType, String   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   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   uri, String   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   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   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   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   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   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   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   getType(String   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   getType(String   uri, String   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   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   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   getValue(String   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   getValue(String   uri, String   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   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   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   uri, String   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags