1   /*
2    * Taxonomy.java
3    *
4    * Copyright (c) 2002-2004, The University of Sheffield.
5    *
6    * This file is part of GATE (see http://gate.ac.uk/), and is free
7    * software, licenced under the GNU Library General Public License,
8    * Version 2, June1991.
9    *
10   * A copy of this licence is included in the distribution in the file
11   * licence.html, and is also available at http://gate.ac.uk/gate/licence.html.
12   *
13   * borislav popov 02/2002
14   *
15   *
16   *  $Id: Taxonomy.java,v 1.1 2004/07/23 17:48:08 kalina Exp $
17   */
18  
19  package gate.creole.ontology;
20  
21  import java.net.URL;
22  import java.util.*;
23  
24  import gate.LanguageResource;
25  import gate.creole.ResourceInstantiationException;
26  
27  /**Defines the interface of an ontology*/
28  public interface Taxonomy extends LanguageResource{
29  
30    /** Gets taxonomy by URL. The taxonomy will be searched first among the LRs and
31     *  afterwards loaded by the URL if not found
32     *  @param someUrl the url of the taxonomy
33     *  @return the retrieved or loaded taxonomy
34     *  @throws ResourceInstantiationException if something gets wrong with the loading*/
35    public Taxonomy getOntology(URL someUrl) throws ResourceInstantiationException;
36  
37    /**
38     * Gets the label.
39     * @return the label of the ontology
40     */
41    public String getLabel();
42  
43    /**
44     * Sets the label of the ontology.
45     * @param theLabel the label to be set
46     */
47    public void setLabel(String theLabel);
48  
49    /** Gets the url of this ontology
50     * @return the url of this ontology */
51    public URL getURL();
52  
53    /**Set the url of this ontology
54     * @param aUrl the url to be set   */
55    public void setURL(URL aUrl);
56  
57    /**Loads this ontology. According to different storages - different implementations
58     * are expected.
59     * Should take care of the modifiedAfterLoading member */
60    public void load() throws ResourceInstantiationException ;
61  
62    /**Stores this ontology. According to different storages - different implementations
63     * are expected.
64     * Should take care of the modifiedAfterLoading member */
65    public void store() throws ResourceInstantiationException;
66  
67    /**Sets the URI of the ontology
68     * @param theURI  the URI to be set */
69    public void setSourceURI(String theURI);
70  
71    /**Gets the source URI.
72     * @return the URI of this ontology*/
73    public String getSourceURI();
74  
75    /**Sets version to this ontology.
76     * @param theVersion the version to be set   */
77    public void setVersion(String theVersion);
78  
79    /**Gets the version of this ontology.
80     * @return  the version of this ontology*/
81    public String getVersion();
82  
83    /**Gets the id of this ontology.
84     * @return the id of this ontology  */
85    public String getId();
86  
87    /**Sets the id of this ontology.
88     * @param theId the id to be set */
89    public void setId(String theId);
90  
91    /**Gets the comment of this ontology.
92     * @return the comment of this ontology  */
93    public String getComment();
94  
95    /**Sets the comment of this ontology.
96     * @param theComment the comment to be set  */
97    public void setComment(String theComment);
98  
99    /**Creates a new OClass and returns it.
100    * @param aName the name of this class
101    * @param aComment the comment of this class
102    * @return the newly created class  */
103   public TClass createClass(String aName, String aComment);
104 
105   /**Removes a class from this ontology.
106    * @param theClass the class to be removed */
107   public void removeClass(TClass theClass);
108 
109   /**Adds a class to the ontology.
110    * @param theClass the class to be added */
111   public void addClass(TClass theClass);
112 
113   /**Retrieves a class by its name.
114    * @param theName the name of the class
115    * @return the class matching the name or null if no matches.
116    */
117   public TClass getClassByName(String theName);
118 
119   /**Checks if the ontology contains a class with the given name.
120    * @param theName name of a class
121    * @return true if the ontology contains a class with the name specified  */
122   public boolean containsClassByName(String theName);
123 
124   /**Retrieves all classes as a set.
125    * @return set of all the classes in this ontology  */
126   public Set getClasses();
127 
128   /**Retireves an iterator over the classes, ordered according to the comparator.
129    * @param comp a comparator defining the order of iterating the classes
130    * @return an iterator over the classes
131    */
132   public Iterator getClasses(Comparator comp);
133 
134   /**Gets the top classes.
135    * @return set of the top classes of this ontology */
136   public Set getTopClasses();
137 
138   /** Gets the taxonomic distance between 2 classes.
139     * @param class1 the first class
140     * @param class2 the second class
141     * @return the taxonomic distance between the 2 classes
142     */
143   public int getTaxonomicDistance(TClass class1,TClass class2);
144 
145   /** Check for subclass relation with transitive closure
146    * @param cls1 the first class
147    * @param cls2 the second class
148    */
149   public boolean isSubClassOf(String cls1, String cls2)
150       throws gate.creole.ontology.NoSuchClosureTypeException;
151 
152   /** Check for subclass relation with direct closure
153    * @param cls1 the first class
154    * @param cls2 the second class
155   */
156   public boolean isDirectSubClassOf(String cls1, String cls2)
157       throws gate.creole.ontology.NoSuchClosureTypeException;
158 
159   /**
160    * Checks the equality of two ontologies.
161    * @param o the other ontology
162    * @return true if the ontologies are considered equal, otherwise - false.
163    */
164   public boolean equals(Object o);
165 
166   /**Sets the modified flag.
167    * @param isModified sets this param as a value of
168    * the modified property of the ontology */
169   public void setModified(boolean isModified);
170 
171   /**Checks the modified flag.
172    * @return whether the ontology has been modified after the loading*/
173   public boolean isModified();
174 
175 }//interface Taxonomy