SpecializedGraph


1   /*
2    *  (c) Copyright 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
3    *  All rights reserved.
4    *
5    */
6   
7   
8   package com.hp.hpl.jena.db.impl;
9   
10  import java.util.List  ;
11  
12  import com.hp.hpl.jena.graph.*;
13  import com.hp.hpl.jena.util.iterator.ExtendedIterator;
14  
15  /**
16   * Interface for a specialized graph.
17   * 
18   * Each specialized graph is optimized for a particular type of statement.
19   * 
20   * An implemenation of GraphRDB will contain a list of specialized graphs
21   * and will attempt to perform each operation on each specialized graph
22   * in the list until one indicates the operation is complete.
23   * 
24   * The list of specialized graphs is immutable.  This aids optimization.
25   * For example, if a specialied graph is asked to perform an operatin 
26   * on a triple, and it knows that it would have added it if asked, then 
27   * it can advise the calling GraphRDB that the operaton is complete even 
28   * though it doesn't know anything about other specialized graphs later
29   * in the list.
30   *
31   * @author csayers
32   * @version $Revision: 1.7 $
33   * 
34   */
35  public interface SpecializedGraph {
36          
37      /** 
38       * Attempt to add a triple to the specialized graph
39       * 
40       * Note that when calling add, the call will either fail (complete=false)
41       * indicating the graph can not store the triple, or succeed (complete=true)
42       * indicating that a subsequent call to contains(triple) will return true
43       * and that the add operation is complete.
44       * Adding the same triple twice is not an error and should still cause
45       * complete to be true.
46       * 
47       * If the triple can't be stored for any reason other than incompatability
48       * (for example, a lack of disk space) then the implemenation should throw
49       * a runtime exception.
50       * 
51       * @param t is the triple to be added
52       * @param complete is true if a subsequent call to contains(triple) will return true.
53       */
54      public void add(Triple t, CompletionFlag complete);
55      
56      /** 
57       * Attempt to add a list of triples to the specialized graph
58       * 
59       * As each triple is successfully added it is removed from the List.
60       * If complete is true then the entire List was added and the List will 
61       * be empty upon return.  if complete is false, then at least one triple 
62       * remains in the List.
63       * 
64       * If a triple can't be stored for any reason other than incompatability
65       * (for example, a lack of disk space) then the implemenation should throw
66       * a runtime exception.
67       * 
68       * @param triples List of triples to be added.  This is modified by the call.
69       * @param complete is true if a subsequent call to contains(triple) will return true for all triples originally in the List.
70       */
71      public void add(List   triples, CompletionFlag complete);
72      
73      /** 
74       * Attempt to add all the triples from a graph to the specialized graph
75       * 
76       * Caution - this call changes the graph passed in, deleting from 
77       * it each triple that is successfully added.
78       * 
79       * Note that when calling add, if complete is true, then the entire
80       * graph was added successfully and the graph g will be empty upon
81       * return.  If complete is false, then some triples in the graph could 
82       * not be added.  Those triples remain in g after the call returns.
83       * 
84       * If the triple can't be stored for any reason other than incompatability
85       * (for example, a lack of disk space) then the implemenation should throw
86       * a runtime exception.
87       * 
88       * @param g is a graph containing triples to be added
89       * @param complete is true if a subsequent call to contains(triple) will return true for any triple in g.
90       */
91      public void add(Graph g, CompletionFlag complete);
92  
93      /** 
94       * Attempt to delete a triple from the specialized graph
95       * 
96       * @param t is the triple to be deleted
97       * @param complete is true if either (i) the triple was in the graph and was deleted, or 
98       * (ii) the triple was not in the graph the graph can guarantee that a call to add(Triple)
99       * would have succeeded, had it been made for that same triple.
100      */
101     public void delete(Triple t, CompletionFlag complete);
102     
103     /** 
104      * Attempt to delete a list of triples from the specialized graph
105      * 
106      * As each triple is successfully deleted it is removed from the List.
107      * If complete is true then the entire List was deleted and the List will 
108      * be empty upon return.  If complete is false, then at least one triple 
109      * remains in the List.
110      * 
111      * @param triples List of triples to be deleted.  This is modified by the call.
112      * @param complete is true iff delete(Triple, complete) would have set 
113      * complete==true for all triples in the List.
114      */
115     public void delete(List   triples, CompletionFlag complete);
116 
117     /** 
118      * Compute the number of unique triples added to the Specialized Graph.
119      * 
120      * @return int count.
121      */
122     public int tripleCount();
123     
124     /**
125      * Tests if a triple is contained in the specialized graph
126      * @param t is the triple to be tested
127      * @param complete is true if the graph can guarantee that no other specialized graph 
128      * could hold any matching triples.
129      * @return boolean result to indicte if the triple was contained
130      */
131     public boolean contains(Triple t, CompletionFlag complete);
132             
133     /**
134      * Finds matching triples contained in the specialized graph
135      * @param m
136      * @param complete is true if the graph can guarantee that no other specialized graph 
137      * could hold any matching triples.
138      * @return ExtendedIterator which iterates over any matching triples
139      */
140     public ExtendedIterator find(TripleMatch m, CompletionFlag complete);
141     
142     /**
143         Finds matching triples contained in the specialized graph
144         @param s the subject of the match
145         @param p the predicate of the match
146         @param o the object of the match
147         @param complete is true if the graph can guarantee that no other specialized graph 
148         could hold any matching triples.
149         @return ExtendedIterator which iterates over any matching triples
150     */
151     public ExtendedIterator find( Node s, Node p, Node o, CompletionFlag complete );
152     
153     /**
154      * Clear the specialized graph
155      * 
156      * This removes any triples stored in the graph.
157      */
158     public void clear();
159     
160     /**
161      * Close specialized graph.
162      * 
163      * This frees any resources used by the graph.
164      * It is an error to perform any operation on a graph after closing it.
165      */
166     public void close();
167     
168     public class CompletionFlag {
169         boolean done;
170         
171         public CompletionFlag() { done = false; }
172         
173         public boolean isDone() { return done; }
174         
175         public void setDone() { done = true; }      
176     }
177     
178     /**
179      * Database identifier of the GraphRDB that contains this specialized graph.
180      * @return IDBID database identifier of the GraphRDB that contains this specialized graph.
181      */
182     public int getGraphId();
183     
184     /**
185      * Return the PSet that implements this specialized graph.
186      * @return IPSet the PSet that implements this specialized graph.
187      */
188     public IPSet getPSet();
189         
190     /**
191      * Return the DBPropLSet for this specialized graph.
192      * @return DBPropLSet for this specialized graph.
193      */
194     public DBPropLSet getDBPropLSet();
195  
196     /** 
197      * Determine if the graph contains any triples for the pattern.
198      * @param pattern the pattern.
199      * @return char indicator, 'n', 's', 'a' for no, some, all triples for pattern.
200      */
201 
202 
203     public char subsumes ( Triple pattern, int reificationBehavior );
204  
205     static final char noTriplesForPattern = 'n'; // graph contains no triples for pattern
206     static final char someTriplesForPattern = 's'; // graph contains some triples for pattern
207     static final char allTriplesForPattern = 'a'; // graph contains all triples for pattern
208 
209     
210 
211 }
212 
213 /*
214     (c) Copyright 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
215     All rights reserved.
216 
217     Redistribution and use in source and binary forms, with or without
218     modification, are permitted provided that the following conditions
219     are met:
220 
221     1. Redistributions of source code must retain the above copyright
222        notice, this list of conditions and the following disclaimer.
223 
224     2. Redistributions in binary form must reproduce the above copyright
225        notice, this list of conditions and the following disclaimer in the
226        documentation and/or other materials provided with the distribution.
227 
228     3. The name of the author may not be used to endorse or promote products
229        derived from this software without specific prior written permission.
230 
231     THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
232     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
233     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
234     IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
235     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
236     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
237     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
238     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
239     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
240     THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
241 */
242
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags