IRDBDriver


1   /*
2    *  (c) Copyright 2003, 2004, 2005 Hewlett-Packard Development Company, LP
3    *  All rights reserved.
4    *  [see end of file]
5    */
6   
7   package com.hp.hpl.jena.db.impl;
8   
9   //=======================================================================
10  
11  // Imports
12  
13  import java.util.List  ;
14  
15  import com.hp.hpl.jena.db.IDBConnection;
16  import com.hp.hpl.jena.db.RDFRDBException;
17  import com.hp.hpl.jena.graph.Graph;
18  import com.hp.hpl.jena.graph.Node;
19  
20  
21  /**
22  * Generic database interface used for implementing RDF Stores.
23  * Different database table layouts and different SQL dialects should all
24  * be supportable via this generic interface. 
25  * 
26  * In earlier versions of Jena the Driver was exposed to some applications -
27  * that is no longer the case, and no application should need to use these
28  * functions directly.
29  * 
30  * Based in part on the Jena 1.0 implementation by der.
31  * 
32  * @author csayers
33  * @version $Revision: 1.21 $
34  */
35  
36  public interface IRDBDriver {
37      
38      /**
39       * Set the database connection
40       */
41      public void setConnection( IDBConnection dbcon );
42      
43      /**
44       * Return the connection
45       */
46      public IDBConnection getConnection();
47      
48      /**
49       * Return the specialized graph containing system properties.
50       * Formats the database and constucts a new one if doInit is true.
51       * @param doInit if true, format the database if needed.
52       * 
53       * @return SpecializedGraph holding properties of this database
54       * @since Jena 2.0
55       */
56      public SpecializedGraph getSystemSpecializedGraph(boolean doInit);
57      
58      /**
59       * Construct and return a list of specialized graphs.
60       * @param graphName TODO
61       * @param requestedProperties TODO
62       * @return List of SpecializedGraphs to store a Graph
63       * 
64       * @since Jena 2.0
65       */
66      public List   createSpecializedGraphs(String   graphName, Graph requestedProperties);
67      
68      /**
69       * Reconstruct and return a list of specialized graphs.
70       * @param graphProperties A set of customization properties for the  graph.
71       * @return List of SpecializedGraphs to store a Graph
72       * 
73       * @since Jena 2.0
74       */
75      public List   recreateSpecializedGraphs(DBPropGraph graphProperties);
76      
77      /**
78       * Remove the specialized graph, erasing all trace of a Graph.
79       * @param graphProperties The properties for the graph to be removed.
80       * 
81       * @since Jena 2.0
82       */
83      public void removeSpecializedGraphs(DBPropGraph graphProperties, List   specializedGraphs);
84      
85      /**
86       * Test if the database has previously been formatted (there's no other
87       * way to easily tell, since getSpecializedGraph will always return
88       * something).
89       * 
90       * @return boolean true if database is correctly formatted, false on any error.
91       */
92      public boolean isDBFormatOK();
93      
94      /**
95       * Method setDatabaseProperties.
96       * 
97       * Sets the current properties for the database.
98       * 
99       * @param databaseProperties is a Graph containing a full set of database properties
100      */
101     void setDatabaseProperties(Graph databaseProperties);
102         
103     /**
104      * Obtain a default set of model properties.
105      * 
106      * Return the default properties for a new model stored in this database
107      * @return DBPropGraph containg the default properties for a new model
108      */
109     DBPropGraph getDefaultModelProperties();
110     
111     /**
112      * Return a string identifying underlying database type.
113      *
114      */
115     String   getDatabaseType();
116     
117 
118     /**
119      * Remove all RDF information from a database.
120      * 
121      * There should be no need for an application to call this function
122      * directly - instead use DBConnection.cleanDB().
123      * 
124      */
125 
126     public void cleanDB();
127 
128     /**
129      * Close the databse connection.
130      * @throws RDFDBException if there is an access problem
131      */
132 
133     public void close() throws RDFRDBException;
134 
135     /**
136      * Initialise a database ready to store RDF tables.
137      * Currently the table format depends on the RDBSpec type. In future it
138      * may become an explicit part of operations like this.
139      * @throws RDFDBException if the is a problem opening the connection or an internal SQL error.
140      * @deprecated Since Jena 2.0 this call is no longer needed - formatting 
141      * happens automatically as a side effect of creating Models - there should
142      * be no need for an application to interact directly with the driver.
143      */
144 
145     public void formatDB() throws RDFRDBException;
146     
147     /**
148      * Acquire the mutex lock in the database. This
149      * is used to implement critical sections to prevent
150      * concurrent Jena threads from inteferring with
151      * each other when creating/destroying models,
152      * formatting databases, etc.
153      * 
154      * There should be no need for an application to
155      * call this method.
156      */
157     
158     public void lockDB() throws RDFRDBException;
159     
160     /**
161      * Release the mutex lock in the database.
162      */
163     
164     public void unlockDB() throws RDFRDBException;
165     
166     /**
167      * Return true if the database is locked, else false.
168      */
169     
170     public boolean tryLockDB() throws RDFRDBException;
171     
172     /**
173      * Create a table for storing asserted or reified statements.
174      * 
175      * @param graphId the graph which the table is created.
176      * @param isReif true if table stores reified statements.
177      * @return the name of the new table 
178      * 
179      */
180     
181     /**
182      *  Return true if the mutex is held.
183      */
184     
185     public boolean DBisLocked() throws RDFRDBException;
186 
187     abstract String   createTable( int graphId, boolean isReif);
188        
189     /**
190      * Delete a table. 
191      * For internal use only.
192      * 
193      */
194     abstract void deleteTable( String   tableName );
195        
196 
197     /**
198      * Aborts the open transaction, then turns autocommit on.
199      */
200     public void abort() throws  RDFRDBException;
201         
202     /**
203      * Turns autocommit off, then opens a new transaction.   *
204      */
205     public void begin() throws  RDFRDBException;
206         
207     /**
208      * Commits the open transaction, then turns autocommit on.
209      */
210     public void commit() throws  RDFRDBException;
211 
212     /**
213      * Returns true if the underlying database supports transactions.
214      */
215     public boolean transactionsSupported();    
216 
217     /**
218      * Returns true if the database layout supports multiple RDF models in the same database.
219      * @return boolean true if the database supports multiple models
220      * @deprecated Since Jena 2.0 all databases support multiple models.
221      */
222 
223     public boolean supportsMultipleModels();
224 
225     /**
226      * Returns true if the database layout supports implicit reification.
227      * of statements (i.e. statements can be treated as resources).
228      * @return boolean true if the database supports jena 1.0 reification.
229      * @deprecated Since Jena 2.0 the reification API has changed.  The
230      * new API is supported in all models, but the old Jena 1 API is no
231      * longer supported.  This call will return false to indicate
232      * to old code that the old style of jena reification is not supported.
233      */
234 
235     public boolean supportsJenaReification();
236     
237     /**
238      * Allocate an identifier for a new graph.
239      * @param graphName The name of a new graph.
240      * @return the identifier of the new graph.
241      */
242      public int graphIdAlloc ( String   graphName );
243     
244     /**
245      * Deallocate an identifier for a new graph.
246      * @param graphId The graph identifier.
247      */
248      public void graphIdDealloc ( int graphId );
249 
250     /**
251     * Return an auto-generated identifier for a table row.
252     * @param tableName The name of the table for the insert.
253     * @return the auto-generated identifier..
254     */
255      public int getInsertID ( String   tableName );
256 
257     
258     /**
259     * Convert a node to a string to be stored in a statement table.
260     * @param Node The node to convert to a string. Must be a concrete node.
261     * @param addIfLong If the node is a long object and is not in the database, add it.
262     * @return the string.
263     */
264 
265     public String   nodeToRDBString ( Node node, boolean addIfLong );
266     
267     /**
268     * Convert an RDB string to the node that it encodes. Return null if failure.
269     * @param RDBstring The string to convert to a node.
270     * @return The node.
271     */
272     
273     public Node RDBStringToNode ( String   RDBString );
274     
275     /**
276      * Generate an SQL string for a reified statement to match on the stmt URI. 
277      * @return qualifier string
278      */ 
279     
280     public String   genSQLReifQualStmt ();
281     
282     /**
283      * Generate an SQL string for a reified statement to match on any subject,
284      * predicate or object column.
285      * @param objIsStmt If true, the object value is rdf:Statement so also match
286      * on the hasType column. 
287      * @return qualifier string
288      */ 
289 
290     public String   genSQLReifQualAnyObj( boolean objIsStmt);
291     
292     /**
293      * Generate an SQL string for a reified statement to match on a property column.
294      * @param reifProp The property column to match, one of S,P,O,T for subject,
295      * predicate, object or type, respectively.
296      * @param hasObj If true, the object value is known so do equality match. Otherwise,
297      * just check for non-null value.
298      * @return qualifier string
299      */ 
300     
301     public String   genSQLReifQualObj ( char reifProp, boolean hasObj );
302     
303     /**
304      * Generate an SQL string to match a table column value to a constant.
305      * If the literal does not occur in the database, a match condition
306      * is generated that will always return false.
307      * There's a known bug in this method. the literal is converted to
308      * a string BEFORE the query is run. consequently, there's a race
309      * condition. if the (long) literal is not in the database
310      * when the query is compiled but is added prior to running the
311      * query, then the query will (incorrectly) return no results.
312      * for now, we'll ignore this case and document it as a bug.
313      * @param alias The table alias for this match.
314      * @param col The column to match, one of S,P,O,N,T for subject,
315      * predicate, object, statement or type, respectively.
316      * @param lit The literal value to match.
317      * @return SQL string.
318      */ 
319     
320     public String   genSQLQualConst ( int alias, char col, Node lit );
321     
322     /**
323      * Similar to genSQLQualConst except that it generates SQL strings
324      * for the reification statement table.
325      *
326      */
327     public String   genSQLReifQualConst ( int alias, char pred, Node lit );
328 
329     
330     /**
331      * Generate an SQL string to match a table column value to a parameter.
332      * @param alias The table alias for this match.
333      * @param col The column to match, one of S,P,O,N,T for subject,
334      * predicate, object, statement or type, respectively.
335      * @return SQL string.
336      */ 
337 
338     public String   genSQLQualParam( int alias, char col );
339     
340     /**
341      * Generate an SQL string to match a graph id. 
342      * @param alias The table alias for this match.
343      * @param graphId The identifer of the graph to match.
344      * @return SQL string.
345      */ 
346 
347     public String   genSQLQualGraphId( int alias, int graphId );
348     
349     public String   genSQLStringMatch( int alias, char col,
350         String   fun, String   stringToMatch );
351     
352     public String   genSQLStringMatchLHS( boolean ignCase, String   var );
353     public String   genSQLStringMatchLHS_IC( String   var );
354     
355     public String   genSQLStringMatchOp( boolean ignCase, String   fun );
356 
357     public String   stringMatchAllChar();
358     public String   stringMatchEscapeChar();
359 
360     public String   genSQLStringMatchRHS( boolean ignCase, boolean pfxMatch,
361                                     String   strToMatch );
362     public String   genSQLStringMatchRHS_IC( String   strToMatch );
363 
364     public String   genSQLStringMatchOp( String   fun );
365 
366     public String   genSQLStringMatchOp_IC( String   fun );
367     
368     public boolean stringMatchNeedsEscape ( String   strToMatch );
369 
370     public String   addEscape ( String   strToMatch );
371     
372     public String   genSQLStringMatchEscape();
373     
374     public String   genSQLLikeKW();
375 
376     public String   genSQLEscapeKW();
377 
378     
379     
380     
381     /**
382      * Generate an SQL string to joing two table columns.
383      * @param lhsAlias The left side table alias for the join.
384      * @param lhsCol The left side column to join, one of
385      * S,P,O,N,T.
386      * @param rhsAlias The right side table alias to join.
387      * @param rhsCol The right side column to join.
388      * @return SQL string.
389      */ 
390 
391     public String   genSQLJoin( int lhsAlias, char lhsCol,
392         int rhsAlias, char rhsCol );
393         
394     /**
395      * Generate an SQL string for a result list of a select stmt.
396      * @param binding Array of Var containing the result list bindings.
397      * @return SQL string (not prefixed by "Select").
398      */ 
399     
400     public String   genSQLResList( int resIndex[], VarDesc[] binding );
401 
402     /**
403      * Generate an SQL string for a from list of a select stmt.
404      * @param aliasCnt The number of table aliases in the from list.
405      * @param table The name of the table to be queried.
406      * @return SQL string (not prefixed by "From").
407      */ 
408     
409     public String   genSQLFromList( int aliasCnt, String   table );
410 
411         
412     /**
413      * Generate an SQL Select statement given the result list,
414      * the from list and the where clause;
415      * @param res The result list as a string.
416      * @param from The from list as a string.
417      * @param where The where qualifier as a string.
418      * @return SQL statement.
419      */ 
420 
421     public String   genSQLSelectStmt( String   res, String   from, String   where );
422     
423     public class GenSQLAnd {
424          private boolean init;
425          GenSQLAnd () { init = false; }
426          String   gen( String   qual ) {
427             if ( qual == "" ) return "";
428             if ( init == false ) {
429                 init = true;
430                 return qual;
431             } else
432                 return " AND " + qual;
433          }       
434     }
435     
436     /**
437      * Get the value of LongObjectLength
438      * @return int
439      */
440     public int getLongObjectLength();
441 
442     /**
443     * Set the value of LongObjectLength. Throws an exception if
444     * the database has been initialized.
445     * @param int
446     */
447     public void setLongObjectLength(int len);
448 
449     /**
450      * Get the value of IndexKeyLength
451      * @return int
452      */
453     public int getIndexKeyLength();
454 
455     /**
456     * Set the value of IndexKeyLength. Throws an exception if
457     * the database has been initialized.
458     * @param int
459     */
460     public void setIndexKeyLength(int len);
461 
462     /**
463     * Get the value of IsTransactionDb
464     * @return bool
465     */
466     public boolean getIsTransactionDb();
467 
468     /**
469     * Set the value of IsTransactionDb. Throws an exception if
470     * the database has been initialized.
471     * @param bool
472     */
473     public void setIsTransactionDb(boolean bool);
474 
475     /**
476     * Get the value of DoCompressURI
477     * @return bool
478     */
479     public boolean getDoCompressURI();
480 
481     /**
482     * Set the value of DoCompressURI. Throws an exception if
483     * the database has been initialized.
484     * @param bool
485     */
486     public void setDoCompressURI(boolean bool);
487 
488     /**
489         * Get the value of CompressURILength
490         * @return int
491         */
492     public int getCompressURILength();
493 
494     /**
495     * Set the value of CompressURILength. Throws an exception if
496     * the database has been initialized.
497     * @param int
498     */
499     public void setCompressURILength(int len);
500 
501     /**
502     * Get the value of DoDuplicateCheck
503     * @return bool
504     */
505     public boolean getDoDuplicateCheck();
506 
507     /**
508     * Set the value of DoDuplicateCheck.
509     * @param bool
510     */
511     public void setDoDuplicateCheck(boolean bool);
512 
513     /**
514     * Get the value of TableNamePrefix
515     * @return String
516     */
517     public String   getTableNamePrefix();
518 
519     /**
520     * Set the value of TableNamePrefix.
521     * @param String
522     */
523     public void setTableNamePrefix(String   prefix);
524     
525     /**
526     * Get the value of StoreWithModel
527     * @return String
528     */
529     public String   getStoreWithModel();
530 
531     /**
532     * Set the value of StoreWithModel.
533     * @param String
534     */
535     public void setStoreWithModel( String   modelName );
536     
537     /**
538     * Get the value of CompressCacheSize
539     * @return int
540     */
541     public int getCompressCacheSize();
542 
543     /**
544     * Set the value of CompressCacheSize.
545     * @param int
546     */
547     public void setCompressCacheSize(int count);
548     
549     /**
550      * Return the number of system tables.
551      */
552 
553     public int getSystemTableCount();
554     
555     /**
556      * Return the name of a system table
557      */
558 
559     public String   getSystemTableName ( int i );
560 
561 }
562 
563 /*
564  *  (c) Copyright 2003, 2004, 2005 Hewlett-Packard Development Company, LP
565  *  All rights reserved.
566  *
567  * Redistribution and use in source and binary forms, with or without
568  * modification, are permitted provided that the following conditions
569  * are met:
570  * 1. Redistributions of source code must retain the above copyright
571  *    notice, this list of conditions and the following disclaimer.
572  * 2. Redistributions in binary form must reproduce the above copyright
573  *    notice, this list of conditions and the following disclaimer in the
574  *    documentation and/or other materials provided with the distribution.
575  * 3. The name of the author may not be used to endorse or promote products
576  *    derived from this software without specific prior written permission.
577 
578  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
579  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
580  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
581  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
582  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
583  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
584  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
585  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
586  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
587  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
588  */
589     
590  
591
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags