# SaxReader.java

    /*
    ** Module   : SaxReader
    ** Abstract : SAX reader specific interface.
    **
    ** Copyright (c) 2013-2018, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- ---------------------------------Description----------------------------------
    ** 001 EVL 20130208 Created initial version.
    ** 002 CA  20130221 Added ADM-DATA and UNIQUE-ID support.
    ** 003 EVL 20130320 Adding SAX reader related literal constants.
    ** 004 EVK 20130903 Moved SuppressNamespaceProcessing methods to the new interface XmlSchema.
    ** 005 CA  20130927 Added LegacyResource annotation, to determine resource type.
    ** 006 EVL 20130911 Adding legacy attributes and methods annotation.
    ** 007 EVL 20131009 Leaving only SAX specific methods for schema path and schema locations. Other
    **                  are inherited from XmlSchema classs.
    ** 008 EVK 20131001 Added enum with 4gl reader status. removed inheritance to the UniqueID and
    **                  ADMData interfaces.
    ** 009 CA  20181029 Fixed a typo in SCHEMA-PATH setter.
    */
    /*
    ** This program is free software: you can redistribute it and/or modify
    ** it under the terms of the GNU Affero General Public License as
    ** published by the Free Software Foundation, either version 3 of the
    ** License, or (at your option) any later version.
    **
    ** This program 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 Affero General Public License for more details.
    **
    ** You may find a copy of the GNU Affero GPL version 3 at the following
    ** location: https://www.gnu.org/licenses/agpl-3.0.en.html
    **
    ** Additional terms under GNU Affero GPL version 3 section 7:
    **
    **   Under Section 7 of the GNU Affero GPL version 3, the following additional
    **   terms apply to the works covered under the License.  These additional terms
    **   are non-permissive additional terms allowed under Section 7 of the GNU
    **   Affero GPL version 3 and may not be removed by you.
    **
    **   0. Attribution Requirement.
    **
    **     You must preserve all legal notices or author attributions in the covered
    **     work or Appropriate Legal Notices displayed by works containing the covered
    **     work.  You may not remove from the covered work any author or developer
    **     credit already included within the covered work.
    **
    **   1. No License To Use Trademarks.
    **
    **     This license does not grant any license or rights to use the trademarks
    **     Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks
    **     of Golden Code Development Corporation. You are not authorized to use the
    **     name Golden Code, FWD, or the names of any author or contributor, for
    **     publicity purposes without written authorization.
    **
    **   2. No Misrepresentation of Affiliation.
    **
    **     You may not represent yourself as Golden Code Development Corporation or FWD.
    **
    **     You may not represent yourself for publicity purposes as associated with
    **     Golden Code Development Corporation, FWD, or any author or contributor to
    **     the covered work, without written authorization.
    **
    **   3. No Misrepresentation of Source or Origin.
    **
    **     You may not represent the covered work as solely your work.  All modified
    **     versions of the covered work must be marked in a reasonable way to make it
    **     clear that the modified work is not originating from Golden Code Development
    **     Corporation or FWD.  All modified versions must contain the notices of
    **     attribution required in this license.
    */

    package com.goldencode.p2j.xml;

    import com.goldencode.p2j.util.*;

    /**
     * Interface describing SAX-Reader specific features of the SAX objects.
     */
    @LegacyResource(resource = LegacyResource.SAX_READER)
    public interface SaxReader
    extends SaxEntity,
            XmlSchema
    {
       /**
        * The SAX-UNINITIALIZE constant returned by the PARSE-STATUS attribute, which in 4GL is the
        * integer value 1.
        */
       public static final int SAX_UNINITIALIZED = 1;

       /**
        * The SAX-RUNNING constant returned by the PARSE-STATUS attribute, which in 4GL is the
        * integer value 2.
        */
       public static final int SAX_RUNNING = 2;

       /**
        * The SAX-COMPLETE constant returned by the PARSE-STATUS attribute, which in 4GL is the
        * integer value 3.
        */
       public static final int SAX_COMPLETE = 3;

       /**
        * The SAX-PARSER-ERROR constant returned by the PARSE-STATUS attribute, which in 4GL is the
        * integer value 4.
        */
       public static final int SAX_PARSER_ERROR = 4;

       /**
        * List of possible states of SAX-READER object, returned by the PARSE-STATUS attribute:
        * <ul>
        * <li>{@link #SAX_UNINITIALIZED} -The SAX-UNINITIALIZED constant which in 4GL is the integer
        * value 1.</li>
        * <li>{@link #SAX_RUNNING} - The SAX-RUNNING constant which in 4GL is the integer 2.</li>
        * <li>{@link #SAX_COMPLETE} - The SAX-COMPLETE constant which in 4GL is the integer 3.</li>
        * <li>{@link #SAX_PARSER_ERROR} - The SAX-PARSER-ERROR constant which in 4GL is the integer 4.
        * </li>
        * </ul>
        */
       enum ReadStatus
       {
          SAX_UNINITIALIZED(1, "SAX-UNINITIALIZED"),
          SAX_RUNNING(2, "SAX-RUNNING"),
          SAX_COMPLETE(3, "SAX-COMPLETE"),
          SAX_PARSER_ERROR(4, "SAX-PARSER-ERROR");

          /** 4gl constant value */
          private final int status;

          /** 4gl constant name */
          private final String name;

          /**
           * Default constructor for enum.
           * @param   status
           *          4gl integer representation of sax reader status.
           * @param   name
           *          Name of 4gl sax reader status.
           */
          ReadStatus(int status, String name)
          {
             this.status = status;
             this.name = name;
          }

          /**
           * Returns the 4gl name of this enum constant.
           *
           * @return See above.
           */
          public String getName()
          {
             return name;
          }

          /**
           * Returns the 4gl value of this enum constant.
           *
           * @return See above.
           */
          public int getStatus()
          {
             return status;
          }

          /**
           * Returns the name of this enum constant, as contained in the
           * declaration.  This method may be overridden, though it typically
           * isn't necessary or desirable.  An enum type should override this
           * method when a more "programmer-friendly" string form exists.
           *
           * @return the name of this enum constant
           */
          @Override
          public String toString()
          {
             return name;
          }
       }
       // Attributes

       /**
        * Gets the value of the handler attribute for the given SAX Reader object.
        *
        * @return   The handle variable representing the handler attribute.
        */
       @LegacyAttribute(name = "HANDLER")
       public handle getHandler();

       /**
        * Sets the value of the handler attribute for the given SAX Reader object.
        *
        * @param    hCallback
        *           The handle of the new callback handler to be set for the handler attribute.
        */
       @LegacyAttribute(name = "HANDLER", setter = true)
       public void setHandler(handle hCallback);

       /**
        * Gets the value of the current 1-based column in XML source.
        *
        * @return   The integer value of the current column.
        */
       @LegacyAttribute(name = "LOCATOR-COLUMN-NUMBER")
       public integer getLocatorColumnNumber();

       /**
        * Gets the value of the current 1-based line number in XML source.
        *
        * @return   The integer value of the current line.
        */
       @LegacyAttribute(name = "LOCATOR-LINE-NUMBER")
       public integer getLocatorLineNumber();

       /**
        * Gets the current value of the parse status. The default value is
        * {@link ReadStatus#SAX_UNINITIALIZED}. The other returned values are
        * {@link ReadStatus#SAX_COMPLETE}, {@link ReadStatus#SAX_PARSER_ERROR} or
        * {@link ReadStatus#SAX_RUNNING}.
        *
        * @return   The integer value representing the current status of the parse.
        */
       @LegacyAttribute(name = "PARSE-STATUS")
       public integer getParseStatus();

       /**
        * Gets the current value of the public identifier of the current XML source.
        *
        * @return   The character value representing the current locator-public-id attribute.
        */
       @LegacyAttribute(name = "LOCATOR-PUBLIC-ID")
       public character getLocatorPublicId();

       /**
        * Gets the current value of the system identifier of the current XML source.
        *
        * @return   The character value representing the current locator-system-id attribute.
        */
       @LegacyAttribute(name = "LOCATOR-SYSTEM-ID")
       public character getLocatorSystemId();

       /**
        * Sets the current value of the namespace location pair mapping.
        *
        * @param    location
        *           The new value the current schema-location attribute.
        */
       @LegacyAttribute(name = "SCHEMA-LOCATION", setter = true)
       public void setSchemaLocation(String location);

       /**
        * Sets the delimiter separated list of directory paths used to locate XML DTD associated with
        * a particular XML document.
        *
        * @param    path
        *           The new value the current schema-path attribute.
        */
       @LegacyAttribute(name = "SCHEMA-PATH", setter = true)
       public void setSchemaPath(String path);

       /**
        * Indicates if the parser validates the XML document against DTD or not.
        *
        * @return   The logical value representing the current validation-enabled attribute.
        */
       @LegacyAttribute(name = "VALIDATION-ENABLED")
       public logical getValidationEnabled();

       /**
        * Redefines whether the parser will validate the XML document against DTD or not.
        *
        * @param    enable
        *           The new value the current validation-enabled attribute.
        */
       @LegacyAttribute(name = "VALIDATION-ENABLED", setter = true)
       public void setValidationEnabled(logical enable);

       /**
        * Redefines whether the parser will validate the XML document against DTD or not.
        *
        * @param    enable
        *           The new value the current validation-enabled attribute.
        */
       @LegacyAttribute(name = "VALIDATION-ENABLED", setter = true)
       public void setValidationEnabled(boolean enable);

       // Methods
       /**
        * Executing single call parse of an XML document associated with a SAX-Reader object.
        */
       @LegacyMethod(name = "SAX-PARSE")
       public void saxParse();

       /**
        * Initializes and begins progressive-scan parse of an XML document associated with a
        * SAX-Reader object.
        */
       @LegacyMethod(name = "SAX-PARSE-FIRST")
       public void saxParseFirst();

       /**
        * Continues progressive-scan parse of an XML document associated with a SAX-Reader object.
        */
       @LegacyMethod(name = "SAX-PARSE-NEXT")
       public void saxParseNext();

       /**
        * Specifies the input source of the XML document to be parsed by a SAX-Reader object.
        *
        * @param    mode
        *           The type of the object to process. Can be 'FILE', 'HANDLE', 'MEMPTR' or
        *           'LONGCHAR'.
        * @param    source
        *           The appropriate object to process.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "SET-INPUT-SOURCE")
       public logical setInputSource(String mode, Object source);

       /**
        * Specifies the input source of the XML document to be parsed by a SAX-Reader object.
        *
        * @param    mode
        *           The type of the object to process. Can be 'FILE', 'HANDLE', 'MEMPTR' or
        *           'LONGCHAR'.
        * @param    source
        *           The appropriate object to process.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "SET-INPUT-SOURCE")
       public logical setInputSource(character mode, Object source);

       /**
        * Causes parser to stop parsing the XML document.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "STOP-PARSING")
       public logical stopParsing();
    }