content: /*
   *  This file is part of AndroidIDE.
   *
   *  AndroidIDE is free software: you can redistribute it and/or modify
   *  it under the terms of the GNU General Public License as published by
   *  the Free Software Foundation, either version 3 of the License, or
   *  (at your option) any later version.
   *
   *  AndroidIDE is distributed in the hope that it will be useful,
   *  but WITHOUT ANY WARRANTY; without even the implied warranty of
   *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   *  GNU General Public License for more details.
   *
   *  You should have received a copy of the GNU General Public License
   *   along with AndroidIDE.  If not, see <https://www.gnu.org/licenses/>.
   */
  
  /*
   * Copyright (c) 2003, 2005, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  
  package jaxp.xml.validation;
  
  import jaxp.xml.parsers.DocumentBuilder;
  import org.w3c.dom.TypeInfo;
  
  /**
   * This class provides access to the type information determined
   * by {@link ValidatorHandler}.
   *
   * <p>
   * Some schema languages, such as W3C XML Schema, encourages a validator
   * to report the "type" it assigns to each attribute/element.
   * Those applications who wish to access this type information can invoke
   * methods defined on this "interface" to access such type information.
   *
   * <p>
   * Implementation of this "interface" can be obtained through the
   * {@link ValidatorHandler#getTypeInfoProvider()} method.
   *
   * @author  <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
   * @see org.w3c.dom.TypeInfo
   * @since 1.5
   */
  public abstract class TypeInfoProvider {
  
      /**
       * Constructor for the derived class.
       *
       * <p>
       * The constructor does nothing.
       */
      protected TypeInfoProvider() {
      }
  
      /**
       * <p>Returns the immutable {@link TypeInfo} object for the current
       * element.</p>
       *
       * <p>The method may only be called by the startElement event
       * or the endElement event
       * of the {@link org.xml.sax.ContentHandler} that the application sets to
       * the {@link ValidatorHandler}.</p>
       *
       * <p>When W3C XML Schema validation is being performed, in the
       * case where an element has a union type, the {@link TypeInfo}
       * returned by a call to <code>getElementTypeInfo()</code> from the
       * startElement
       * event will be the union type. The <code>TypeInfo</code>
       * returned by a call
       * from the endElement event will be the actual member type used
       * to validate the element.</p>
       *
       * @throws IllegalStateException
       *      If this method is called from other {@link org.xml.sax.ContentHandler}
       *      methods.
       * @return
       *      An immutable {@link TypeInfo} object that represents the
       *      type of the current element.
       *      Note that the caller can keep references to the obtained
       *      {@link TypeInfo} longer than the callback scope.
       *
       *      Otherwise, this method returns
       *      null if the validator is unable to
       *      determine the type of the current element for some reason
       *      (for example, if the validator is recovering from
       *      an earlier error.)
       *
       */
      public abstract TypeInfo getElementTypeInfo();
  
      /**
       * Returns the immutable {@link TypeInfo} object for the specified
       * attribute of the current element.
       *
       * <p>
       * The method may only be called by the startElement event of
       * the {@link org.xml.sax.ContentHandler} that the application sets to the
       * {@link ValidatorHandler}.</p>
       *
       * @param index
       *      The index of the attribute. The same index for
       *      the {@link org.xml.sax.Attributes} object passed to the
       *      <code>startElement</code> callback.
       *
       * @throws IndexOutOfBoundsException
       *      If the index is invalid.
       * @throws IllegalStateException
       *      If this method is called from other {@link org.xml.sax.ContentHandler}
       *      methods.
       *
       * @return
       *      An immutable {@link TypeInfo} object that represents the
       *      type of the specified attribute.
       *      Note that the caller can keep references to the obtained
       *      {@link TypeInfo} longer than the callback scope.
       *
       *      Otherwise, this method returns
       *      null if the validator is unable to
       *      determine the type.
       */
      public abstract TypeInfo getAttributeTypeInfo(int index);
  
      /**
       * Returns <code>true</code> if the specified attribute is determined
       * to be ID.
       *
       * <p>
       * Exacly how an attribute is "determined to be ID" is up to the
       * schema language. In case of W3C XML Schema, this means
       * that the actual type of the attribute is the built-in ID type
       * or its derived type.
       *
       * <p>
       * A {@link DocumentBuilder} uses this information
       * to properly implement {@link org.w3c.dom.Attr#isId()}.
       *
       * <p>
       * The method may only be called by the startElement event of
       * the {@link org.xml.sax.ContentHandler} that the application sets to the
       * {@link ValidatorHandler}.
       *
       * @param index
       *      The index of the attribute. The same index for
       *      the {@link org.xml.sax.Attributes} object passed to the
       *      <code>startElement</code> callback.
       *
       * @throws IndexOutOfBoundsException
       *      If the index is invalid.
       * @throws IllegalStateException
       *      If this method is called from other {@link org.xml.sax.ContentHandler}
       *      methods.
       *
       * @return true
       *      if the type of the specified attribute is ID.
       */
      public abstract boolean isIdAttribute(int index);
  
      /**
       * Returns <code>false</code> if the attribute was added by the validator.
       *
       * <p>
       * This method provides information necessary for
       * a {@link DocumentBuilder} to determine what
       * the DOM tree should return from the {@link org.w3c.dom.Attr#getSpecified()} method.
       *
       * <p>
       * The method may only be called by the startElement event of
       * the {@link org.xml.sax.ContentHandler} that the application sets to the
       * {@link ValidatorHandler}.
       *
       * <p>
       * A general guideline for validators is to return true if
       * the attribute was originally present in the pipeline, and
       * false if it was added by the validator.
       *
       * @param index
       *      The index of the attribute. The same index for
       *      the {@link org.xml.sax.Attributes} object passed to the
       *      <code>startElement</code> callback.
       *
       * @throws IndexOutOfBoundsException
       *      If the index is invalid.
       * @throws IllegalStateException
       *      If this method is called from other {@link org.xml.sax.ContentHandler}
       *      methods.
       *
       * @return
       *      <code>true</code> if the attribute was present before the validator
       *      processes input. <code>false</code> if the attribute was added
       *      by the validator.
       */
      public abstract boolean isSpecified(int index);
  }
  