/* 
 * OdbTools application interface.
 * @author Alberto Corni,  Gen 2000
 */
module OdbToolsApplic {



  /*
   * SERVANT object, provides OdbTools functionalities.
   * <p>
   * Here are declared all functionalities available by Odb-Tools.
   */
  interface OdbTools {

     /*
      * Translate a schema described in ODL into a OLCD description.
      * <p>
      * @param odl  The original schema description.
      * @param odcl The returned schema description.
      * @return the standard output and error of the ODB-Tools translator.
      */
     string translate_Odl_Olcd ( in string odl, out string olcd );

     /*
      * Translate a schema described in ODL into a OLCD description.
      * <p>
      * @param odl  The original schema description.
      * @param odcl The returned schema description.
      * @param vf   The returned schema description in VF format.
      *             This format is used by the ODB-Tools graphical
      *             schema visualizer.
      * @return the standard output and error of the ODB-Tools translator.
      */
     string translate_Odl_Olcd_vf ( in string odl, 
				     out string olcd, 
				     out string vf );

     /*
      * Translate and validate schema described in ODL.
      * ODB-Tools internally translate the schema into OLCD
      * and runs the Validator. The validator optimizes the schema
      * and, if exists, signals incoherences.
      * <p>
      * @param odl  The original schema description.
      * @param fc   The returned CANONICAL FORM of the schema.
      *             The CANONICAL FORM is a description of all
      *             possible inferences that can be applied to the schema
      *             described in a ODB-Tools internal format.
      * @return the standard output of the ODB-Tools translator ad validator.
      */
     string validate_Odl ( in string odl, out string fc );

     /*
      * Validates only a previously Translated schema.
      * If the ODB-Tools translator has already been runned on a schema
      * using this method it is possible to run the validator only.
      * The validator optimizes the schema
      * and, if exists, signals incoherences.
      * <p>
      * @param fc   The returned CANONICAL FORM of the schema.
      *             The CANONICAL FORM is a description of all
      *             possible inferences that can be applied to the schema
      *             described in a ODB-Tools internal format.
      * @return the standard output of the ODB-Tools validator.
      */
     string validate_OdlSS ( out string fc );

     /*
      * Validates only a previously Translated schema.
      * If the ODB-Tools translator has already been runned on a schema
      * using this method it is possible to run the validator only.
      * The validator optimizes the schema
      * and, if exists, signals incoherences.
      * <p>
      * @param fc   The returned CANONICAL FORM of the schema.
      *             The CANONICAL FORM is a description of all
      *             possible inferences that can be applied to the schema
      *             described in a ODB-Tools internal format.
      * @param vf   The returned optimized schema description in VF format.
      *             This format is used by the ODB-Tools graphical
      *             schema visualizer.
      * @return the standard output of the ODB-Tools validator.
      */
     string validate_OdlSS_vf ( out string fc, out string vf );

     /*
      * Optimize a OQL query on a ODL schema.
      * The ODB-Tools query optimizer optimizes a OQL query on
      * a given schema.
      * <p>
      * ODB-Tools runs the translation and validation steps on the 
      * ODL schema then optimize the OQL schema on the optimized schema.
      * @param odl    The original schema description.
      * @param oql    The original query to optimize.
      * @param stdOut The standard output of the translator and validator.
      * @return the optimzed query described in OQL.
      */
     string optimize_Oql ( in string odl, in string oql, out string stdOut  );

     /*
      * Optimizes a OQL query on a previously validated schema.
      * If the ODB-Tools validator has already been runned on a schema
      * using this method it is possible to run the query optimizer only.
      * The ODB-Tools query optimizer optimizes a OQL query on
      * a given schema.
      * <p>
      * ODB-Tools runs the translation and validation steps on the 
      * ODL schema then optimize the OQL schema on the optimized schema.
      * @param oql    The original query to optimize.
      * @return the optimzed query described in OQL.
      */
     string optimize_OqlSS ( in string oql );

     /*
      * Optimizes a OQL query on a previously validated schema.
      * If the ODB-Tools validator has already been runned on a schema
      * using this method it is possible to run the query optimizer only.
      * The ODB-Tools query optimizer optimizes a OQL query on
      * a given schema.
      * <p>
      * ODB-Tools runs the translation and validation steps on the 
      * ODL schema then optimize the OQL schema on the optimized schema.
      * @param oql    The original query to optimize.
      * @param vf   The returned optimized schema description in VF format.
      *             This format is used by the ODB-Tools graphical
      *             schema visualizer and contains the description
      *             of the schema and the "postion" of the query showing
      *             how the optimization runned.
      * @return the optimzed query described in OQL.
      */
     string optimize_OqlSS_vf ( in string oql, out string vf );

     /*
      * Kills the current object and free its resources.
      * <p>
      *  Each ODB-Tools functionalities request is served by a SERVANT
      *  object. 
      *  The SERVER object is unique, it serves new request 
      *  of services creating new SERVANT objects
      *  and manage existing SERVANT killing them for example after a 
      *  time out period.
      * @return  ever returns the 0 (zero) value.
      */
     long killObject();
  };

  /*
   * Main SERVER Object.
   * <p>
   *  Each ODB-Tools functionalities request is served by a SERVANT
   *  object. 
   *  The SERVER object is unique, it serves new request 
   *  of services creating new SERVANT objects
   *  and manage existing SERVANT killing them for example after a 
   *  time out period.
   * <p>
   *  The only functionality provided by the server object is the
   *  possibility of creating a new SERVANT object.
   */
  interface OdbToolsFactory  {
     /*
      * Creates a new SERVANT object.
      * @param description Description of the new SERVANT object.
      *                    Such description is provided at connection time
      *                    form the client. 
      *                    Is a week way to identify the client.
      */
     OdbTools newServant ( in string description );
  };


};