1/*
2 * reserved comment block
3 * DO NOT REMOVE OR ALTER!
4 */
5/*
6 * Licensed to the Apache Software Foundation (ASF) under one or more
7 * contributor license agreements.  See the NOTICE file distributed with
8 * this work for additional information regarding copyright ownership.
9 * The ASF licenses this file to You under the Apache License, Version 2.0
10 * (the "License"); you may not use this file except in compliance with
11 * the License.  You may obtain a copy of the License at
12 *
13 *      http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS,
17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
20 */
21
22package com.sun.org.apache.xerces.internal.xni;
23
24/**
25 * The XMLAttributes interface defines a collection of attributes for
26 * an element. In the parser, the document source would scan the entire
27 * start element and collect the attributes. The attributes are
28 * communicated to the document handler in the startElement method.
29 * <p>
30 * The attributes are read-write so that subsequent stages in the document
31 * pipeline can modify the values or change the attributes that are
32 * propogated to the next stage.
33 *
34 * @see XMLDocumentHandler#startElement
35 *
36 * @author Andy Clark, IBM
37 *
38 */
39public interface XMLAttributes {
40
41    //
42    // XMLAttributes methods
43    //
44
45    /**
46     * Adds an attribute. The attribute's non-normalized value of the
47     * attribute will have the same value as the attribute value until
48     * set using the <code>setNonNormalizedValue</code> method. Also,
49     * the added attribute will be marked as specified in the XML instance
50     * document unless set otherwise using the <code>setSpecified</code>
51     * method.
52     * <p>
53     * <strong>Note:</strong> If an attribute of the same name already
54     * exists, the old values for the attribute are replaced by the new
55     * values.
56     *
57     * @param attrName  The attribute name.
58     * @param attrType  The attribute type. The type name is determined by
59     *                  the type specified for this attribute in the DTD.
60     *                  For example: "CDATA", "ID", "NMTOKEN", etc. However,
61     *                  attributes of type enumeration will have the type
62     *                  value specified as the pipe ('|') separated list of
63     *                  the enumeration values prefixed by an open
64     *                  parenthesis and suffixed by a close parenthesis.
65     *                  For example: "(true|false)".
66     * @param attrValue The attribute value.
67     *
68     * @return Returns the attribute index.
69     *
70     * @see #setNonNormalizedValue
71     * @see #setSpecified
72     */
73    public int addAttribute(QName attrName, String attrType, String attrValue);
74
75    /**
76     * Removes all of the attributes. This method will also remove all
77     * entities associated to the attributes.
78     */
79    public void removeAllAttributes();
80
81    /**
82     * Removes the attribute at the specified index.
83     * <p>
84     * <strong>Note:</strong> This operation changes the indexes of all
85     * attributes following the attribute at the specified index.
86     *
87     * @param attrIndex The attribute index.
88     */
89    public void removeAttributeAt(int attrIndex);
90
91    /**
92     * Returns the number of attributes in the list.
93     * <p>
94     * Once you know the number of attributes, you can iterate
95     * through the list.
96     *
97     * @see #getURI(int)
98     * @see #getLocalName(int)
99     * @see #getQName(int)
100     * @see #getType(int)
101     * @see #getValue(int)
102     */
103    public int getLength();
104
105    /**
106     * Look up the index of an attribute by XML 1.0 qualified name.
107     *
108     * @param qName The qualified (prefixed) name.
109     *
110     * @return The index of the attribute, or -1 if it does not
111     *         appear in the list.
112     */
113    public int getIndex(String qName);
114
115    /**
116     * Look up the index of an attribute by Namespace name.
117     *
118     * @param uri       The Namespace URI, or the empty string if
119     *                  the name has no Namespace URI.
120     * @param localName The attribute's local name.
121     *
122     * @return The index of the attribute, or -1 if it does not
123     *         appear in the list.
124     */
125    public int getIndex(String uri, String localPart);
126
127    /**
128     * Sets the name of the attribute at the specified index.
129     *
130     * @param attrIndex The attribute index.
131     * @param attrName  The new attribute name.
132     */
133    public void setName(int attrIndex, QName attrName);
134
135    /**
136     * Sets the fields in the given QName structure with the values
137     * of the attribute name at the specified index.
138     *
139     * @param attrIndex The attribute index.
140     * @param attrName  The attribute name structure to fill in.
141     */
142    public void getName(int attrIndex, QName attrName);
143
144    /**
145     * Returns the prefix of the attribute at the specified index.
146     *
147     * @param index The index of the attribute.
148     */
149    public String getPrefix(int index);
150
151    /**
152     * Look up an attribute's Namespace URI by index.
153     *
154     * @param index The attribute index (zero-based).
155     *
156     * @return The Namespace URI, or the empty string if none
157     *         is available, or null if the index is out of
158     *         range.
159     *
160     * @see #getLength
161     */
162    public String getURI(int index);
163
164    /**
165     * Look up an attribute's local name by index.
166     *
167     * @param index The attribute index (zero-based).
168     *
169     * @return The local name, or the empty string if Namespace
170     *         processing is not being performed, or null
171     *         if the index is out of range.
172     *
173     * @see #getLength
174     */
175    public String getLocalName(int index);
176
177    /**
178     * Look up an attribute's XML 1.0 qualified name by index.
179     *
180     * @param index The attribute index (zero-based).
181     *
182     * @return The XML 1.0 qualified name, or the empty string
183     *         if none is available, or null if the index
184     *         is out of range.
185     *
186     * @see #getLength
187     */
188    public String getQName(int index);
189
190    //why the above method doens't return QName ?
191    public QName getQualifiedName(int index);
192
193
194    /**
195     * Sets the type of the attribute at the specified index.
196     *
197     * @param attrIndex The attribute index.
198     * @param attrType  The attribute type. The type name is determined by
199     *                  the type specified for this attribute in the DTD.
200     *                  For example: "CDATA", "ID", "NMTOKEN", etc. However,
201     *                  attributes of type enumeration will have the type
202     *                  value specified as the pipe ('|') separated list of
203     *                  the enumeration values prefixed by an open
204     *                  parenthesis and suffixed by a close parenthesis.
205     *                  For example: "(true|false)".
206     */
207    public void setType(int attrIndex, String attrType);
208
209    /**
210     * Look up an attribute's type by index.
211     * <p>
212     * The attribute type is one of the strings "CDATA", "ID",
213     * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
214     * or "NOTATION" (always in upper case).
215     * <p>
216     * If the parser has not read a declaration for the attribute,
217     * or if the parser does not report attribute types, then it must
218     * return the value "CDATA" as stated in the XML 1.0 Recommentation
219     * (clause 3.3.3, "Attribute-Value Normalization").
220     * <p>
221     * For an enumerated attribute that is not a notation, the
222     * parser will report the type as "NMTOKEN".
223     *
224     * @param index The attribute index (zero-based).
225     *
226     * @return The attribute's type as a string, or null if the
227     *         index is out of range.
228     *
229     * @see #getLength
230     */
231    public String getType(int index);
232
233    /**
234     * Look up an attribute's type by XML 1.0 qualified name.
235     * <p>
236     * See {@link #getType(int) getType(int)} for a description
237     * of the possible types.
238     *
239     * @param qName The XML 1.0 qualified name.
240     *
241     * @return The attribute type as a string, or null if the
242     *         attribute is not in the list or if qualified names
243     *         are not available.
244     */
245    public String getType(String qName);
246
247    /**
248     * Look up an attribute's type by Namespace name.
249     * <p>
250     * See {@link #getType(int) getType(int)} for a description
251     * of the possible types.
252     *
253     * @param uri       The Namespace URI, or the empty String if the
254     *                  name has no Namespace URI.
255     * @param localName The local name of the attribute.
256     *
257     * @return The attribute type as a string, or null if the
258     *         attribute is not in the list or if Namespace
259     *         processing is not being performed.
260     */
261    public String getType(String uri, String localName);
262
263    /**
264     * Sets the value of the attribute at the specified index. This
265     * method will overwrite the non-normalized value of the attribute.
266     *
267     * @param attrIndex The attribute index.
268     * @param attrValue The new attribute value.
269     *
270     * @see #setNonNormalizedValue
271     */
272    public void setValue(int attrIndex, String attrValue);
273
274    public void setValue(int attrIndex, String attrValue, XMLString value);
275
276    /**
277     * Look up an attribute's value by index.
278     * <p>
279     * If the attribute value is a list of tokens (IDREFS,
280     * ENTITIES, or NMTOKENS), the tokens will be concatenated
281     * into a single string with each token separated by a
282     * single space.
283     *
284     * @param index The attribute index (zero-based).
285     *
286     * @return The attribute's value as a string, or null if the
287     *         index is out of range.
288     *
289     * @see #getLength
290     */
291    public String getValue(int index);
292
293    /**
294     * Look up an attribute's value by XML 1.0 qualified name.
295     * <p>
296     * See {@link #getValue(int) getValue(int)} for a description
297     * of the possible values.
298     *
299     * @param qName The XML 1.0 qualified name.
300     *
301     * @return The attribute value as a string, or null if the
302     *         attribute is not in the list or if qualified names
303     *         are not available.
304     */
305    public String getValue(String qName);
306
307    /**
308     * Look up an attribute's value by Namespace name.
309     * <p>
310     * See {@link #getValue(int) getValue(int)} for a description
311     * of the possible values.
312     *
313     * @param uri       The Namespace URI, or the empty String if the
314     *                  name has no Namespace URI.
315     * @param localName The local name of the attribute.
316     *
317     * @return The attribute value as a string, or null if the
318     *         attribute is not in the list.
319     */
320    public String getValue(String uri, String localName);
321
322    /**
323     * Sets the non-normalized value of the attribute at the specified
324     * index.
325     *
326     * @param attrIndex The attribute index.
327     * @param attrValue The new non-normalized attribute value.
328     */
329    public void setNonNormalizedValue(int attrIndex, String attrValue);
330
331    /**
332     * Returns the non-normalized value of the attribute at the specified
333     * index. If no non-normalized value is set, this method will return
334     * the same value as the <code>getValue(int)</code> method.
335     *
336     * @param attrIndex The attribute index.
337     */
338    public String getNonNormalizedValue(int attrIndex);
339
340    /**
341     * Sets whether an attribute is specified in the instance document
342     * or not.
343     *
344     * @param attrIndex The attribute index.
345     * @param specified True if the attribute is specified in the instance
346     *                  document.
347     */
348    public void setSpecified(int attrIndex, boolean specified);
349
350    /**
351     * Returns true if the attribute is specified in the instance document.
352     *
353     * @param attrIndex The attribute index.
354     */
355    public boolean isSpecified(int attrIndex);
356
357
358    /**
359     * Look up an augmentation by attribute's index.
360     *
361     * @param attributeIndex The attribute index.
362     * @return Augmentations
363     */
364    public Augmentations getAugmentations (int attributeIndex);
365
366    /**
367     * Look up an augmentation by namespace name.
368     *
369     * @param uri       The Namespace URI, or the empty string if
370     *                  the name has no Namespace URI.
371     * @param localPart
372     * @return Augmentations
373     */
374    public Augmentations getAugmentations (String uri, String localPart);
375
376
377    /**
378     * Look up an augmentation by XML 1.0 qualified name.
379     * <p>
380     *
381     * @param qName The XML 1.0 qualified name.
382     *
383     * @return Augmentations
384     *
385     */
386    public Augmentations getAugmentations(String qName);
387
388    /**
389     * Sets the augmentations of the attribute at the specified index.
390     *
391     * @param attrIndex The attribute index.
392     * @param augs      The augmentations.
393     */
394    public void setAugmentations(int attrIndex, Augmentations augs);
395
396
397
398
399} // interface XMLAttributes
400