View Javadoc
1   /*
2    * reserved comment block
3    * DO NOT REMOVE OR ALTER!
4    */
5   /*
6    * The Apache Software License, Version 1.1
7    *
8    *
9    * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
10   * reserved.
11   *
12   * Redistribution and use in source and binary forms, with or without
13   * modification, are permitted provided that the following conditions
14   * are met:
15   *
16   * 1. Redistributions of source code must retain the above copyright
17   *    notice, this list of conditions and the following disclaimer.
18   *
19   * 2. Redistributions in binary form must reproduce the above copyright
20   *    notice, this list of conditions and the following disclaimer in
21   *    the documentation and/or other materials provided with the
22   *    distribution.
23   *
24   * 3. The end-user documentation included with the redistribution,
25   *    if any, must include the following acknowledgment:
26   *       "This product includes software developed by the
27   *        Apache Software Foundation (http://www.apache.org/)."
28   *    Alternately, this acknowledgment may appear in the software itself,
29   *    if and wherever such third-party acknowledgments normally appear.
30   *
31   * 4. The names "Xerces" and "Apache Software Foundation" must
32   *    not be used to endorse or promote products derived from this
33   *    software without prior written permission. For written
34   *    permission, please contact apache@apache.org.
35   *
36   * 5. Products derived from this software may not be called "Apache",
37   *    nor may "Apache" appear in their name, without prior written
38   *    permission of the Apache Software Foundation.
39   *
40   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
41   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
42   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
43   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
44   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
46   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
47   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
48   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
49   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
50   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
51   * SUCH DAMAGE.
52   * ====================================================================
53   *
54   * This software consists of voluntary contributions made by many
55   * individuals on behalf of the Apache Software Foundation and was
56   * originally based on software copyright (c) 1999, International
57   * Business Machines, Inc., http://www.apache.org.  For more
58   * information on the Apache Software Foundation, please see
59   * <http://www.apache.org/>.
60   */
61  
62  package com.sun.org.apache.xerces.internal.xni;
63  
64  /**
65   * The XMLAttributes interface defines a collection of attributes for
66   * an element. In the parser, the document source would scan the entire
67   * start element and collect the attributes. The attributes are
68   * communicated to the document handler in the startElement method.
69   * <p>
70   * The attributes are read-write so that subsequent stages in the document
71   * pipeline can modify the values or change the attributes that are
72   * propogated to the next stage.
73   *
74   * @see XMLDocumentHandler#startElement
75   *
76   * @author Andy Clark, IBM
77   *
78   */
79  public interface XMLAttributes {
80  
81      //
82      // XMLAttributes methods
83      //
84  
85      /**
86       * Adds an attribute. The attribute's non-normalized value of the
87       * attribute will have the same value as the attribute value until
88       * set using the <code>setNonNormalizedValue</code> method. Also,
89       * the added attribute will be marked as specified in the XML instance
90       * document unless set otherwise using the <code>setSpecified</code>
91       * method.
92       * <p>
93       * <strong>Note:</strong> If an attribute of the same name already
94       * exists, the old values for the attribute are replaced by the new
95       * values.
96       *
97       * @param attrName  The attribute name.
98       * @param attrType  The attribute type. The type name is determined by
99       *                  the type specified for this attribute in the DTD.
100      *                  For example: "CDATA", "ID", "NMTOKEN", etc. However,
101      *                  attributes of type enumeration will have the type
102      *                  value specified as the pipe ('|') separated list of
103      *                  the enumeration values prefixed by an open
104      *                  parenthesis and suffixed by a close parenthesis.
105      *                  For example: "(true|false)".
106      * @param attrValue The attribute value.
107      *
108      * @return Returns the attribute index.
109      *
110      * @see #setNonNormalizedValue
111      * @see #setSpecified
112      */
113     public int addAttribute(QName attrName, String attrType, String attrValue);
114 
115     /**
116      * Removes all of the attributes. This method will also remove all
117      * entities associated to the attributes.
118      */
119     public void removeAllAttributes();
120 
121     /**
122      * Removes the attribute at the specified index.
123      * <p>
124      * <strong>Note:</strong> This operation changes the indexes of all
125      * attributes following the attribute at the specified index.
126      *
127      * @param attrIndex The attribute index.
128      */
129     public void removeAttributeAt(int attrIndex);
130 
131     /**
132      * Returns the number of attributes in the list.
133      * <p>
134      * Once you know the number of attributes, you can iterate
135      * through the list.
136      *
137      * @see #getURI(int)
138      * @see #getLocalName(int)
139      * @see #getQName(int)
140      * @see #getType(int)
141      * @see #getValue(int)
142      */
143     public int getLength();
144 
145     /**
146      * Look up the index of an attribute by XML 1.0 qualified name.
147      *
148      * @param qName The qualified (prefixed) name.
149      *
150      * @return The index of the attribute, or -1 if it does not
151      *         appear in the list.
152      */
153     public int getIndex(String qName);
154 
155     /**
156      * Look up the index of an attribute by Namespace name.
157      *
158      * @param uri       The Namespace URI, or the empty string if
159      *                  the name has no Namespace URI.
160      * @param localName The attribute's local name.
161      *
162      * @return The index of the attribute, or -1 if it does not
163      *         appear in the list.
164      */
165     public int getIndex(String uri, String localPart);
166 
167     /**
168      * Sets the name of the attribute at the specified index.
169      *
170      * @param attrIndex The attribute index.
171      * @param attrName  The new attribute name.
172      */
173     public void setName(int attrIndex, QName attrName);
174 
175     /**
176      * Sets the fields in the given QName structure with the values
177      * of the attribute name at the specified index.
178      *
179      * @param attrIndex The attribute index.
180      * @param attrName  The attribute name structure to fill in.
181      */
182     public void getName(int attrIndex, QName attrName);
183 
184     /**
185      * Returns the prefix of the attribute at the specified index.
186      *
187      * @param index The index of the attribute.
188      */
189     public String getPrefix(int index);
190 
191     /**
192      * Look up an attribute's Namespace URI by index.
193      *
194      * @param index The attribute index (zero-based).
195      *
196      * @return The Namespace URI, or the empty string if none
197      *         is available, or null if the index is out of
198      *         range.
199      *
200      * @see #getLength
201      */
202     public String getURI(int index);
203 
204     /**
205      * Look up an attribute's local name by index.
206      *
207      * @param index The attribute index (zero-based).
208      *
209      * @return The local name, or the empty string if Namespace
210      *         processing is not being performed, or null
211      *         if the index is out of range.
212      *
213      * @see #getLength
214      */
215     public String getLocalName(int index);
216 
217     /**
218      * Look up an attribute's XML 1.0 qualified name by index.
219      *
220      * @param index The attribute index (zero-based).
221      *
222      * @return The XML 1.0 qualified name, or the empty string
223      *         if none is available, or null if the index
224      *         is out of range.
225      *
226      * @see #getLength
227      */
228     public String getQName(int index);
229 
230     //why the above method doens't return QName ?
231     public QName getQualifiedName(int index);
232 
233 
234     /**
235      * Sets the type of the attribute at the specified index.
236      *
237      * @param attrIndex The attribute index.
238      * @param attrType  The attribute type. The type name is determined by
239      *                  the type specified for this attribute in the DTD.
240      *                  For example: "CDATA", "ID", "NMTOKEN", etc. However,
241      *                  attributes of type enumeration will have the type
242      *                  value specified as the pipe ('|') separated list of
243      *                  the enumeration values prefixed by an open
244      *                  parenthesis and suffixed by a close parenthesis.
245      *                  For example: "(true|false)".
246      */
247     public void setType(int attrIndex, String attrType);
248 
249     /**
250      * Look up an attribute's type by index.
251      * <p>
252      * The attribute type is one of the strings "CDATA", "ID",
253      * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
254      * or "NOTATION" (always in upper case).
255      * <p>
256      * If the parser has not read a declaration for the attribute,
257      * or if the parser does not report attribute types, then it must
258      * return the value "CDATA" as stated in the XML 1.0 Recommentation
259      * (clause 3.3.3, "Attribute-Value Normalization").
260      * <p>
261      * For an enumerated attribute that is not a notation, the
262      * parser will report the type as "NMTOKEN".
263      *
264      * @param index The attribute index (zero-based).
265      *
266      * @return The attribute's type as a string, or null if the
267      *         index is out of range.
268      *
269      * @see #getLength
270      */
271     public String getType(int index);
272 
273     /**
274      * Look up an attribute's type by XML 1.0 qualified name.
275      * <p>
276      * See {@link #getType(int) getType(int)} for a description
277      * of the possible types.
278      *
279      * @param qName The XML 1.0 qualified name.
280      *
281      * @return The attribute type as a string, or null if the
282      *         attribute is not in the list or if qualified names
283      *         are not available.
284      */
285     public String getType(String qName);
286 
287     /**
288      * Look up an attribute's type by Namespace name.
289      * <p>
290      * See {@link #getType(int) getType(int)} for a description
291      * of the possible types.
292      *
293      * @param uri       The Namespace URI, or the empty String if the
294      *                  name has no Namespace URI.
295      * @param localName The local name of the attribute.
296      *
297      * @return The attribute type as a string, or null if the
298      *         attribute is not in the list or if Namespace
299      *         processing is not being performed.
300      */
301     public String getType(String uri, String localName);
302 
303     /**
304      * Sets the value of the attribute at the specified index. This
305      * method will overwrite the non-normalized value of the attribute.
306      *
307      * @param attrIndex The attribute index.
308      * @param attrValue The new attribute value.
309      *
310      * @see #setNonNormalizedValue
311      */
312     public void setValue(int attrIndex, String attrValue);
313 
314     public void setValue(int attrIndex, String attrValue, XMLString value);
315 
316     /**
317      * Look up an attribute's value by index.
318      * <p>
319      * If the attribute value is a list of tokens (IDREFS,
320      * ENTITIES, or NMTOKENS), the tokens will be concatenated
321      * into a single string with each token separated by a
322      * single space.
323      *
324      * @param index The attribute index (zero-based).
325      *
326      * @return The attribute's value as a string, or null if the
327      *         index is out of range.
328      *
329      * @see #getLength
330      */
331     public String getValue(int index);
332 
333     /**
334      * Look up an attribute's value by XML 1.0 qualified name.
335      * <p>
336      * See {@link #getValue(int) getValue(int)} for a description
337      * of the possible values.
338      *
339      * @param qName The XML 1.0 qualified name.
340      *
341      * @return The attribute value as a string, or null if the
342      *         attribute is not in the list or if qualified names
343      *         are not available.
344      */
345     public String getValue(String qName);
346 
347     /**
348      * Look up an attribute's value by Namespace name.
349      * <p>
350      * See {@link #getValue(int) getValue(int)} for a description
351      * of the possible values.
352      *
353      * @param uri       The Namespace URI, or the empty String if the
354      *                  name has no Namespace URI.
355      * @param localName The local name of the attribute.
356      *
357      * @return The attribute value as a string, or null if the
358      *         attribute is not in the list.
359      */
360     public String getValue(String uri, String localName);
361 
362     /**
363      * Sets the non-normalized value of the attribute at the specified
364      * index.
365      *
366      * @param attrIndex The attribute index.
367      * @param attrValue The new non-normalized attribute value.
368      */
369     public void setNonNormalizedValue(int attrIndex, String attrValue);
370 
371     /**
372      * Returns the non-normalized value of the attribute at the specified
373      * index. If no non-normalized value is set, this method will return
374      * the same value as the <code>getValue(int)</code> method.
375      *
376      * @param attrIndex The attribute index.
377      */
378     public String getNonNormalizedValue(int attrIndex);
379 
380     /**
381      * Sets whether an attribute is specified in the instance document
382      * or not.
383      *
384      * @param attrIndex The attribute index.
385      * @param specified True if the attribute is specified in the instance
386      *                  document.
387      */
388     public void setSpecified(int attrIndex, boolean specified);
389 
390     /**
391      * Returns true if the attribute is specified in the instance document.
392      *
393      * @param attrIndex The attribute index.
394      */
395     public boolean isSpecified(int attrIndex);
396 
397 
398     /**
399      * Look up an augmentation by attribute's index.
400      *
401      * @param attributeIndex The attribute index.
402      * @return Augmentations
403      */
404     public Augmentations getAugmentations (int attributeIndex);
405 
406     /**
407      * Look up an augmentation by namespace name.
408      *
409      * @param uri       The Namespace URI, or the empty string if
410      *                  the name has no Namespace URI.
411      * @param localPart
412      * @return Augmentations
413      */
414     public Augmentations getAugmentations (String uri, String localPart);
415 
416 
417     /**
418      * Look up an augmentation by XML 1.0 qualified name.
419      * <p>
420      *
421      * @param qName The XML 1.0 qualified name.
422      *
423      * @return Augmentations
424      *
425      */
426     public Augmentations getAugmentations(String qName);
427 
428     /**
429      * Sets the augmentations of the attribute at the specified index.
430      *
431      * @param attrIndex The attribute index.
432      * @param augs      The augmentations.
433      */
434     public void setAugmentations(int attrIndex, Augmentations augs);
435 
436 
437 
438 
439 } // interface XMLAttributes