# LegacyJavaAppserverApi.java

    /*
    ** Module   : LegacyJavaAppserverApi.java
    ** Abstract : Definitions of helper APIs to replace the legacy Java Open Client.
    **
    ** Copyright (c) 2019-2024, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- ---------------------------------------Description----------------------------------------
    ** 001 CA  20190717 Created initial version.
    ** 002 CA  20191119 Added more data-types (clob, recid, raw, rowid, unknown).
    ** 003 CA  20200923 API improvements. Added extent support, other data-types.  Allow access to the hidden
    **                  temp-table fields.
    **     CA  20201008 Added HANDLE type.  Added addRelation API.
    **     OM  20201120 Added support for xmlNodeName and errorString table attributes.
    **     CA  20210213 Modifying the signature of APIs in this class may result in incompatibilities with other
    **                  existing code, either in TRPL rules (for the proxy generation code), or in 3rd party
    **                  customer apps.  Always leave the previous signature and mark it as deprecated.
    **     CA  20210917 Javadoc fixes.
    **     CA  20220615 Added 'getBeforeObjects'.
    **     CA  20220428 Added TABLE and extent parameter support.
    **     CA  20220513 Added 'getTableIndex' helpers.
    **     CA  20220524 Added helpers which work with table metadata, to retrieve field information.
    **     CA  20220527 Added helpers for relation metadata.
    ** 004 CA  20230221 Encapsulated the field and relation metadata in their own classes, to avoid the DataObject
    **                  overhead and increase performance.  Other performance optimizations.
    ** 005 CA  20240305 Added namespace URI, namespace prefix and XML node-name for table/graph metadata in
    **                  OpenClient.
    */

    /*
    ** 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.util;

    import java.util.*;

    import com.goldencode.p2j.*;
    import com.goldencode.p2j.cfg.*;

    import commonj.sdo.*;

    /**
     * Defines APIs to work as a replacement for the legacy Java Open Client.
     */
    public interface LegacyJavaAppserverApi
    {
       /** Value  for INPUT mode. */
       public static final int INPUT = 1;

       /** Value  for OUTPUT mode. */
       public static final int OUTPUT = 2;

       /** Value  for INPUT-OUTPUT mode. */
       public static final int INPUT_OUTPUT = 3;

       /** Value for {@link handle} type. */
       public static final int TYPE_HANDLE = -100000;

       /** Value for {@link integer} type. */
       public static final int TYPE_INTEGER = 4;

       /** Value for {@link int64} type. */
       public static final int TYPE_INT64 = 41;

       /** Value for {@link decimal} type. */
       public static final int TYPE_DECIMAL = 5;

       /** Value for {@link memptr} type. */
       public static final int TYPE_MEMPTR = 11;

       /** Value for {@link blob} type. */
       public static final int TYPE_BLOB = 18;

       /** Value for {@link clob} type. */
       public static final int TYPE_CLOB = 19;

       /** Value for {@link character} type. */
       public static final int TYPE_CHARACTER = 1;

       /** Value for {@link longchar} type. */
       public static final int TYPE_LONGCHAR = 39;

       /** Value for {@link logical} type. */
       public static final int TYPE_LOGICAL = 3;

       /** Value for {@link date} type. */
       public static final int TYPE_DATE = 2;

       /** Value for {@link datetime} type. */
       public static final int TYPE_DATETIME = 34;

       /** Value for {@link datetimetz} type. */
       public static final int TYPE_DATETIMETZ = 40;

       /** Value for {@link recid} type. */
       public static final int TYPE_RECID = 7;

       /** Value for {@link raw} type. */
       public static final int TYPE_RAW = 8;

       /** Value for {@link rowid} type. */
       public static final int TYPE_ROWID = 13;

       /** Value for {@link unknown} type. */
       public static final int TYPE_UNKNOWN = 16;

       /** Value for {@link com.goldencode.p2j.persist.DataSetContainer} type. */
       public static final int TYPE_DATASET = 36;

       /** Value for {@link com.goldencode.p2j.persist.DataSetContainer} type. */
       public static final int TYPE_DATASET_HANDLE = 37;

       /** Value for {@link com.goldencode.p2j.persist.DataSetContainer} type. */
       public static final int TYPE_TABLE = 15;

       /** Value for {@link com.goldencode.p2j.persist.TempTableResultSet} type. */
       public static final int TYPE_TABLE_HANDLE = 17;

       /**
        * Get the value for INPUT mode.
        *
        * @return   The {@link #INPUT}.
        */
       public default int input()
       {
          return INPUT;
       }

       /**
        * Get the value for OUTPUT mode.
        *
        * @return   The {@link #OUTPUT}.
        */
       public default int output()
       {
          return OUTPUT;
       }

       /**
        * Get the value for INPUT-OUTPUT mode.
        *
        * @return   The {@link #INPUT_OUTPUT}.
        */
       public default int inputOutput()
       {
          return INPUT_OUTPUT;
       }

       /**
        * Get the type for a HANDLE.
        *
        * @return   The {@link #TYPE_HANDLE}.
        */
       public default int handle()
       {
          return TYPE_HANDLE;
       }

       /**
        * Get the type for a INTEGER.
        *
        * @return   The {@link #TYPE_INTEGER}.
        */
       public default int integer()
       {
          return TYPE_INTEGER;
       }

       /**
        * Get the type for a INT64.
        *
        * @return   The {@link #TYPE_INT64}.
        */
       public default int int64()
       {
          return TYPE_INT64;
       }

       /**
        * Get the type for a DECIMAL.
        *
        * @return   The {@link #TYPE_DECIMAL}.
        */
       public default int decimal()
       {
          return TYPE_DECIMAL;
       }

       /**
        * Get the type for a MEMPTR.
        *
        * @return   The {@link #TYPE_MEMPTR}.
        */
       public default int memptr()
       {
          return TYPE_MEMPTR;
       }

       /**
        * Get the type for a BLOB.
        *
        * @return   The {@link #TYPE_BLOB}.
        */
       public default int blob()
       {
          return TYPE_BLOB;
       }

       /**
        * Get the type for a CLOB.
        *
        * @return   The {@link #TYPE_CLOB}.
        */
       public default int clob()
       {
          return TYPE_CLOB;
       }

       /**
        * Get the type for a RAW.
        *
        * @return   The {@link #TYPE_RAW}.
        */
       public default int raw()
       {
          return TYPE_RAW;
       }

       /**
        * Get the type for a ROWID.
        *
        * @return   The {@link #TYPE_ROWID}.
        */
       public default int rowid()
       {
          return TYPE_ROWID;
       }

       /**
        * Get the type for a RECID.
        *
        * @return   The {@link #TYPE_RECID}.
        */
       public default int recid()
       {
          return TYPE_RECID;
       }

       /**
        * Get the type for a UNKNOWN.
        *
        * @return   The {@link #TYPE_UNKNOWN}.
        */
       public default int unknown()
       {
          return TYPE_UNKNOWN;
       }

       /**
        * Get the type for a CHARACTER.
        *
        * @return   The {@link #TYPE_CHARACTER}.
        */
       public default int character()
       {
          return TYPE_CHARACTER;
       }

       /**
        * Get the type for a LONGCHAR.
        *
        * @return   The {@link #TYPE_LONGCHAR}.
        */
       public default int longchar()
       {
          return TYPE_LONGCHAR;
       }

       /**
        * Get the type for a LOGICAL.
        *
        * @return   The {@link #TYPE_LOGICAL}.
        */
       public default int logical()
       {
          return TYPE_LOGICAL;
       }

       /**
        * Get the type for a DATE.
        *
        * @return   The {@link #TYPE_DATE}.
        */
       public default int date()
       {
          return TYPE_DATE;
       }

       /**
        * Get the type for a DATETIME.
        *
        * @return   The {@link #TYPE_DATETIME}.
        */
       public default int datetime()
       {
          return TYPE_DATETIME;
       }

       /**
        * Get the type for a DATETIME-TZ.
        *
        * @return   The {@link #TYPE_DATETIMETZ}.
        */
       public default int datetimetz()
       {
          return TYPE_DATETIMETZ;
       }

       /**
        * Get the type for a DATASET.
        *
        * @return   The {@link #TYPE_DATASET}.
        */
       public default int dataset()
       {
          return TYPE_DATASET;
       }

       /**
        * Get the type for a TABLE.
        *
        * @return   The {@link #TYPE_TABLE}.
        */
       public default int table()
       {
          return TYPE_TABLE;
       }

       /**
        * Get the type for a DATASET-HANDLE.
        *
        * @return   The {@link #TYPE_DATASET_HANDLE}.
        */
       public default int datasetHandle()
       {
          return TYPE_DATASET_HANDLE;
       }

       /**
        * Get the type for a TABLE-HANDLE.
        *
        * @return   The {@link #TYPE_TABLE_HANDLE}.
        */
       public default int tableHandle()
       {
          return TYPE_TABLE_HANDLE;
       }

       /**
        * Get all the records for the table on the specified index, in the graph metadata.
        *
        * @param    graph
        *           The graph.
        * @param    idx
        *           The table index.
        *
        * @return   The list of rows.
        */
       public List<DataObject> getDataObjects(DataGraph graph, int idx);

       /**
        * Get all the records for the table with the specified name, in this graph.
        *
        * @param    graph
        *           The graph.
        * @param    table
        *           The table name.
        *
        * @return   The list of rows.
        */
       public List<DataObject> getDataObjects(DataGraph graph, String table);

       /**
        * Get all the records for the specified table.
        *
        * @param    tableMeta
        *           The table metadata.
        *
        * @return   The list of rows.
        */
       public List<DataObject> getDataObjects(DataObject tableMeta);

       /**
        * Get the before-table rows for this after-table.
        *
        * @param    tableMeta
        *           The after-table metadata.
        *
        * @return   The list of before-table rows.
        */
       public List<DataObject> getBeforeObjects(DataObject tableMeta);

       /**
        * Get the child rows for this record.
        *
        * @param    row
        *           The row.
        * @param    relation
        *           The child relation.
        *
        * @return   The child rows.
        */
       public List<DataObject> getChildRows(DataObject row, String relation);

       /**
        * Get the row's property on the given index as a {@link GregorianCalendar}.
        *
        * @param    row
        *           The row.
        * @param    idx
        *           The property index.
        */
       public GregorianCalendar getGregorianCalendar(DataObject row, int idx);

       /**
        * Set the field's property on the given index from the {@link GregorianCalendar} instance.
        *
        * @param    row
        *           The row.
        * @param    idx
        *           The property index.
        * @param    date
        *           The property's value.
        */
       public void setGregorianCalendar(DataObject row, int idx, GregorianCalendar date);

       /**
        * Get the row's property as a {@link GregorianCalendar}.
        *
        * @param    row
        *           The row.
        * @param    name
        *           The property name.
        *
        * @return   The calendar instance.
        */
       public GregorianCalendar getGregorianCalendar(DataObject row, String name);

        /**
         * Create a new graph to hold a dataset.  It holds just the root <code>graph</code> node.
         *
         * @return   A graph with no metadata.
         */
       public DataGraph createDataGraph();

       /**
        * Create a new metadata object to hold the table details.
        *
        * @param    metadata
        *           The root graph node.
        *
        * @return   The graph metadata object.
        */
       public DataGraph createDataGraph(Object metadata);

       /**
        * Create a new row for the specified table.  This row is not attached to the table - use
        * {@link #addDataObject(DataGraph, DataObject)} to add it.
        *
        * @param    graph
        *           The graph.
        * @param    table
        *           The table name.
        *
        * @return   A new, empty, row.
        */
       public DataObject createDataObject(DataGraph graph, String table);

       /**
        * Create a new row for the specified table.    This row is not attached to the table - use
        * {@link #addDataObject(DataObject, DataObject)} to add it.
        *
        * @param    tableMetaData
        *           The table metadata.
        *
        * @return   The new row.
        */
       public DataObject createDataObject(DataObject tableMetaData);

       /**
        * Add the specified row to the graph.
        *
        * @param    graph
        *           The field's graph.
        * @param    row
        *           The row to add to the table.
        */
       public void addDataObject(DataGraph graph, DataObject row);

       /**
        * Add the specified row to the graph.
        *
        * @param    tableMetaData
        *           The table metadata.
        * @param    row
        *           The row to add to the table.
        */
       public void addDataObject(DataObject tableMetaData, DataObject row);

       /**
        * Get the table name for a given row or table metadata.
        *
        * @param    value
        *           The table row or table metadata.
        *
        * @return   The table name.
        */
       public String getTableName(DataObject value);

       /**
        * Get the table index for a given row or table metadata.
        *
        * @param    value
        *           The table row or table metadata.
        *
        * @return   The table index, 0-based.
        *
        * @throws   NullPointerException
        *           If the row is not attached to a table.
        */
       public int getTableIndex(DataObject value);

       /**
        * Get the table index for a given table name and data graph.
        *
        * @param    graph
        *           The data graph.
        * @param    name
        *           The table name.
        *
        * @return   The table index, 0-based.
        *
        * @throws   IllegalArgumentException
        *           If the table is not part of this graph.
        */
       public int getTableIndex(DataGraph graph, String name);

       /**
        * Get the table index for a given table name and data graph metadata.
        *
        * @param    metadata
        *           The graph metadata.
        * @param    name
        *           The table name.
        *
        * @return   The table index, 0-based.
        *
        * @throws   IllegalArgumentException
        *           If the table is not part of this graph.
        */
       public int getTableIndex(DataObject metadata, String name);

       /**
        * Get the data graph name for the given table metadata.
        *
        * @param     tableMetadata
        *            The table metadata.
        *
        * @return    The data graph name or <code>null</code> if the table is not part of a graph.
        */
       public String getGraphName(DataObject tableMetadata);

       /**
        * Get the legacy field metadata from the given table's metadata.
        *
        * @param    tableMetadata
        *           The table metadata.
        *
        * @return   The metadata for all the table's fields, in their definition order.
        */
       public LegacyFieldMetaData[] getTableFields(DataObject tableMetadata);

       /**
        * Get the legacy field metadata from the given row.
        *
        * @param    row
        *           The row.
        *
        * @return   The metadata for all the table's fields, in their definition order.
        */
       public LegacyFieldMetaData[] getFields(DataObject row);

       /**
        * Get the number of fields for a given row.
        *
        * @param    row
        *           The table row.
        *
        * @return   The number of fields as specified in the table metadata.
        */
       public int getFieldCount(DataObject row);

       /**
        * Get the field names for the specified table meta.
        *
        * @param    tableMeta
        *           The table metadata.
        *
        * @return   The field names.
        */
       public String[] getTableFieldNames(DataObject tableMeta);

       /**
        * Get the number of fields for the specified table meta.
        *
        * @param    tableMeta
        *           The table metadata.
        *
        * @return   The field count.
        */
       public int getTableFieldCount(DataObject tableMeta);

       /**
        * Get the name of the field on the given index in the metadata.
        *
        * @param    row
        *           The table row.  Must be attached to a table.
        * @param    i
        *           The field index.
        *
        * @return   The field's name.
        */
       public String getFieldName(DataObject row, int i);

       /**
        * Get the type of the field on the given index in the metadata.
        *
        * @param    row
        *           The table row.  Must be attached to a table.
        * @param    i
        *           The field index.
        *
        * @return   The field's type.
        */
       public int getFieldType(DataObject row, int i);

       /**
        * Check if this table has a field defined with that name.
        *
        * @param    tableMetadata
        *           The table metadata.
        * @param    fieldName
        *           The field name.
        *
        * @return   <code>true</code> if there is a field defined with this name.
        */
       public boolean isTableField(DataObject tableMetadata, String fieldName);

       /**
        * Get the field type.
        *
        * @param    tableMetadata
        *           The table metadata.
        * @param    fieldName
        *           The field name.
        *
        * @return   The field type.
        */
       public int getTableFieldType(DataObject tableMetadata, String fieldName);

       /**
        * Get the field type.
        *
        * @param    tableMeta
        *           The table metadata.
        * @param    fieldIndex
        *           The field index.
        *
        * @return   See above.
        */
       public int getTableFieldType(DataObject tableMeta, int fieldIndex);

       /**
        * Get all table names from the given graph.
        *
        * @param    graph
        *           The graph.
        *
        * @return   See above.
        */
       public String[] getTableNames(DataGraph graph);

       /**
        * Get the number of tables for a graph.
        *
        * @param    graph
        *           The graph.
        *
        * @return   See above.
        */
       public int getNumTables(DataGraph graph);

       /**
        * Get the number of tables for a graph metadata.
        *
        * @param    metaData
        *           The graph metadata.
        *
        * @return   See above.
        */
       public int getNumTables(DataObject metaData);

       /**
        * Get the metadata object for this graph, from the <code>metadata</code> property of the root
        * object.
        *
        * @param    graph
        *           The graph.
        *
        * @return   The metadata object.
        */
       public DataObject getMetaData(DataGraph graph);

       /**
        * Get the metadata for the table registered on the given index in the graph.
        *
        * @param    metaData
        *           The graph metadata.
        * @param    i
        *           The table index.
        *
        * @return   The table metadata.
        */
       public DataObject getTableMetaData(DataObject metaData, int i);

       /**
        * Get the metadata for the specified table.
        *
        * @param    graph
        *           The graph.
        * @param    table
        *           The table name.
        *
        * @return   The table metadata or <code>null</code> if the table is not part of this graph.
        */
       public DataObject getTableMetaData(DataGraph graph, String table);

       /**
        * Get the metadata list for all tables.
        *
        * @param    graph
        *           The graph.
        *
        * @return   The metadata for all tables.
        */
       public List<DataObject> getTableMetaData(DataGraph graph);

       /**
        * Create an object with a table metadata.  This object will have the {@code tablemetadata} type and is not
        * attached to the graph.
        *
        * @param   name
        *          The table's name.
        * @param   numFields
        *          The number of fields.
        * @param   b4img
        *          Flag indicating if the table has a BEFORE-IMAGE.
        * @param   numIndexes
        *          The number of indexes.
        * @param   indexes
        *          The index specification.
        * @param   xmlns
        *          The XML namespace.
        * @param   xmlPrefix
        *          The XML prefix.
        *
        * @return   An object with the table metadata.
        */
       @Deprecated
       public DataObject createObjectMetaData(String  name,
                                              int     numFields,
                                              boolean b4img,
                                              int     numIndexes,
                                              String  indexes,
                                              String  xmlns,
                                              String  xmlPrefix);

       /**
        * Create an object with a table metadata.  This object will have the {@code tablemetadata} type and is not
        * attached to the graph.
        *
        * @param   name
        *          The table's name.
        * @param   numFields
        *          The number of fields.
        * @param   b4img
        *          Flag indicating if the table has a BEFORE-IMAGE.
        * @param   numIndexes
        *          The number of indexes.
        * @param   indexes
        *          The index specification.
        * @param   xmlns
        *          The XML namespace.
        * @param   xmlPrefix
        *          The XML prefix.
        * @param   xmlNodeName
        *          The XML node name.
        * @param   errorString
        *          The table's ERROR-STRING attribute.
        *
        * @return   An object with the table metadata.
        */
       public DataObject createObjectMetaData(String  name,
                                              int     numFields,
                                              boolean b4img,
                                              int     numIndexes,
                                              String  indexes,
                                              String  xmlns,
                                              String  xmlPrefix,
                                              String  xmlNodeName,
                                              String  errorString);

       /**
        * Add a new new field with the specified configuration.
        *
        * @param    metaData
        *           The table metadata, of type <code>tablemetadata</code>.  The field will be added
        *           to the <code>fields</code> property.
        * @param    idx
        *           The field's index in the metadata.
        * @param    name
        *           The field's name.
        * @param    extent
        *           The field's extent.
        * @param    type
        *           The legacy type (numeric value based on {@link LegacyJavaAppserver} constants.
        * @param    order
        *           The field's order.
        * @param    xmlMapping
        *           The field's mapping.
        */
       public void setFieldMetaData(DataObject metaData,
                                    int        idx,
                                    String     name,
                                    int        extent,
                                    int        type,
                                    int        order,
                                    int        xmlMapping);

       /**
        * Create a metadata object with the specified name.
        *
        * @param    name
        *           The graph name.
        *
        * @return   The metadata object.  Will be attached to a graph via {@link #createDataGraph(Object)}.
        */
       public DataObject createGraphMetaData(String name);

       /**
        * Add the specified table metadata to the graph.  This will create a custom type based on the
        * configured fields, so that each row will be created with this type.
        *
        * @param    metaData
        *           The graph metadata.
        * @param    table
        *           The table metadata.
        */
       public void addTableMetaData(DataObject metaData, DataObject table);

       /**
        * Copy the single table from the provided DataGraph to the given graph metadata (i.e. attach a table
        * to a data-set).
        *
        * @param    metaData
        *           The graph metadata.
        * @param    table
        *           The table representation, in a {@link #createDataGraph} format.
        */
       public void addTableMetaData(DataObject metaData, DataGraph table);

       /**
        * Get the graph name from the specified metadata, of type <code>graphmetadata</code>.
        *
        * @param    metadata
        *           The metadata.
        *
        * @return   The graph name.
        */
       public String getDataGraphName(DataObject metadata);

       /**
        * Get the namespace URI from the given metadata.
        *
        * @param    metadata
        *           The graph or table metadata.
        *
        * @return   See above.
        */
       public String getNamespaceURI(DataObject metadata);

       /**
        * Set the namespace URI for the given metadata.
        *
        * @param    metadata
        *           The graph or table metadata.
        * @param    xmlns
        *           The namespace URI.
        */
       public void setNamespaceURI(DataObject metadata, String xmlns);

       /**
        * Get the namespace prefix from the given metadata.
        *
        * @param    metadata
        *           The graph or table metadata.
        *
        * @return   See above.
        */
       public String getNamespacePrefix(DataObject metadata);

       /**
        * Set the namespace prefix for the given metadata.
        *
        * @param    metadata
        *           The graph or table metadata.
        * @param    xmlPrefix
        *           The namespace prefix.
        */
       public void setNamespacePrefix(DataObject metadata, String xmlPrefix);

       /**
        * Get the XML node-name from the given metadata.
        *
        * @param    metadata
        *           The graph or table metadata.
        *
        * @return   See above.
        */
       public String getXmlNodeName(DataObject metadata);

       /**
        * Set the XML node-name for the given metadata.
        *
        * @param    metadata
        *           The graph or table metadata.
        * @param    xmlNodeName
        *           The XML node name.
        */
       public void setXmlNodeName(DataObject metadata, String xmlNodeName);

       /**
        * Configure a {@link LegacyJavaAppserverParameter} with the given details.
        *
        * @param    mode
        *           The parameter mode.
        * @param    type
        *           The parameter type.
        * @param    value
        *           The parameter value.
        * @param    metadata
        *           The parameter metadata (in case of DataSet).
        *
        * @return   A new parameter instance.
        */
       public LegacyJavaAppserverParameter getJavaParameter(int mode, int type, Object value, Object metadata);

       /**
        * Configure a {@link LegacyJavaAppserverParameter} with the given details.
        *
        * @param    mode
        *           The parameter mode.
        * @param    type
        *           The parameter type.
        * @param    value
        *           The parameter value.
        * @param    metadata
        *           The parameter metadata (in case of DataSet).
        *
        * @return   A new parameter instance.
        */
       public LegacyJavaAppserverParameter getJavaParameter(int    mode,
                                                            int    type,
                                                            int    extent,
                                                            Object value,
                                                            Object metadata);

       /**
        * Determine the output parameter value.
        *
        * @param    param
        *           The parameter as received from the remote side.
        *
        * @return   The parameter's output value.
        */
       public Object getOutputParameter(LegacyJavaAppserverParameter param);

       /**
        * Determine the output parameter value on the given index.
        *
        * @param    paramArray
        *           The parameter array.
        * @param    i
        *           The parameter's index.
        *
        * @return   The parameter's output value.
        */
       public Object getOutputParameter(LegacyJavaAppserverParameter[] paramArray, int i);

       /**
        * Get a string representation of the argument's modes.
        *
        * @param    paramArray
        *           The parameter array.
        *
        * @return   The parameter modes.
        */
       public String getArgumentModes(LegacyJavaAppserverParameter[] paramArray);

       /**
        * Resolve the arguments from the given parameter array.
        *
        * @param    paramArray
        *           The parameter array.
        *
        * @return   The arguments.
        */
       public Object[] getArguments(LegacyJavaAppserverParameter[] paramArray);

       /**
        * Create a memptr corresponding instance.
        *
        * @param    value
        *           The bytes.
        *
        * @return   A memptr compatible instance.
        */
       public Object createMemptr(byte[] value);

       /**
        * Check if the given parameter is a memptr.
        *
        * @param    outputParameter
        *           The parameter.
        *
        * @return   See above.
        */
       public boolean isMemptr(Object outputParameter);

       /**
        * Get the bytes from the given output parameter, which is a memptr compatible instance.
        *
        * @param    outputParameter
        *           The output parameter.
        *
        * @return   See above.
        */
       public byte[] getBytes(Object outputParameter);

       /**
        * Create a new FWd connection with the specified configuration.
        *
        * @param    config
        *           The configuration for the FWD server connection.
        * @param    account
        *           The FWD account to authenticate on the remote side.
        * @param    appServerName
        *           The name of the appserver to which the connection will be established.
        * @param    sessionFree
        *           <code>true</code> to indicate a session-free operating mode, <code>false</code>
        *           to indicate a session-managed operating mode.
        * @param    user
        *           The username passed to the appserver's connect procedure.
        * @param    pwd
        *           The password passed to the appserver's connect procedure.
        * @param    serverInfo
        *           The info passed to the appserver's connect procedure.
        *
        * @return   The helper with the connection result (which was established or not).
        *
        * @throws   NumberedException
        *           If there are connection problems.
        */
       public AppServerHelper getConnection(BootstrapConfig   config,
                                            String            account,
                                            String            appServerName,
                                            boolean           sessionFree,
                                            String            user,
                                            String            pwd,
                                            String            serverInfo)
       throws NumberedException;

       /**
        * Postprocess these arguments - this includes copying state back to the
        * {@link LegacyJavaAppserverParameter} instance, for OUTPUT parameters.
        *
        * @param    paramArray
        *           The parameter array.
        * @param    args
        *           The returned arguments.
        */
       public void postProcessArguments(Object paramArray, Object[] args);

       /**
        * Get the changes in this change summary, as a graph.
        *
        * @param    changeSummary
        *           The change summary.
        *
        * @return   See above.
        */
       public DataGraph getChanges(Object changeSummary);

       /**
        * End the logging for changes in this object.
        *
        * @param    changeSummary
        *           The change summary.
        */
       public void endLogging(Object changeSummary);

       /**
        * Begin the logging for changes in this object.
        *
        * @param    changeSummary
        *           The change summary.
        */
       public void beginLogging(Object changeSummary);

       /**
        * Get the change summary object for this graph.
        *
        * @param    graph
        *           The graph.
        *
        * @return   See above.
        */
       public Object getChangeSummary(DataGraph graph);

       /**
        * Check if the given object has been deleted.
        *
        * @param    changeSummary
        *           The change summary.
        * @param    object
        *           The object.
        *
        * @return   See above.
        */
       public boolean isDeleted(Object changeSummary, DataObject object);

       /**
        * Check if the given object is newly created.
        *
        * @param    changeSummary
        *           The change summary.
        * @param    object
        *           The object.
        *
        * @return   See above.
        */
       public boolean isCreated(Object changeSummary, DataObject object);

       /**
        * Get all the changed objects in this change summary.
        *
        * @param    changeSummary
        *           The change summary.
        *
        * @return   See above.
        */
       public List<DataObject> getChangedDataObjects(Object changeSummary);

       /**
        * Retrieve all rows which have an exact match for the specified fields.
        *
        * @param    tableMetadata
        *           The table metadata.
        * @param    fields
        *           The field list.
        * @param    values
        *           The values to be matched.
        *
        * @return   See above.
        */
       public List<DataObject> selectRows(DataObject tableMetadata, String[] fields, Object[] values);

       /**
        * Add a relation to the graph's metadata.
        *
        * @param    metaData
        *           The graph metadata.
        * @param    name
        *           The relation name.
        * @param    parentBuffer
        *           The parent buffer.
        * @param    childBuffer
        *           The child buffer.
        * @param    whereString
        *           The where string.
        * @param    active
        *           Flag indicating if this relation is active.
        * @param    parentId
        *           Flag indicating if parent-id is used.
        * @param    pairs
        *           The field pairs, in <code>parent, child</code> format.
        * @param    fkeyHidden
        *           Flag indicating if fkey-hidden is used.
        * @param    recursive
        *           Flag indicating if recursive is used.
        * @param    nested
        *           Flag indicating if nested is used.
        * @param    reposition
        *           Flag indicating if reposition is used.
        */
       public void addRelation(DataObject metaData,
                               String name,
                               String parentBuffer,
                               String childBuffer,
                               String whereString,
                               boolean active,
                               boolean parentId,
                               String pairs,
                               boolean fkeyHidden,
                               boolean recursive,
                               boolean nested,
                               boolean reposition);

       /**
        * Get the relation metadata with the given name.
        *
        * @param    graph
        *           The data graph.
        * @param    name
        *           The relation name.
        *
        * @return   The relation metadata, or <code>null</code> if it does not exist.
        */
       public LegacyRelationMetaData getRelation(DataGraph graph, String name);

       /**
        * Get the relation metadata with the given name.
        *
        * @param    metaData
        *           The graph metadata.
        * @param    name
        *           The relation name.
        *
        * @return   The relation metadata, or <code>null</code> if it does not exist.
        */
       public LegacyRelationMetaData getRelation(DataObject metaData, String name);

       /**
        * Get the all relation metadata from the given graph.
        *
        * @param    graph
        *           The data graph.
        *
        * @return   The relations metadata.
        */
       public LegacyRelationMetaData[] getRelations(DataGraph graph);

       /**
        * Get the all relation metadata from the given graph.
        *
        * @param    metaData
        *           The graph metadata.
        *
        * @return   The relations metadata.
        */
       public LegacyRelationMetaData[] getRelations(DataObject metaData);
    }