XMLAttributes


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