/* <PRE> *************************************************************************
 * Computing Research Laboratory, New Mexico State University
 * Box 30001 / Dept. 3CRL, Las Cruces, NM 88003-8001, USA                     
 * Tel.:   (505) 646-5861       Fax: (505) 646-6218                           
 * E-mail: mahesh@crl.nmsu.edu  
 * WWW: http://crl.nmsu.edu/Research/Projects/mikro/
 *                                                                            
 * AUTHOR: Kavi Mahesh                                                   
 * DATE: Jan 4 1997                                             
 *                                                                            
 * PURPOSE: Definition of an API for  Mikrokosmos Ontology 
 *
 * FORMAT: OMG's Interface Definition Language (IDL)
 *         This API has been compiled using an IDL compiler to test its syntax.
 *
 * This software is made available as is without any warranty or guarantee, implied or explicit.
 * The author, CRL, and NMSU are not responsible for any consequence of using this software.
 *
 * This software may be used for research and development purposes only.
 * It may not be used in a commercial product without a written license agreement with
 * CRL and New Mexico State University
 *
 * For information on the Mikrokosmos Ontology, please see the 
 * <A HREF="http://crl.nmsu.edu/Research/Projects/mikro/ontology/">Ontology Web pages.</A>
 ***************************************************************************/

/*****************Hierarchy Of Classes and Sub-Classes ***********************

 ontology
 frame
   concept
     Onto_object
     event
     property
       relation
       onto_attribute
   instance
 slot
 facet
 frames
 concepts
 instances
 slots
 facets
 fillers

Note: "object" and "attribute" are keywords in IDL. Hence using "onto_object" and "onto_attribute"
Note: onto_object and event are not defined below since they do not have any special methods as far as
this API is concerned.

*/

/***************************API  Module description************************/

/**************************************************************************
 *                         Module ontoApi
 * Interfaces: ontology, frame, slot, facet, concept, instance, property, relation, attribute
 *    Sequences: frames, concepts, instances, slots, facets, fillers.
 * Comments: Provides methods for using the Mikrokosmos Ontology.
 *          A separate API will be written later for editing/developing the Ontology.
 *
 **************************************************************************/

module ontoApi {

  /* Forward declarations of classes which are defined later.*/

interface frame;

interface concept;

interface instance;

interface slot;

interface facet;

 /* typedef's for sequences of objects.*/

 typedef sequence <frame> frames;

 typedef sequence <concept> concepts;

 typedef sequence <instance> instances;

 typedef sequence <slot> slots;

 typedef sequence <facet> facets;

 typedef sequence <string> fillers;

/* Exceptions used by many classes in this module */

 /* There is no frame in the ontology with the given string as its name */
 exception NoSuchFrame{};

 /* There is no concept in the ontology with the given string as its name */
 exception NoSuchConcept{};

 /* There is no instance in the ontology with the given string as its name */
 exception NoSuchInstance{};

 /* There is no slot with the given string as its name in the (inherited) frame */
 exception NoSuchSlot{};

 /* There is no facet with the given string as its name in the slot */
 exception NoSuchFacet{};

 /* There is no filler in the facet */
 exception NoFiller{};

 /* ontology has not been loaded into memory */
 exception NoOntologyLoaded{};

  /**************************************************************************
   *                       class ontology
   * Super-classes : None
   * Sub-classes : None
   * Methods : As listed below
   * Comments : 
   *   Top-level class used to package methods for loading the ontology and finding
    * frames in the ontology
   *************************************************************************/  

interface ontology {

 /* Could not open the specified file */
 exception BadFile{};

 /* No file open */
 exception NoOpenFile{};

    /*************************************************************************
     *  Method: openOntologyFile
     *  Description: open a file containing the ontology for loading
     *  Parameters: 
     *    in filename: a string specifying the path and file name
     *  Returns: void
     *  Exceptions: BadFile exception if the filename cannot be opened
     *         
     ************************************************************************/
     
      void openOntologyFile  (in string filename) 
            raises (BadFile);
      
    /*************************************************************************
     *  Method: loadOntology
     *  Description: loads the ontology into memory
     *  Parameters: none
     *  Returns: void
     *  Exceptions: NoOpenFile if the ontology file has not been opened for loading
     *         
     ************************************************************************/
     
      void  loadOntology ()
            raises (NoOpenFile);

         /*************************************************************************
     *  Method: closeOntologyFile
     *  Description: closes an open ontology file (after loading)
     *  Parameters: none
     *  Returns: void
     *  Exceptions: NoOpenFile if no ontology file is open
     *         
     ************************************************************************/
     
  void closeOntologyFile ()
            raises (NoOpenFile);
 
     /*************************************************************************
     *  Method: getFrame
     *  Description: finds a frame in the ontology with the given string as its name
     *  Parameters: 
     *    in name: a string that is the name of the frame
     *  Returns: a frame
     *  Exceptions: NoOntologyLoaded if the ontology has not been loaded into memory
     *                NoSuchFrame if there is no frame in the ontology with the given name
     *         
     ************************************************************************/
     
      frame getFrame (in string name)
             raises (NoOntologyLoaded, NoSuchFrame);

    /*************************************************************************
     *  Method: isFrame
     *  Description: is there a frame in the ontology with the given name
     *  Parameters: 
     *    in name: a string
     *  Returns: boolean
     *  Exceptions: NoOntologyLoaded if the ontology has not been loaded into memory
     *         
     ************************************************************************/
     
       boolean isFrame (in string name)
            raises (NoOntologyLoaded);

    /*************************************************************************
     *  Method: isConcept
     *  Description: is there a concept in the ontology with the given name
     *  Parameters: 
     *    in name: a string
     *  Returns: boolean
     *  Exceptions: NoOntologyLoaded if the ontology has not been loaded into memory
     *         
     ************************************************************************/
     
       boolean isConcept (in string name)
            raises (NoOntologyLoaded);

    /*************************************************************************
     *  Method: isInstance
     *  Description: is there an instance in the ontology with the given name
     *  Parameters: 
     *    in name: a string
     *  Returns: boolean
     *  Exceptions: NoOntologyLoaded if the ontology has not been loaded into memory
     *         
     ************************************************************************/
     
       boolean isInstance  (in string name)
            raises (NoOntologyLoaded);

    /*************************************************************************
     *  Method: isObject
     *  Description: is there an onto_object in the ontology with the given name
     *  Parameters: 
     *    in name: a string
     *  Returns: boolean
     *  Exceptions: NoOntologyLoaded if the ontology has not been loaded into memory
     *         
     ************************************************************************/
     
       boolean isObject  (in string name)
            raises (NoOntologyLoaded);

    /*************************************************************************
     *  Method: isEvent
     *  Description: is there an event in the ontology with the given name
     *  Parameters: 
     *    in name: a string
     *  Returns: boolean
     *  Exceptions: NoOntologyLoaded if the ontology has not been loaded into memory
     *         
     ************************************************************************/
     
       boolean isEvent  (in string name)
            raises (NoOntologyLoaded);

    /*************************************************************************
     *  Method: isProperty
     *  Description: is there a property in the ontology with the given name
     *  Parameters: 
     *    in name: a string
     *  Returns: boolean
     *  Exceptions: NoOntologyLoaded if the ontology has not been loaded into memory
     *         
     ************************************************************************/
     
       boolean isProperty  (in string name)
            raises (NoOntologyLoaded);

    /*************************************************************************
     *  Method: isRelation
     *  Description: is there a relation in the ontology with the given name
     *  Parameters: 
     *    in name: astring
     *  Returns: boolean
     *  Exceptions: NoOntologyLoaded if the ontology has not been loaded into memory
     *         
     ************************************************************************/
     
       boolean isRelation  (in string name)
            raises (NoOntologyLoaded);

    /*************************************************************************
     *  Method: isAttribute
     *  Description: is there an onto_attribute in the ontology with the given name
     *  Parameters: 
     *    in name: a string
     *  Returns: boolean
     *  Exceptions:  NoOntologyLoaded if the ontology has not been loaded into memory
     *         
     ************************************************************************/
     
       boolean isAttribute  (in string name)
            raises (NoOntologyLoaded);

    /*************************************************************************
     *  Method: isLiteral
     *  Description: is the given string a literal symbol in the ontology (i.e., a symbol that is not the     
     *               name of any frame but is a valid filler of certain (literal) onto_attributes, e.g., "red" for the 
     *   color attribute)
     *  Parameters: 
     *    in name: a string
     *  Returns: boolean
     *  Exceptions: NoOntologyLoaded if the ontology has not been loaded into memory
     *         
     ************************************************************************/
     
       boolean isLiteral  (in string name)
            raises (NoOntologyLoaded);

    /*************************************************************************
     *  Method: isNumerical
     *  Description: is the given string a number or a numerical range (e.g., 20, (> 10), (<> 0 1))
     *     That can be used as the filler of certain (scalar) onto_attributes
     *  Parameters: 
     *    in name: a string
     *  Returns: boolean
     *  Exceptions: NoOntologyLoaded if the ontology has not been loaded into memory
     *         
     ************************************************************************/
     
       boolean isNumerical  (in string name)
            raises (NoOntologyLoaded);

 };

  /**************************************************************************
   *                       class frame
   * Super-classes : None
   * Sub-classes : concept and instance
   * Methods : As listed below
   * Comments : 
   * any concept or instance in the ontology; the ontology is just a set of all the frames in it
   * each frame has a name, a time stamp of its creation or last modification, an English description
   * called its definition, taxonomic slots (IS-A or INSTANCE-OF, SUBCLASSES, INSTANCES),
   * and, if the frame is an onto_object or event, a number of other slots which are all its properties
   * (relations or onto_attributes), or if  the frame is a relation then DOMAIN, RANGE, and 
   * INVERSE slots, or if the frame is an onto_attribute, then DOMAIN and RANGE slots.
   *************************************************************************/  

interface frame {

 /* the frame as no parent. Note that the root concept ALL has no parent. */
 exception NoParent{};


 /* the frame has no definition. */
 exception NoDefinition{};

 /* the frame has no time stamp */
 exception NoTimeStamp{};

    /*************************************************************************
     *  Method: getName
     *  Description: get the name of the frame
     *  Parameters: none
     * Returns: a string
     *  Exceptions: none
     *         
     ************************************************************************/

 string getName ();

    /*************************************************************************
     *  Method: getSlots
     *  Description: get all the slots in a frame
     *  Parameters: none
     *  Returns: slots: a sequence of slot
     *  Exceptions: NoSuchSlot if the frame has no slots
     *         
     ************************************************************************/
     
   slots getSlots ()
        raises (NoSuchSlot);

    /*************************************************************************
     *  Method: getInheritedSlots
     *  Description: get all the local and inherited slots for the frame
     *  Parameters: none
     *  Returns: slots: a sequence of slot
     *  Exceptions: NoSuchSlot if there is no slot, local or inherited, in the frame
     *                NoParent if the frame has no parent to compute inheritance from
     ************************************************************************/
     
   slots getInheritedSlots ()
      raises (NoParent, NoSuchSlot);

    /*************************************************************************
     *  Method: getSlot
     *  Description: get the slot in the frame with the given name
     *  Parameters: 
     *    in slot_name: a string
     *  Returns: a slot
     *  Exceptions: NoSuchSlot if the frame does not have a slot with the given name
     *         
     ************************************************************************/
     
  slot getSlot (in string slot_name)
     raises (NoSuchSlot);

    /*************************************************************************
     *  Method: getInheritedSlot
     *  Description: get the slot in the frame (or inherited from its ancestors) with the given name
     *  Parameters: 
     *    in slot_name: a string
     *  Returns: a slot
     *  Exceptions: NoSuchSlot if there is no slot in the frame, local or inherited, with the given name
     *                NoParent if the frame has no parent to compute the inheritance
     ************************************************************************/
     
 slot getInheritedSlot (in string slot_name)
    raises (NoSuchSlot, NoParent);

    /*************************************************************************
     *  Method: getFacets
     *  Description: get all the facets in the given slot
     *  Parameters: 
     *    in a_slot: a slot
     *  Returns: facets: a sequence of facet
     *  Exceptions: NoSuchFacet if the slot has no facets
     *         
     ************************************************************************/
     
  facets getFacets (in slot a_slot)
       raises (NoSuchFacet);

