001: /*
002: * (c) Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
003: * All rights reserved.
004: *
005: */
006:
007: package com.hp.hpl.jena.db.impl;
008:
009: import java.util.List;
010:
011: import com.hp.hpl.jena.graph.*;
012: import com.hp.hpl.jena.util.iterator.ExtendedIterator;
013:
014: /**
015: * Interface for a specialized graph.
016: *
017: * Each specialized graph is optimized for a particular type of statement.
018: *
019: * An implemenation of GraphRDB will contain a list of specialized graphs
020: * and will attempt to perform each operation on each specialized graph
021: * in the list until one indicates the operation is complete.
022: *
023: * The list of specialized graphs is immutable. This aids optimization.
024: * For example, if a specialied graph is asked to perform an operatin
025: * on a triple, and it knows that it would have added it if asked, then
026: * it can advise the calling GraphRDB that the operaton is complete even
027: * though it doesn't know anything about other specialized graphs later
028: * in the list.
029: *
030: * @author csayers
031: * @version $Revision: 1.10 $
032: *
033: */
034: public interface SpecializedGraph {
035:
036: /**
037: * Attempt to add a triple to the specialized graph
038: *
039: * Note that when calling add, the call will either fail (complete=false)
040: * indicating the graph can not store the triple, or succeed (complete=true)
041: * indicating that a subsequent call to contains(triple) will return true
042: * and that the add operation is complete.
043: * Adding the same triple twice is not an error and should still cause
044: * complete to be true.
045: *
046: * If the triple can't be stored for any reason other than incompatability
047: * (for example, a lack of disk space) then the implemenation should throw
048: * a runtime exception.
049: *
050: * @param t is the triple to be added
051: * @param complete is true if a subsequent call to contains(triple) will return true.
052: */
053: public void add(Triple t, CompletionFlag complete);
054:
055: /**
056: * Attempt to add a list of triples to the specialized graph
057: *
058: * As each triple is successfully added it is removed from the List.
059: * If complete is true then the entire List was added and the List will
060: * be empty upon return. if complete is false, then at least one triple
061: * remains in the List.
062: *
063: * If a triple can't be stored for any reason other than incompatability
064: * (for example, a lack of disk space) then the implemenation should throw
065: * a runtime exception.
066: *
067: * @param triples List of triples to be added. This is modified by the call.
068: * @param complete is true if a subsequent call to contains(triple) will return true for all triples originally in the List.
069: */
070: public void add(List triples, CompletionFlag complete);
071:
072: /**
073: * Attempt to add all the triples from a graph to the specialized graph
074: *
075: * Caution - this call changes the graph passed in, deleting from
076: * it each triple that is successfully added.
077: *
078: * Note that when calling add, if complete is true, then the entire
079: * graph was added successfully and the graph g will be empty upon
080: * return. If complete is false, then some triples in the graph could
081: * not be added. Those triples remain in g after the call returns.
082: *
083: * If the triple can't be stored for any reason other than incompatability
084: * (for example, a lack of disk space) then the implemenation should throw
085: * a runtime exception.
086: *
087: * @param g is a graph containing triples to be added
088: * @param complete is true if a subsequent call to contains(triple) will return true for any triple in g.
089: */
090: public void add(Graph g, CompletionFlag complete);
091:
092: /**
093: * Attempt to delete a triple from the specialized graph
094: *
095: * @param t is the triple to be deleted
096: * @param complete is true if either (i) the triple was in the graph and was deleted, or
097: * (ii) the triple was not in the graph the graph can guarantee that a call to add(Triple)
098: * would have succeeded, had it been made for that same triple.
099: */
100: public void delete(Triple t, CompletionFlag complete);
101:
102: /**
103: * Attempt to delete a list of triples from the specialized graph
104: *
105: * As each triple is successfully deleted it is removed from the List.
106: * If complete is true then the entire List was deleted and the List will
107: * be empty upon return. If complete is false, then at least one triple
108: * remains in the List.
109: *
110: * @param triples List of triples to be deleted. This is modified by the call.
111: * @param complete is true iff delete(Triple, complete) would have set
112: * complete==true for all triples in the List.
113: */
114: public void delete(List triples, CompletionFlag complete);
115:
116: /**
117: * Compute the number of unique triples added to the Specialized Graph.
118: *
119: * @return int count.
120: */
121: public int tripleCount();
122:
123: /**
124: * Tests if a triple is contained in the specialized graph
125: * @param t is the triple to be tested
126: * @param complete is true if the graph can guarantee that no other specialized graph
127: * could hold any matching triples.
128: * @return boolean result to indicte if the triple was contained
129: */
130: public boolean contains(Triple t, CompletionFlag complete);
131:
132: /**
133: * Finds matching triples contained in the specialized graph
134: * @param m
135: * @param complete is true if the graph can guarantee that no other specialized graph
136: * could hold any matching triples.
137: * @return ExtendedIterator which iterates over any matching triples
138: */
139: public ExtendedIterator find(TripleMatch m, CompletionFlag complete);
140:
141: /**
142: Finds matching triples contained in the specialized graph
143: @param s the subject of the match
144: @param p the predicate of the match
145: @param o the object of the match
146: @param complete is true if the graph can guarantee that no other specialized graph
147: could hold any matching triples.
148: @return ExtendedIterator which iterates over any matching triples
149: */
150: public ExtendedIterator find(Node s, Node p, Node o,
151: 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() {
172: done = false;
173: }
174:
175: public boolean isDone() {
176: return done;
177: }
178:
179: public void setDone() {
180: done = true;
181: }
182: }
183:
184: /**
185: * Database identifier of the GraphRDB that contains this specialized graph.
186: * @return IDBID database identifier of the GraphRDB that contains this specialized graph.
187: */
188: public int getGraphId();
189:
190: /**
191: * Return the PSet that implements this specialized graph.
192: * @return IPSet the PSet that implements this specialized graph.
193: */
194: public IPSet getPSet();
195:
196: /**
197: * Return the DBPropLSet for this specialized graph.
198: * @return DBPropLSet for this specialized graph.
199: */
200: public DBPropLSet getDBPropLSet();
201:
202: /**
203: * Determine if the graph contains any triples for the pattern.
204: * @param pattern the pattern.
205: * @return char indicator, 'n', 's', 'a' for no, some, all triples for pattern.
206: */
207:
208: public char subsumes(Triple pattern, int reificationBehavior);
209:
210: static final char noTriplesForPattern = 'n'; // graph contains no triples for pattern
211: static final char someTriplesForPattern = 's'; // graph contains some triples for pattern
212: static final char allTriplesForPattern = 'a'; // graph contains all triples for pattern
213:
214: }
215:
216: /*
217: (c) Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
218: All rights reserved.
219:
220: Redistribution and use in source and binary forms, with or without
221: modification, are permitted provided that the following conditions
222: are met:
223:
224: 1. Redistributions of source code must retain the above copyright
225: notice, this list of conditions and the following disclaimer.
226:
227: 2. Redistributions in binary form must reproduce the above copyright
228: notice, this list of conditions and the following disclaimer in the
229: documentation and/or other materials provided with the distribution.
230:
231: 3. The name of the author may not be used to endorse or promote products
232: derived from this software without specific prior written permission.
233:
234: THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
235: IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
236: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
237: IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
238: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
239: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
240: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
241: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
242: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
243: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
244: */
|