/**
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
 * License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is the Protege Server.
 *
 * The Initial Developer of the Original Code is The MITRE Corporation.
 */
module KRS
{
  
  //forward declarations
  interface KBKnowledgeBase;
  interface KBFrame;
  interface KBConcept;
  interface KBInstance;
  interface KBSlot;
  interface KBFacet;

  //new types
  typedef sequence<KBConcept> ListOfConcepts;
  typedef sequence<KBInstance> ListOfInstances;
  typedef sequence<KBSlot> ListOfSlots;
  typedef sequence<KBFacet> ListOfFacets;
  typedef sequence<KBKnowledgeBase> ListOfKnowledgeBases;
  typedef sequence<string> ListOfStrings;
  typedef sequence<any> ListOfAny;

  enum SlotValueType 
  { 
    SLOT_TYPE_ANY, 
    SLOT_TYPE_BOOLEAN,
    SLOT_TYPE_CONCEPT,
    SLOT_TYPE_FLOAT, 
    SLOT_TYPE_INSTANCE,
    SLOT_TYPE_INTEGER,
    SLOT_TYPE_STRING,
    SLOT_TYPE_SYMBOL
  };
  
  //exceptions
  exception FileNotFoundException{};
  exception FileExistsException{};
  exception IoException //lower-case "o" to avoid a Java name clash.
  { string message; };
  exception FrameNameExistsException{ string message; };
  exception FrameNotFoundException{ string message; };
  exception InvalidRegularExpressionException{ string message; };
  
  
  interface KBControl
  {
    KBKnowledgeBase loadKb(in string kbName) 
                          raises (FileNotFoundException, IoException);
    KBKnowledgeBase createKb(in string kbName)
                            raises (FileExistsException, IoException);
    ListOfKnowledgeBases getOpenKbs();
    void closeKb(in KBKnowledgeBase kb);
  };
  
  interface KBKnowledgeBase
  {
    void save() raises (IoException);
    void delete() raises (IoException);
    void clear();
    
    KBConcept createConcept(in string name) raises (FrameNameExistsException);
    ListOfConcepts getConcepts();
    ListOfConcepts findConcepts(in string regexp) raises (InvalidRegularExpressionException);
    KBConcept getRootConcept();
    
    //This slot will implicitly be an instance of :STANDARD-SLOT, and
    //unattached to any concept.
    KBSlot createSlot(in string name) raises (FrameNameExistsException);
    
    //convenience accessors
    KBFrame getFrame(in string name) raises (FrameNotFoundException);
    KBConcept getConcept(in string name) raises (FrameNotFoundException);
    KBInstance getInstance(in string name) raises (FrameNotFoundException);
    KBSlot getSlot(in string name) raises (FrameNotFoundException);
  };

  interface KBFrame
  {
    string getName();
    
    //delete frame from the KB altogether
    void delete();
    
    //get the KB this frame resides in.
    KBKnowledgeBase getKnowledgeBase();
  };

  interface KBInstance : KBFrame
  {
    KBConcept getDirectType();

    //slot stuff    
    ListOfSlots getSlots();
    KBSlot getSlot(in string name) raises (FrameNotFoundException);
    void addSlotValue(in KBSlot slot, in any value) raises (FrameNotFoundException);
    void setSlotValues(in KBSlot slot, in ListOfAny values) raises (FrameNotFoundException);
    void removeSlotValue(in KBSlot slot, in any value) raises (FrameNotFoundException);
    ListOfAny getSlotValues(in KBSlot slot) raises (FrameNotFoundException);
  };
  
  interface KBConcept : KBInstance
  {
    //class hierarchy stuff
    void addParents(in ListOfConcepts newParents);
    void reparent(in KBConcept newParent);
    boolean isAncestorOf(in KBConcept concept);
    ListOfConcepts getSuperconcepts();
    ListOfConcepts getSubconcepts();
    boolean isAbstract();
    
    //instance stuff
    ListOfInstances getAllInstances();
    ListOfInstances getDirectInstances();
    KBInstance createInstance(in string name) raises (FrameNameExistsException);
    KBInstance getInstance(in string name) raises (FrameNotFoundException);
    
    //more slot stuff
    KBSlot createSlot(in string name) raises (FrameNameExistsException);
    void removeSlot(in KBSlot slot) raises (FrameNotFoundException);   
    KBSlot getBrowserSlot() raises (FrameNotFoundException);
    void attachSlot(in KBSlot slot);
    void detachSlot(in KBSlot slot) raises (FrameNotFoundException);

    //facet stuff
    ListOfFacets getFacets(in KBSlot slot) raises (FrameNotFoundException);
    KBFacet getFacet(in KBSlot slot, in string name) raises (FrameNotFoundException);
    ListOfAny getFacetValues(in KBSlot slot, in KBFacet facet) raises (FrameNotFoundException);
    void setFacetValues(in KBSlot slot, in KBFacet facet, in ListOfAny values) raises (FrameNotFoundException);
  };
  
  interface KBSlot : KBInstance
  {
    //This affects the top-level slot.  I.e. unless overridden at a
    //particular concept, this will take effect for ALL concepts/
    //instances that have this slot.
    void setValueType(in SlotValueType type);
  };
  
  interface KBFacet : KBInstance
  {
    boolean isValidValue(in KBFrame frame, in KBSlot slot, in any value) raises (FrameNotFoundException);
  };
};