    /*************************************************************************
     *  Method: getFacet
     *  Description: get the facet with the given name  in the given slot
     *  Parameters: 
     *    in a_slot: a slot
     *    In facet_name: a string
     *  Returns: a facet
     *  Exceptions: NoSuchFacet if the slot has no facet with the given name
     *         
     ************************************************************************/
     
  facet getFacet (in slot a_slot, in string facet_name)
       raises (NoSuchFacet);

    /*************************************************************************
     *  Method: getFillers
     *  Description: get all the fillers in the given facet
     *  Parameters: 
     *    in a_facet: a facet
     *  Returns: fillers: a sequence of string
     *  Exceptions: NoFiller if the given facet has no fillers
     *         
     ************************************************************************/
     
  fillers getFillers (in facet a_facet)
      raises (NoFiller);

    /*************************************************************************
     *  Method: getParents 
     *  Description: get all the immediate parents of the given frame (Note: does a getFrame on
     *                       Each filler of the IS-A or INSTANCE-OF slot to get the corresponding concept)
     *  Parameters: none
     *  Returns: concepts: a sequence of concept
     *  Exceptions: NoParent if the frame has no parents
     *                NoSuchConcept if any of the fillers is not a concept in the ontology
     ************************************************************************/
     
 concepts getParents ()
     raises (NoParent, NoSuchConcept);

    /*************************************************************************
     *  Method: getDefinition
     *  Description: get the definition of the given frame
     *  Parameters: none
     *  Returns: a string
     *  Exceptions: NoDefinition if the frame has no definition
     *         
     ************************************************************************/
     
  string getDefinition ()
    raises (NoDefinition);

    /*************************************************************************
     *  Method: getTimeStamp
     *  Description: get the time stamp of the given frame
     *  Parameters: none
     *  Returns: a string
     *  Exceptions: NoTimeStamp if the frame has no time stamp
     *         
     ************************************************************************/
     
  string getTimeStamp ()
    raises (NoTimeStamp);

    /*************************************************************************
     *  Method: isAncestor
     *  Description: is the concept with the name ancestor_name an ancestor of the frame
     *  Parameters: 
     *    in ancestor_name: a string
     *  Returns: boolean
     *  Exceptions: NoSuchConcept if there is no concept in the ontology with the name ancestor_name
     *         
     ************************************************************************/
     
  boolean isAncestor (in string ancestor_name)
       raises (NoSuchConcept);


 };

  /**************************************************************************
   *                       class concept
   * Super-classes : frame
   * Sub-classes : onto_object, event, property
   * Methods : As listed below
   * Comments : 
   *   any concept in the ontology. Note that onto_object and event are not defined in this API
   *   since they are the same as concept as far as this API is concerned.
   *************************************************************************/  

interface concept : frame {

 /* the concept has no child concept */
 exception NoChild{};

 /* the concept has no instance */
 exception NoInstance{};

    /*************************************************************************
     *  Method: getChildren
     *  Description: get all the children concepts of the given concept (Note: does a getFrame on 
     *                       Each filler of the SUBCLASSES slot to get the corresponding concept)
     *  Parameters: none
     *  Returns: concepts:  a sequence of concept
     *  Exceptions: NoChild if the concept has no child concept
     *                NoSuchConcept if any of the fillers is not a concept in the ontology
     ************************************************************************/
     
 concepts getChildren ()
      raises (NoChild, NoSuchConcept);

    /*************************************************************************
     *  Method: getInstances
     *  Description: get all the instances of the given concept (Note: does a getFrame on each filler
     *                       Of the INSTANCES slot to get the corresponding instance frame)
     *  Parameters: none
     *  Returns: instances: a sequence of instance
     *  Exceptions: NoInstance if the given concept has no instance
     *                 NoSuchInstance if any of the fillers is not an instance in the ontology
     ************************************************************************/
     
 instances getInstances ()
     raises (NoInstance, NoSuchInstance);

 };

  /**************************************************************************
   *                       class instance
   * Super-classes : frame
   * Sub-classes : none
   * Methods : none
   * Comments : 
   *   any instance of a concept in the ontology
   *************************************************************************/  

interface instance : frame {

 };

  /**************************************************************************
   *                       class property
   * Super-classes : concept
   * Sub-classes : relation, onto_attribute
   * Methods : As listed below
   * Comments : 
   *   any concept that is property in the ontology. Properties become slots in concepts
   *   that are onto_objects or events.
   *************************************************************************/  

interface property : concept {

    /*************************************************************************
     *  Method: getDomain
     *  Description: get the sequence of fillers that constitute the domain of the given property
     *  Parameters: none
     *  Returns: fillers: a sequence of string
     *  Exceptions: NoSuchSlot if the property does not have a DOMAIN slot and if the DOMAIN slot
     *                       Cannot be inherited from the ancestors of the property
     *                NoSuchFacet if the DOMAIN slot of the property does not have a VALUE facet
     *                NoFiller if the VALUE facet of the DOMAIN slot of the property has no fillers
     *                NoParent if the property has no parents to inherit the DOMAIN slot
     ************************************************************************/
     
 fillers getDomain ()
     raises (NoSuchSlot, NoSuchFacet, NoFiller, NoParent);


      /*************************************************************************
     *  Method: getRange
     *  Description: get the sequence of fillers that constitute the range of the given property
     *  Parameters: none
     *  Returns: fillers: a sequence of string
     *  Exceptions: NoSuchSlot if the property does not have a RANGE slot and if the RANGE slot
     *                       Cannot be inherited from the ancestors of the property
     *                NoSuchFacet if the RANGE slot of the property does not have a VALUE facet
     *                NoFiller if the VALUE facet of the RANGE slot of the property has no fillers
     *                NoParent if the property has no parents to inherit the RANGE slot
     ************************************************************************/
     
  fillers getRange ()
     raises (NoSuchSlot, NoSuchFacet, NoFiller, NoParent);
 
};

  /**************************************************************************
   *                       class relation
   * Super-classes : property
   * Sub-classes : None
   * Methods : As listed below
   * Comments : 
   *    Any relation in the ontology.
   *************************************************************************/  

interface relation : property {

    /*************************************************************************
     *  Method: getInverseRelation
     *  Description: get the name of the inverse relation for the given relation (note that INVERSE slots 
     *                        Are not inherited)
     *  Parameters: none
     *  Returns: a string
     *  Exceptions: NoSuchSlot if the given relation does not have an INVERSE slot
     *                NoSuchFacet if the INVERSE slot in the given relation does not have a VALUE facet
     *                NoFiller if the VALUE facet of the INVERSE slot in the relation does not have a filler
     ************************************************************************/
     
 string getInverseRelation ()
     raises (NoSuchSlot, NoSuchFacet, NoFiller);

 };

  /**************************************************************************
   *                       class onto_attribute
   * Super-classes : property
   * Sub-classes : None
   * Methods : none
   * Comments : 
   *   any onto_attribute in the ontology.
   *************************************************************************/  

interface onto_attribute : property {
 
 };

  /**************************************************************************
   *                       class slot
   * Super-classes : None
   * Sub-classes : None
   * Methods : As listed below
   * Comments : 
   *   any slot in any frame in the ontology.
   *************************************************************************/  

interface slot {

    /*************************************************************************
     *  Method: getFacets
     *  Description: get all the facets in the given slot
     *  Parameters: none
     *  Returns: facets: a sequence of facet
     *  Exceptions: NoSuchFacet if the given slot has no facet
     *         
     ************************************************************************/
     
 facets getFacets ()
     raises (NoSuchFacet);

    /*************************************************************************
     *  Method: getFacet
     *  Description: get the facet with the given name  in the given slot
     *  Parameters: 
     *      In facet_name: a string
     *  Returns: a facet
     *  Exceptions: NoSuchFacet if the given slot does not have a facet with the given name
     *         
     ************************************************************************/
     
 facet getFacet (in string facet_name)
     raises (NoSuchFacet);

 };

  /**************************************************************************
   *                       class facet
   * Super-classes : None
   * Sub-classes : None
   * Methods : As listed below
   * Comments : 
   *   any facet in any slot in the ontology.
   *************************************************************************/  

interface facet {

    /*************************************************************************
     *  Method: getFillers
     *  Description: get all the fillers in the given facet
     *  Parameters: none
     *  Returns: fillers: a sequence of string
     *  Exceptions: NoFiller if the facet has no filler
     *         
     ************************************************************************/
     
 fillers getFillers ()
    raises (NoFiller);

 };

};

/* </PRE> *******************************************************************/