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();
}