Attributes


1   /*
2    * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
3    * Copyright (C) 2006 - Javolution (http://javolution.org/)
4    * All rights reserved.
5    * 
6    * Permission to use, copy, modify, and distribute this software is
7    * freely granted, provided that this notice is preserved.
8    */
9   package javolution.xml.sax;
10  import javolution.text.CharArray;
11  import j2me.lang.CharSequence;
12  
13  /**
14   * <p> This interface represents a list of XML attributes.</p>
15   * 
16   * <p> It is a more efficient version of <code>org.xml.sax.Attributes</code>
17   *     with  {@link CharArray CharArray}/{@link CharSequence CharSequence} 
18   *     instead of the <code>String</code> to avoid forcing dynamic object 
19   *     allocations.</p>
20   *
21   * @author  <a HREF="mailto:sax@megginson.com">David Megginson</a>
22   * @author  <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
23   * @version 4.0, June 16, 2006
24   */
25  public interface Attributes {
26  
27      /**
28       * Returns the number of attributes in this list of attributes.
29       *
30       * @return the number of attributes.
31       */
32      int getLength();
33  
34      /**
35       * Looks up an attribute's Namespace URI by index.
36       *
37       * @param  index the attribute index (zero-based).
38       * @return the Namespace URI, or an empty character sequence if none is
39       *         available, or <code>null</code> if the index is out of range.
40       * @see    #getLength
41       */
42      CharArray getURI(int index);
43  
44      /**
45       * Looks up an attribute's local name by index.
46       *
47       * @param  index the attribute index (zero-based).
48       * @return the local name, or an empty character sequence if Namespace
49       *         processing is  not being performed, or <code>null</code> if
50       *         the index is out of range.
51       * @see    #getLength
52       */
53      CharArray getLocalName(int index);
54  
55  
56      /**
57       * Looks up an attribute's XML 1.0 qualified name by index.
58       *
59       * @param  index the attribute index (zero-based).
60       * @return the XML 1.0 qualified name, or an empty character sequence if
61       *         none is available, or <code>null</code> if the index is out
62       *         of range.
63       * @see    #getLength
64       */
65      CharArray getQName(int index);
66  
67      /**
68       * Looks up an attribute's type by index.
69       *
70       * <p> The attribute type is one of the strings "CDATA", "ID",
71       *    "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
72       *    or "NOTATION" (always in upper case).</p>
73       *
74       * <p> If the parser has not read a declaration for the attribute,
75       *     or if the parser does not report attribute types, then it must
76       *     return the value "CDATA" as stated in the XML 1.0 Recommentation
77       *     (clause 3.3.3, "Attribute-TextBuilder Normalization").</p>
78       *
79       * <p> For an enumerated attribute that is not a notation, the
80       *     parser will report the type as "NMTOKEN".</p>
81       *
82       * @param  index the attribute index (zero-based).
83       * @return the attribute's type as a string, or null if the
84       *         index is out of range.
85       * @see    #getLength
86       */
87      CharArray getType(int index);
88  
89      /**
90       * Looks up an attribute's value by index.
91       *
92       * <p> If the attribute value is a list of tokens (IDREFS,
93       *     ENTITIES, or NMTOKENS), the tokens will be concatenated
94       *     into a single string with each token separated by a
95       *     single space.</p>
96       *
97       * @param  index the attribute index (zero-based).
98       * @return the attribute's value as a character sequence,
99       *         <code>null</code> if the index is out of range.
100      * @see    #getLength
101      */
102     CharArray getValue(int index);
103 
104     /**
105      * Looks up the index of an attribute by namespace name (convenience 
106      * method).
107      * This method returns the index of the attribute whose uri/localName 
108      * have the same character content as the specified uri/localName.
109      *
110      * @param  uri the Namespace URI, or an empty character sequence if
111      *         the name has no Namespace URI.
112      * @param  localName the attribute's local name.
113      * @return the index of the attribute, or <code>-1</code> if it does not
114      *         appear in the list.
115      */
116     int getIndex(CharSequence   uri, CharSequence   localName);
117 
118     /**
119      * Looks up the index of an attribute by XML 1.0 qualified name 
120      * (convenience method). This method returns the index of the attribute 
121      * whose name has the same character content as the specified qName.
122      *
123      * @param  qName the qualified (prefixed) name.
124      * @return the index of the attribute, or <code>-1</code> if it does not
125      *         appear in the list.
126      */
127     int getIndex(CharSequence   qName);
128 
129     /**
130      * Looks up an attribute's type by Namespace name (convenience method).
131      * This method returns the type of the attribute whose uri/localName 
132      * have the same character content as the specified uri/localName.
133      *
134      * @param  uri the Namespace URI, or an empty string if the
135      *         name has no Namespace URI.
136      * @param  localName the local name of the attribute.
137      * @return the attribute type as a string, or null if the attribute is not
138      *         in the list or if Namespace processing is not being performed.
139      */
140     CharArray getType(CharSequence   uri, CharSequence   localName);
141 
142     /**
143      * Looks up an attribute's type by XML 1.0 qualified name.
144      * This method returns the type of the attribute whose qName 
145      * has the same character content as the specified qName.
146      *
147      * @param  qName The XML 1.0 qualified name.
148      * @return the attribute type as a string, or null if the attribute is not
149      *         in the list or if qualified names are not available.
150      */
151     CharArray getType(CharSequence   qName);
152 
153     /**
154      * Looks up an attribute's value by Namespace name (convenience method).
155      * This method returns the value of the attribute whose uri/localName 
156      * have the same character content as the specified uri/localName.
157      *
158      * @param  uri the Namespace URI, or the empty string if the name has no 
159      *         Namespace URI.
160      * @param  localName the local name of the attribute.
161      * @return the attribute value as a character sequence, or <code>null</code>
162      *         if the attribute is not in the list.
163      */
164     CharArray getValue(CharSequence   uri, CharSequence   localName);
165 
166     /**
167      * Looks up an attribute's value by XML 1.0 qualified name (convenience 
168      * method). This method returns the value of the attribute whose qName 
169      * has the same character content as the specified qName.
170      *
171      * @param  qName The XML 1.0 qualified name.
172      * @return the attribute value as a character sequence, or <code>null</code>
173      *         if the attribute is not in the list or if qualified names
174      *         are not available.
175      */
176     CharArray getValue(CharSequence   qName);
177 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags