OntologyTripleStore.java
001 /*
002  *  Copyright (c) 1995-2012, The University of Sheffield. See the file
003  *  COPYRIGHT.txt in the software or at http://gate.ac.uk/gate/COPYRIGHT.txt
004  *
005  *  This file is part of GATE (see http://gate.ac.uk/), and is free
006  *  software, licenced under the GNU Library General Public License,
007  *  Version 2, June 1991 (in the distribution as file licence.html,
008  *  and also available at http://gate.ac.uk/gate/licence.html).
009  *
010  *  Johann Petrak
011  *
012  *  $Id: $
013  */
014 package gate.creole.ontology;
015 
016 /**
017  * An OntologyTripleStore object can be used to directly manipulate the
018  * triples that represent an ontology, if the ontology implementation 
019  * supports this. The OntologyTripleStore object can be accessed using
020  * the method {@link Ontology#getOntologyTripleStore}.
021  
022  @author Johann Petrak
023  */
024 public interface OntologyTripleStore {
025   /** 
026    * Add a triple with a non-literal triple object to the triple store. 
027    *
028    @param subject 
029    @param predicate
030    @param object 
031    */
032   public void addTriple(ONodeID subject, OURI predicate, ONodeID object);
033   
034   /** 
035    * Add a triple with a literal triple object to the triple store. 
036    *
037    @param subject
038    @param predicate
039    @param object 
040    */
041   public void addTriple(ONodeID subject, OURI predicate, Literal object);
042   
043   /** 
044    * Remove a statement(triple) with a non-literal triple object 
045    * from the ontology triple
046    * store. The null value can be used for any of the subject, predicate,
047    * or object parameters as a wildcard indicator: in that case, triples
048    * with any value for that parameter will be removed.
049    
050    * NOTE: if a null value is passed for the object parameter, triples with
051    * any value for the object, no matter if it is a literal or non-literal
052    * (including blank nodes) will be removed!!
053    
054    @param subject
055    @param predicate
056    @param object 
057    */
058   public void removeTriple(ONodeID subject, OURI predicate, ONodeID object);
059   /** 
060    * Remove a statement(triple) with a literal triple object from the ontology triple
061    * store. The null value can be used for any of the subject, predicate,
062    * or object parameters as a wildcard indicator: in that case, triples
063    * with any value for that parameter will be removed.
064    
065    * NOTE: if a null value is passed for the object parameter, triples with
066    * any value for the object, no matter if it is a literal or non-literal
067    * (including blank nodes) will be removed!!
068    
069    @param subject
070    @param predicate
071    @param object 
072    */
073   public void removeTriple(ONodeID subject, OURI predicate, Literal object);
074 
075   /** 
076    * Add a listener for ontology triple store additions and removals. 
077    * The listener will get the parameters of the original addition or 
078    * deletion request, not any indication of which concrete triples were 
079    * actually added or removed!
080    <p>
081    * NOTE: the listener will not get all events for modifications made 
082    * through methods other than the direct triple addition and removal
083    * methods of the OntologyTripleStore object.
084    
085    @param listener  OntologyTripleStoreListener object
086    */
087   public void addOntologyTripleStoreListener(
088     OntologyTripleStoreListener listener);
089   
090   /**
091    * Check if a given triple with an URI object is part of the ontology.
092    
093    @param subject
094    @param predicate
095    @param object
096    @return true if the triple with the given subject, predicate and object
097    * is either asserted or inferred in the ontology.
098    */
099   public boolean hasTriple(ONodeID subject, OURI predicate, ONodeID object);
100   
101   /**
102    * Check if a given triple with a literal object is part of the ontology.
103    
104    @param subject
105    @param predicate
106    @param object
107    @return true if the triple with the given subject, predicate and object
108    * is either asserted or inferred in the ontology.
109    */
110   public boolean hasTriple(ONodeID subject, OURI predicate, 
111     gate.creole.ontology.Literal object);
112   
113   
114   /** 
115    * Remove an existing listener for ontology triple store additions and removals. 
116    
117    @param listener  OntologyTripleStoreListener object
118    */
119   public void removeOntologyTripleStoreListener(
120     OntologyTripleStoreListener listener);
121 }