1 /*

     2  * Copyright 2000-2005 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 // Attributes.java - attribute list with Namespace support

    27 // http://www.saxproject.org

    28 // Written by David Megginson

    29 // NO WARRANTY!  This class is in the public domain.

    30 // $Id: Attributes.java,v 1.2 2004/11/03 22:44:51 jsuttor Exp $

    31 

    32 package org.xml.sax;

    33 

    34 

    35 /**

    36  * Interface for a list of XML attributes.

    37  *

    38  * <blockquote>

    39  * <em>This module, both source code and documentation, is in the

    40  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>

    41  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>

    42  * for further information.

    43  * </blockquote>

    44  *

    45  * <p>This interface allows access to a list of attributes in

    46  * three different ways:</p>

    47  *

    48  * <ol>

    49  * <li>by attribute index;</li>

    50  * <li>by Namespace-qualified name; or</li>

    51  * <li>by qualified (prefixed) name.</li>

    52  * </ol>

    53  *

    54  * <p>The list will not contain attributes that were declared

    55  * #IMPLIED but not specified in the start tag.  It will also not

    56  * contain attributes used as Namespace declarations (xmlns*) unless

    57  * the <code>http://xml.org/sax/features/namespace-prefixes</code>

    58  * feature is set to <var>true</var> (it is <var>false</var> by

    59  * default).

    60  * Because SAX2 conforms to the original "Namespaces in XML"

    61  * recommendation, it normally does not

    62  * give namespace declaration attributes a namespace URI.

    63  * </p>

    64  *

    65  * <p>Some SAX2 parsers may support using an optional feature flag

    66  * (<code>http://xml.org/sax/features/xmlns-uris</code>) to request

    67  * that those attributes be given URIs, conforming to a later

    68  * backwards-incompatible revision of that recommendation.  (The

    69  * attribute's "local name" will be the prefix, or "xmlns" when

    70  * defining a default element namespace.)  For portability, handler

    71  * code should always resolve that conflict, rather than requiring

    72  * parsers that can change the setting of that feature flag.  </p>

    73  *

    74  * <p>If the namespace-prefixes feature (see above) is

    75  * <var>false</var>, access by qualified name may not be available; if

    76  * the <code>http://xml.org/sax/features/namespaces</code> feature is

    77  * <var>false</var>, access by Namespace-qualified names may not be

    78  * available.</p>

    79  *

    80  * <p>This interface replaces the now-deprecated SAX1 {@link

    81  * org.xml.sax.AttributeList AttributeList} interface, which does not

    82  * contain Namespace support.  In addition to Namespace support, it

    83  * adds the <var>getIndex</var> methods (below).</p>

    84  *

    85  * <p>The order of attributes in the list is unspecified, and will

    86  * vary from implementation to implementation.</p>

    87  *

    88  * @since SAX 2.0

    89  * @author David Megginson

    90  * @see org.xml.sax.helpers.AttributesImpl

    91  * @see org.xml.sax.ext.DeclHandler#attributeDecl

    92  */

    93 public interface Attributes

    94 {

    95 

    96 

    97     ////////////////////////////////////////////////////////////////////

    98     // Indexed access.

    99     ////////////////////////////////////////////////////////////////////

   100 

   101 

   102     /**

   103      * Return the number of attributes in the list.

   104      *

   105      * <p>Once you know the number of attributes, you can iterate

   106      * through the list.</p>

   107      *

   108      * @return The number of attributes in the list.

   109      * @see #getURI(int)

   110      * @see #getLocalName(int)

   111      * @see #getQName(int)

   112      * @see #getType(int)

   113      * @see #getValue(int)

   114      */

   115     public abstract int getLength ();

   116 

   117 

   118     /**

   119      * Look up an attribute's Namespace URI by index.

   120      *

   121      * @param index The attribute index (zero-based).

   122      * @return The Namespace URI, or the empty string if none

   123      *         is available, or null if the index is out of

   124      *         range.

   125      * @see #getLength

   126      */

   127     public abstract String getURI (int index);

   128 

   129 

   130     /**

   131      * Look up an attribute's local name by index.

   132      *

   133      * @param index The attribute index (zero-based).

   134      * @return The local name, or the empty string if Namespace

   135      *         processing is not being performed, or null

   136      *         if the index is out of range.

   137      * @see #getLength

   138      */

   139     public abstract String getLocalName (int index);

   140 

   141 

   142     /**

   143      * Look up an attribute's XML qualified (prefixed) name by index.

   144      *

   145      * @param index The attribute index (zero-based).

   146      * @return The XML qualified name, or the empty string

   147      *         if none is available, or null if the index

   148      *         is out of range.

   149      * @see #getLength

   150      */

   151     public abstract String getQName (int index);

   152 

   153 

   154     /**

   155      * Look up an attribute's type by index.

   156      *

   157      * <p>The attribute type is one of the strings "CDATA", "ID",

   158      * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",

   159      * or "NOTATION" (always in upper case).</p>

   160      *

   161      * <p>If the parser has not read a declaration for the attribute,

   162      * or if the parser does not report attribute types, then it must

   163      * return the value "CDATA" as stated in the XML 1.0 Recommendation

   164      * (clause 3.3.3, "Attribute-Value Normalization").</p>

   165      *

   166      * <p>For an enumerated attribute that is not a notation, the

   167      * parser will report the type as "NMTOKEN".</p>

   168      *

   169      * @param index The attribute index (zero-based).

   170      * @return The attribute's type as a string, or null if the

   171      *         index is out of range.

   172      * @see #getLength

   173      */

   174     public abstract String getType (int index);

   175 

   176 

   177     /**

   178      * Look up an attribute's value by index.

   179      *

   180      * <p>If the attribute value is a list of tokens (IDREFS,

   181      * ENTITIES, or NMTOKENS), the tokens will be concatenated

   182      * into a single string with each token separated by a

   183      * single space.</p>

   184      *

   185      * @param index The attribute index (zero-based).

   186      * @return The attribute's value as a string, or null if the

   187      *         index is out of range.

   188      * @see #getLength

   189      */

   190     public abstract String getValue (int index);

   191 

   192 

   193 

   194     ////////////////////////////////////////////////////////////////////

   195     // Name-based query.

   196     ////////////////////////////////////////////////////////////////////

   197 

   198 

   199     /**

   200      * Look up the index of an attribute by Namespace name.

   201      *

   202      * @param uri The Namespace URI, or the empty string if

   203      *        the name has no Namespace URI.

   204      * @param localName The attribute's local name.

   205      * @return The index of the attribute, or -1 if it does not

   206      *         appear in the list.

   207      */

   208     public int getIndex (String uri, String localName);

   209 

   210 

   211     /**

   212      * Look up the index of an attribute by XML qualified (prefixed) name.

   213      *

   214      * @param qName The qualified (prefixed) name.

   215      * @return The index of the attribute, or -1 if it does not

   216      *         appear in the list.

   217      */

   218     public int getIndex (String qName);

   219 

   220 

   221     /**

   222      * Look up an attribute's type by Namespace name.

   223      *

   224      * <p>See {@link #getType(int) getType(int)} for a description

   225      * of the possible types.</p>

   226      *

   227      * @param uri The Namespace URI, or the empty String if the

   228      *        name has no Namespace URI.

   229      * @param localName The local name of the attribute.

   230      * @return The attribute type as a string, or null if the

   231      *         attribute is not in the list or if Namespace

   232      *         processing is not being performed.

   233      */

   234     public abstract String getType (String uri, String localName);

   235 

   236 

   237     /**

   238      * Look up an attribute's type by XML qualified (prefixed) name.

   239      *

   240      * <p>See {@link #getType(int) getType(int)} for a description

   241      * of the possible types.</p>

   242      *

   243      * @param qName The XML qualified name.

   244      * @return The attribute type as a string, or null if the

   245      *         attribute is not in the list or if qualified names

   246      *         are not available.

   247      */

   248     public abstract String getType (String qName);

   249 

   250 

   251     /**

   252      * Look up an attribute's value by Namespace name.

   253      *

   254      * <p>See {@link #getValue(int) getValue(int)} for a description

   255      * of the possible values.</p>

   256      *

   257      * @param uri The Namespace URI, or the empty String if the

   258      *        name has no Namespace URI.

   259      * @param localName The local name of the attribute.

   260      * @return The attribute value as a string, or null if the

   261      *         attribute is not in the list.

   262      */

   263     public abstract String getValue (String uri, String localName);

   264 

   265 

   266     /**

   267      * Look up an attribute's value by XML qualified (prefixed) name.

   268      *

   269      * <p>See {@link #getValue(int) getValue(int)} for a description

   270      * of the possible values.</p>

   271      *

   272      * @param qName The XML qualified name.

   273      * @return The attribute value as a string, or null if the

   274      *         attribute is not in the list or if qualified names

   275      *         are not available.

   276      */

   277     public abstract String getValue (String qName);

   278 

   279 }

   280 

   281 // end of Attributes.java