001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.xerces.xni;
019:
020: /**
021: * The XMLAttributes interface defines a collection of attributes for
022: * an element. In the parser, the document source would scan the entire
023: * start element and collect the attributes. The attributes are
024: * communicated to the document handler in the startElement method.
025: * <p>
026: * The attributes are read-write so that subsequent stages in the document
027: * pipeline can modify the values or change the attributes that are
028: * propagated to the next stage.
029: *
030: * @see XMLDocumentHandler#startElement
031: *
032: * @author Andy Clark, IBM
033: *
034: * @version $Id: XMLAttributes.java 570130 2007-08-27 14:10:55Z mrglavas $
035: */
036: public interface XMLAttributes {
037:
038: //
039: // XMLAttributes methods
040: //
041:
042: /**
043: * Adds an attribute. The attribute's non-normalized value of the
044: * attribute will have the same value as the attribute value until
045: * set using the <code>setNonNormalizedValue</code> method. Also,
046: * the added attribute will be marked as specified in the XML instance
047: * document unless set otherwise using the <code>setSpecified</code>
048: * method.
049: * <p>
050: * <strong>Note:</strong> If an attribute of the same name already
051: * exists, the old values for the attribute are replaced by the new
052: * values.
053: *
054: * @param attrName The attribute name.
055: * @param attrType The attribute type. The type name is determined by
056: * the type specified for this attribute in the DTD.
057: * For example: "CDATA", "ID", "NMTOKEN", etc. However,
058: * attributes of type enumeration will have the type
059: * value specified as the pipe ('|') separated list of
060: * the enumeration values prefixed by an open
061: * parenthesis and suffixed by a close parenthesis.
062: * For example: "(true|false)".
063: * @param attrValue The attribute value.
064: *
065: * @return Returns the attribute index.
066: *
067: * @see #setNonNormalizedValue
068: * @see #setSpecified
069: */
070: public int addAttribute(QName attrName, String attrType,
071: String attrValue);
072:
073: /**
074: * Removes all of the attributes. This method will also remove all
075: * entities associated to the attributes.
076: */
077: public void removeAllAttributes();
078:
079: /**
080: * Removes the attribute at the specified index.
081: * <p>
082: * <strong>Note:</strong> This operation changes the indexes of all
083: * attributes following the attribute at the specified index.
084: *
085: * @param attrIndex The attribute index.
086: */
087: public void removeAttributeAt(int attrIndex);
088:
089: /**
090: * Returns the number of attributes in the list.
091: * <p>
092: * Once you know the number of attributes, you can iterate
093: * through the list.
094: *
095: * @see #getURI(int)
096: * @see #getLocalName(int)
097: * @see #getQName(int)
098: * @see #getType(int)
099: * @see #getValue(int)
100: */
101: public int getLength();
102:
103: /**
104: * Look up the index of an attribute by XML 1.0 qualified name.
105: *
106: * @param qName The qualified (prefixed) name.
107: *
108: * @return The index of the attribute, or -1 if it does not
109: * appear in the list.
110: */
111: public int getIndex(String qName);
112:
113: /**
114: * Look up the index of an attribute by Namespace name.
115: *
116: * @param uri The Namespace URI, or the empty string if
117: * the name has no Namespace URI.
118: * @param localPart The attribute's local name.
119: *
120: * @return The index of the attribute, or -1 if it does not
121: * appear in the list.
122: */
123: public int getIndex(String uri, String localPart);
124:
125: /**
126: * Sets the name of the attribute at the specified index.
127: *
128: * @param attrIndex The attribute index.
129: * @param attrName The new attribute name.
130: */
131: public void setName(int attrIndex, QName attrName);
132:
133: /**
134: * Sets the fields in the given QName structure with the values
135: * of the attribute name at the specified index.
136: *
137: * @param attrIndex The attribute index.
138: * @param attrName The attribute name structure to fill in.
139: */
140: public void getName(int attrIndex, QName attrName);
141:
142: /**
143: * Returns the prefix of the attribute at the specified index.
144: *
145: * @param index The index of the attribute.
146: */
147: public String getPrefix(int index);
148:
149: /**
150: * Look up an attribute's Namespace URI by index.
151: *
152: * @param index The attribute index (zero-based).
153: *
154: * @return The Namespace URI, or the empty string if none
155: * is available, or null if the index is out of
156: * range.
157: *
158: * @see #getLength
159: */
160: public String getURI(int index);
161:
162: /**
163: * Look up an attribute's local name by index.
164: *
165: * @param index The attribute index (zero-based).
166: *
167: * @return The local name, or the empty string if Namespace
168: * processing is not being performed, or null
169: * if the index is out of range.
170: *
171: * @see #getLength
172: */
173: public String getLocalName(int index);
174:
175: /**
176: * Look up an attribute's XML 1.0 qualified name by index.
177: *
178: * @param index The attribute index (zero-based).
179: *
180: * @return The XML 1.0 qualified name, or the empty string
181: * if none is available, or null if the index
182: * is out of range.
183: *
184: * @see #getLength
185: */
186: public String getQName(int index);
187:
188: /**
189: * Sets the type of the attribute at the specified index.
190: *
191: * @param attrIndex The attribute index.
192: * @param attrType The attribute type. The type name is determined by
193: * the type specified for this attribute in the DTD.
194: * For example: "CDATA", "ID", "NMTOKEN", etc. However,
195: * attributes of type enumeration will have the type
196: * value specified as the pipe ('|') separated list of
197: * the enumeration values prefixed by an open
198: * parenthesis and suffixed by a close parenthesis.
199: * For example: "(true|false)".
200: */
201: public void setType(int attrIndex, String attrType);
202:
203: /**
204: * Look up an attribute's type by index.
205: * <p>
206: * The attribute type is one of the strings "CDATA", "ID",
207: * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
208: * or "NOTATION" (always in upper case).
209: * <p>
210: * If the parser has not read a declaration for the attribute,
211: * or if the parser does not report attribute types, then it must
212: * return the value "CDATA" as stated in the XML 1.0 Recommendation
213: * (clause 3.3.3, "Attribute-Value Normalization").
214: * <p>
215: * For an enumerated attribute that is not a notation, the
216: * parser will report the type as "NMTOKEN".
217: *
218: * @param index The attribute index (zero-based).
219: *
220: * @return The attribute's type as a string, or null if the
221: * index is out of range.
222: *
223: * @see #getLength
224: */
225: public String getType(int index);
226:
227: /**
228: * Look up an attribute's type by XML 1.0 qualified name.
229: * <p>
230: * See {@link #getType(int) getType(int)} for a description
231: * of the possible types.
232: *
233: * @param qName The XML 1.0 qualified name.
234: *
235: * @return The attribute type as a string, or null if the
236: * attribute is not in the list or if qualified names
237: * are not available.
238: */
239: public String getType(String qName);
240:
241: /**
242: * Look up an attribute's type by Namespace name.
243: * <p>
244: * See {@link #getType(int) getType(int)} for a description
245: * of the possible types.
246: *
247: * @param uri The Namespace URI, or the empty String if the
248: * name has no Namespace URI.
249: * @param localName The local name of the attribute.
250: *
251: * @return The attribute type as a string, or null if the
252: * attribute is not in the list or if Namespace
253: * processing is not being performed.
254: */
255: public String getType(String uri, String localName);
256:
257: /**
258: * Sets the value of the attribute at the specified index. This
259: * method will overwrite the non-normalized value of the attribute.
260: *
261: * @param attrIndex The attribute index.
262: * @param attrValue The new attribute value.
263: *
264: * @see #setNonNormalizedValue
265: */
266: public void setValue(int attrIndex, String attrValue);
267:
268: /**
269: * Look up an attribute's value by index.
270: * <p>
271: * If the attribute value is a list of tokens (IDREFS,
272: * ENTITIES, or NMTOKENS), the tokens will be concatenated
273: * into a single string with each token separated by a
274: * single space.
275: *
276: * @param index The attribute index (zero-based).
277: *
278: * @return The attribute's value as a string, or null if the
279: * index is out of range.
280: *
281: * @see #getLength
282: */
283: public String getValue(int index);
284:
285: /**
286: * Look up an attribute's value by XML 1.0 qualified name.
287: * <p>
288: * See {@link #getValue(int) getValue(int)} for a description
289: * of the possible values.
290: *
291: * @param qName The XML 1.0 qualified name.
292: *
293: * @return The attribute value as a string, or null if the
294: * attribute is not in the list or if qualified names
295: * are not available.
296: */
297: public String getValue(String qName);
298:
299: /**
300: * Look up an attribute's value by Namespace name.
301: * <p>
302: * See {@link #getValue(int) getValue(int)} for a description
303: * of the possible values.
304: *
305: * @param uri The Namespace URI, or the empty String if the
306: * name has no Namespace URI.
307: * @param localName The local name of the attribute.
308: *
309: * @return The attribute value as a string, or null if the
310: * attribute is not in the list.
311: */
312: public String getValue(String uri, String localName);
313:
314: /**
315: * Sets the non-normalized value of the attribute at the specified
316: * index.
317: *
318: * @param attrIndex The attribute index.
319: * @param attrValue The new non-normalized attribute value.
320: */
321: public void setNonNormalizedValue(int attrIndex, String attrValue);
322:
323: /**
324: * Returns the non-normalized value of the attribute at the specified
325: * index. If no non-normalized value is set, this method will return
326: * the same value as the <code>getValue(int)</code> method.
327: *
328: * @param attrIndex The attribute index.
329: */
330: public String getNonNormalizedValue(int attrIndex);
331:
332: /**
333: * Sets whether an attribute is specified in the instance document
334: * or not.
335: *
336: * @param attrIndex The attribute index.
337: * @param specified True if the attribute is specified in the instance
338: * document.
339: */
340: public void setSpecified(int attrIndex, boolean specified);
341:
342: /**
343: * Returns true if the attribute is specified in the instance document.
344: *
345: * @param attrIndex The attribute index.
346: */
347: public boolean isSpecified(int attrIndex);
348:
349: /**
350: * Look up an augmentation by attribute's index.
351: *
352: * @param attributeIndex The attribute index.
353: * @return Augmentations
354: */
355: public Augmentations getAugmentations(int attributeIndex);
356:
357: /**
358: * Look up an augmentation by namespace name.
359: *
360: * @param uri The Namespace URI, or the empty string if
361: * the name has no Namespace URI.
362: * @param localPart
363: * @return Augmentations
364: */
365: public Augmentations getAugmentations(String uri, String localPart);
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: * Sets the augmentations of the attribute at the specified index.
380: *
381: * @param attrIndex The attribute index.
382: * @param augs The augmentations.
383: */
384: public void setAugmentations(int attrIndex, Augmentations augs);
385:
386: } // interface XMLAttributes
|