001: /*
002: * The Apache Software License, Version 1.1
003: *
004: *
005: * Copyright (c) 2000-2002 The Apache Software Foundation. All rights
006: * reserved.
007: *
008: * Redistribution and use in source and binary forms, with or without
009: * modification, are permitted provided that the following conditions
010: * are met:
011: *
012: * 1. Redistributions of source code must retain the above copyright
013: * notice, this list of conditions and the following disclaimer.
014: *
015: * 2. Redistributions in binary form must reproduce the above copyright
016: * notice, this list of conditions and the following disclaimer in
017: * the documentation and/or other materials provided with the
018: * distribution.
019: *
020: * 3. The end-user documentation included with the redistribution,
021: * if any, must include the following acknowledgment:
022: * "This product includes software developed by the
023: * Apache Software Foundation (http://www.apache.org/)."
024: * Alternately, this acknowledgment may appear in the software itself,
025: * if and wherever such third-party acknowledgments normally appear.
026: *
027: * 4. The names "Xerces" and "Apache Software Foundation" must
028: * not be used to endorse or promote products derived from this
029: * software without prior written permission. For written
030: * permission, please contact apache@apache.org.
031: *
032: * 5. Products derived from this software may not be called "Apache",
033: * nor may "Apache" appear in their name, without prior written
034: * permission of the Apache Software Foundation.
035: *
036: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
037: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
038: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
039: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
040: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
041: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
042: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
043: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
044: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
045: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
046: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
047: * SUCH DAMAGE.
048: * ====================================================================
049: *
050: * This software consists of voluntary contributions made by many
051: * individuals on behalf of the Apache Software Foundation and was
052: * originally based on software copyright (c) 1999, International
053: * Business Machines, Inc., http://www.apache.org. For more
054: * information on the Apache Software Foundation, please see
055: * <http://www.apache.org/>.
056: */
057:
058: package com.sun.xml.stream.xerces.xni;
059:
060: /**
061: * The XMLAttributes interface defines a collection of attributes for
062: * an element. In the parser, the document source would scan the entire
063: * start element and collect the attributes. The attributes are
064: * communicated to the document handler in the startElement method.
065: * <p>
066: * The attributes are read-write so that subsequent stages in the document
067: * pipeline can modify the values or change the attributes that are
068: * propogated to the next stage.
069: *
070: * @see XMLDocumentHandler#startElement
071: *
072: * @author Andy Clark, IBM
073: *
074: * @version $Id: XMLAttributes.java,v 1.2 2006/04/01 06:01:46 jeffsuttor Exp $
075: */
076: public interface XMLAttributes {
077:
078: //
079: // XMLAttributes methods
080: //
081:
082: /**
083: * Adds an attribute. The attribute's non-normalized value of the
084: * attribute will have the same value as the attribute value until
085: * set using the <code>setNonNormalizedValue</code> method. Also,
086: * the added attribute will be marked as specified in the XML instance
087: * document unless set otherwise using the <code>setSpecified</code>
088: * method.
089: * <p>
090: * <strong>Note:</strong> If an attribute of the same name already
091: * exists, the old values for the attribute are replaced by the new
092: * values.
093: *
094: * @param attrName The attribute name.
095: * @param attrType The attribute type. The type name is determined by
096: * the type specified for this attribute in the DTD.
097: * For example: "CDATA", "ID", "NMTOKEN", etc. However,
098: * attributes of type enumeration will have the type
099: * 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,
111: String attrValue);
112:
113: /**
114: * Removes all of the attributes. This method will also remove all
115: * entities associated to the attributes.
116: */
117: public void removeAllAttributes();
118:
119: /**
120: * Removes the attribute at the specified index.
121: * <p>
122: * <strong>Note:</strong> This operation changes the indexes of all
123: * attributes following the attribute at the specified index.
124: *
125: * @param attrIndex The attribute index.
126: */
127: public void removeAttributeAt(int attrIndex);
128:
129: /**
130: * Returns the number of attributes in the list.
131: * <p>
132: * Once you know the number of attributes, you can iterate
133: * through the list.
134: *
135: * @see #getURI(int)
136: * @see #getLocalName(int)
137: * @see #getQName(int)
138: * @see #getType(int)
139: * @see #getValue(int)
140: */
141: public int getLength();
142:
143: /**
144: * Look up the index of an attribute by XML 1.0 qualified name.
145: *
146: * @param qName The qualified (prefixed) name.
147: *
148: * @return The index of the attribute, or -1 if it does not
149: * appear in the list.
150: */
151: public int getIndex(String qName);
152:
153: /**
154: * Look up the index of an attribute by Namespace name.
155: *
156: * @param uri The Namespace URI, or the empty string if
157: * the name has no Namespace URI.
158: * @param localName The attribute's local name.
159: *
160: * @return The index of the attribute, or -1 if it does not
161: * appear in the list.
162: */
163: public int getIndex(String uri, String localPart);
164:
165: /**
166: * Sets the name of the attribute at the specified index.
167: *
168: * @param attrIndex The attribute index.
169: * @param attrName The new attribute name.
170: */
171: public void setName(int attrIndex, QName attrName);
172:
173: /**
174: * Sets the fields in the given QName structure with the values
175: * of the attribute name at the specified index.
176: *
177: * @param attrIndex The attribute index.
178: * @param attrName The attribute name structure to fill in.
179: */
180: public void getName(int attrIndex, QName attrName);
181:
182: /**
183: * Returns the prefix of the attribute at the specified index.
184: *
185: * @param index The index of the attribute.
186: */
187: public String getPrefix(int index);
188:
189: /**
190: * Look up an attribute's Namespace URI by index.
191: *
192: * @param index The attribute index (zero-based).
193: *
194: * @return The Namespace URI, or the empty string if none
195: * is available, or null if the index is out of
196: * range.
197: *
198: * @see #getLength
199: */
200: public String getURI(int index);
201:
202: /**
203: * Look up an attribute's local name by index.
204: *
205: * @param index The attribute index (zero-based).
206: *
207: * @return The local name, or the empty string if Namespace
208: * processing is not being performed, or null
209: * if the index is out of range.
210: *
211: * @see #getLength
212: */
213: public String getLocalName(int index);
214:
215: /**
216: * Look up an attribute's XML 1.0 qualified name by index.
217: *
218: * @param index The attribute index (zero-based).
219: *
220: * @return The XML 1.0 qualified name, or the empty string
221: * if none is available, or null if the index
222: * is out of range.
223: *
224: * @see #getLength
225: */
226: public String getQName(int index);
227:
228: //why the above method doens't return QName ?
229: public QName getQualifiedName(int index);
230:
231: /**
232: * Sets the type of the attribute at the specified index.
233: *
234: * @param attrIndex The attribute index.
235: * @param attrType The attribute type. The type name is determined by
236: * the type specified for this attribute in the DTD.
237: * For example: "CDATA", "ID", "NMTOKEN", etc. However,
238: * attributes of type enumeration will have the type
239: * value specified as the pipe ('|') separated list of
240: * the enumeration values prefixed by an open
241: * parenthesis and suffixed by a close parenthesis.
242: * For example: "(true|false)".
243: */
244: public void setType(int attrIndex, String attrType);
245:
246: /**
247: * Look up an attribute's type by index.
248: * <p>
249: * The attribute type is one of the strings "CDATA", "ID",
250: * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
251: * or "NOTATION" (always in upper case).
252: * <p>
253: * If the parser has not read a declaration for the attribute,
254: * or if the parser does not report attribute types, then it must
255: * return the value "CDATA" as stated in the XML 1.0 Recommentation
256: * (clause 3.3.3, "Attribute-Value Normalization").
257: * <p>
258: * For an enumerated attribute that is not a notation, the
259: * parser will report the type as "NMTOKEN".
260: *
261: * @param index The attribute index (zero-based).
262: *
263: * @return The attribute's type as a string, or null if the
264: * index is out of range.
265: *
266: * @see #getLength
267: */
268: public String getType(int index);
269:
270: /**
271: * Look up an attribute's type by XML 1.0 qualified name.
272: * <p>
273: * See {@link #getType(int) getType(int)} for a description
274: * of the possible types.
275: *
276: * @param qName The XML 1.0 qualified name.
277: *
278: * @return The attribute type as a string, or null if the
279: * attribute is not in the list or if qualified names
280: * are not available.
281: */
282: public String getType(String qName);
283:
284: /**
285: * Look up an attribute's type by Namespace name.
286: * <p>
287: * See {@link #getType(int) getType(int)} for a description
288: * of the possible types.
289: *
290: * @param uri The Namespace URI, or the empty String if the
291: * name has no Namespace URI.
292: * @param localName The local name of the attribute.
293: *
294: * @return The attribute type as a string, or null if the
295: * attribute is not in the list or if Namespace
296: * processing is not being performed.
297: */
298: public String getType(String uri, String localName);
299:
300: /**
301: * Sets the value of the attribute at the specified index. This
302: * method will overwrite the non-normalized value of the attribute.
303: *
304: * @param attrIndex The attribute index.
305: * @param attrValue The new attribute value.
306: *
307: * @see #setNonNormalizedValue
308: */
309: public void setValue(int attrIndex, String attrValue);
310:
311: /**
312: * Look up an attribute's value by index.
313: * <p>
314: * If the attribute value is a list of tokens (IDREFS,
315: * ENTITIES, or NMTOKENS), the tokens will be concatenated
316: * into a single string with each token separated by a
317: * single space.
318: *
319: * @param index The attribute index (zero-based).
320: *
321: * @return The attribute's value as a string, or null if the
322: * index is out of range.
323: *
324: * @see #getLength
325: */
326: public String getValue(int index);
327:
328: /**
329: * Look up an attribute's value by XML 1.0 qualified name.
330: * <p>
331: * See {@link #getValue(int) getValue(int)} for a description
332: * of the possible values.
333: *
334: * @param qName The XML 1.0 qualified name.
335: *
336: * @return The attribute value as a string, or null if the
337: * attribute is not in the list or if qualified names
338: * are not available.
339: */
340: public String getValue(String qName);
341:
342: /**
343: * Look up an attribute's value by Namespace name.
344: * <p>
345: * See {@link #getValue(int) getValue(int)} for a description
346: * of the possible values.
347: *
348: * @param uri The Namespace URI, or the empty String if the
349: * name has no Namespace URI.
350: * @param localName The local name of the attribute.
351: *
352: * @return The attribute value as a string, or null if the
353: * attribute is not in the list.
354: */
355: public String getValue(String uri, String localName);
356:
357: /**
358: * Sets the non-normalized value of the attribute at the specified
359: * index.
360: *
361: * @param attrIndex The attribute index.
362: * @param attrValue The new non-normalized attribute value.
363: */
364: public void setNonNormalizedValue(int attrIndex, String attrValue);
365:
366: /**
367: * Returns the non-normalized value of the attribute at the specified
368: * index. If no non-normalized value is set, this method will return
369: * the same value as the <code>getValue(int)</code> method.
370: *
371: * @param attrIndex The attribute index.
372: */
373: public String getNonNormalizedValue(int attrIndex);
374:
375: /**
376: * Sets whether an attribute is specified in the instance document
377: * or not.
378: *
379: * @param attrIndex The attribute index.
380: * @param specified True if the attribute is specified in the instance
381: * document.
382: */
383: public void setSpecified(int attrIndex, boolean specified);
384:
385: /**
386: * Returns true if the attribute is specified in the instance document.
387: *
388: * @param attrIndex The attribute index.
389: */
390: public boolean isSpecified(int attrIndex);
391:
392: /**
393: * Look up an augmentation by attribute's index.
394: *
395: * @param attributeIndex The attribute index.
396: * @return Augmentations
397: */
398: public Augmentations getAugmentations(int attributeIndex);
399:
400: /**
401: * Look up an augmentation by namespace name.
402: *
403: * @param uri The Namespace URI, or the empty string if
404: * the name has no Namespace URI.
405: * @param localPart
406: * @return Augmentations
407: */
408: public Augmentations getAugmentations(String uri, String localPart);
409:
410: /**
411: * Look up an augmentation by XML 1.0 qualified name.
412: * <p>
413: *
414: * @param qName The XML 1.0 qualified name.
415: *
416: * @return Augmentations
417: *
418: */
419: public Augmentations getAugmentations(String qName);
420:
421: } // interface XMLAttributes
|