001: /*
002: * (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
003: * All rights reserved.
004: * [see end of file]
005: */
006:
007: package com.hp.hpl.jena.db.impl;
008:
009: //=======================================================================
010:
011: // Imports
012:
013: import java.util.List;
014:
015: import com.hp.hpl.jena.db.IDBConnection;
016: import com.hp.hpl.jena.db.RDFRDBException;
017: import com.hp.hpl.jena.graph.Graph;
018: import com.hp.hpl.jena.graph.Node;
019:
020: /**
021: * Generic database interface used for implementing RDF Stores.
022: * Different database table layouts and different SQL dialects should all
023: * be supportable via this generic interface.
024: *
025: * In earlier versions of Jena the Driver was exposed to some applications -
026: * that is no longer the case, and no application should need to use these
027: * functions directly.
028: *
029: * Based in part on the Jena 1.0 implementation by der.
030: *
031: * @author csayers
032: * @version $Revision: 1.25 $
033: */
034:
035: public interface IRDBDriver {
036:
037: /**
038: * Set the database connection
039: */
040: public void setConnection(IDBConnection dbcon);
041:
042: /**
043: * Return the connection
044: */
045: public IDBConnection getConnection();
046:
047: /**
048: * Return the specialized graph containing system properties.
049: * Formats the database and constucts a new one if doInit is true.
050: * @param doInit if true, format the database if needed.
051: *
052: * @return SpecializedGraph holding properties of this database
053: * @since Jena 2.0
054: */
055: public SpecializedGraph getSystemSpecializedGraph(boolean doInit);
056:
057: /**
058: * Construct and return a list of specialized graphs.
059: * @param graphName TODO
060: * @param requestedProperties TODO
061: * @return List of SpecializedGraphs to store a Graph
062: *
063: * @since Jena 2.0
064: */
065: public List createSpecializedGraphs(String graphName,
066: Graph requestedProperties);
067:
068: /**
069: * Reconstruct and return a list of specialized graphs.
070: * @param graphProperties A set of customization properties for the graph.
071: * @return List of SpecializedGraphs to store a Graph
072: *
073: * @since Jena 2.0
074: */
075: public List recreateSpecializedGraphs(DBPropGraph graphProperties);
076:
077: /**
078: * Remove the specialized graph, erasing all trace of a Graph.
079: * @param graphProperties The properties for the graph to be removed.
080: *
081: * @since Jena 2.0
082: */
083: public void removeSpecializedGraphs(DBPropGraph graphProperties,
084: List specializedGraphs);
085:
086: /**
087: * Test if the database has previously been formatted (there's no other
088: * way to easily tell, since getSpecializedGraph will always return
089: * something).
090: *
091: * @return boolean true if database is correctly formatted, false on any error.
092: */
093: public boolean isDBFormatOK();
094:
095: /**
096: * Method setDatabaseProperties.
097: *
098: * Sets the current properties for the database.
099: *
100: * @param databaseProperties is a Graph containing a full set of database properties
101: */
102: void setDatabaseProperties(Graph databaseProperties);
103:
104: /**
105: * Obtain a default set of model properties.
106: *
107: * Return the default properties for a new model stored in this database
108: * @return DBPropGraph containg the default properties for a new model
109: */
110: DBPropGraph getDefaultModelProperties();
111:
112: /**
113: * Return a string identifying underlying database type.
114: *
115: */
116: String getDatabaseType();
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: * Aborts the open transaction, then turns autocommit on.
198: */
199: public void abort() throws RDFRDBException;
200:
201: /**
202: * Turns autocommit off, then opens a new transaction. *
203: */
204: public void begin() throws RDFRDBException;
205:
206: /**
207: * Commits the open transaction, then turns autocommit on.
208: */
209: public void commit() throws RDFRDBException;
210:
211: /**
212: * Returns true if the underlying database supports transactions.
213: */
214: public boolean transactionsSupported();
215:
216: /**
217: * Returns true if the database layout supports multiple RDF models in the same database.
218: * @return boolean true if the database supports multiple models
219: * @deprecated Since Jena 2.0 all databases support multiple models.
220: */
221:
222: public boolean supportsMultipleModels();
223:
224: /**
225: * Returns true if the database layout supports implicit reification.
226: * of statements (i.e. statements can be treated as resources).
227: * @return boolean true if the database supports jena 1.0 reification.
228: * @deprecated Since Jena 2.0 the reification API has changed. The
229: * new API is supported in all models, but the old Jena 1 API is no
230: * longer supported. This call will return false to indicate
231: * to old code that the old style of jena reification is not supported.
232: */
233:
234: public boolean supportsJenaReification();
235:
236: /**
237: * Allocate an identifier for a new graph.
238: * @param graphName The name of a new graph.
239: * @return the identifier of the new graph.
240: */
241: public int graphIdAlloc(String graphName);
242:
243: /**
244: * Deallocate an identifier for a new graph.
245: * @param graphId The graph identifier.
246: */
247: public void graphIdDealloc(int graphId);
248:
249: /**
250: * Return an auto-generated identifier for a table row.
251: * @param tableName The name of the table for the insert.
252: * @return the auto-generated identifier..
253: */
254: public int getInsertID(String tableName);
255:
256: /**
257: * Convert a node to a string to be stored in a statement table.
258: * @param Node The node to convert to a string. Must be a concrete node.
259: * @param addIfLong If the node is a long object and is not in the database, add it.
260: * @return the string.
261: */
262:
263: public String nodeToRDBString(Node node, boolean addIfLong);
264:
265: /**
266: * Convert an RDB string to the node that it encodes. Return null if failure.
267: * @param RDBstring The string to convert to a node.
268: * @return The node.
269: */
270:
271: public Node RDBStringToNode(String RDBString);
272:
273: /**
274: * Generate an SQL string for a reified statement to match on the stmt URI.
275: * @return qualifier string
276: */
277:
278: public String genSQLReifQualStmt();
279:
280: /**
281: * Generate an SQL string for a reified statement to match on any subject,
282: * predicate or object column.
283: * @param objIsStmt If true, the object value is rdf:Statement so also match
284: * on the hasType column.
285: * @return qualifier string
286: */
287:
288: public String genSQLReifQualAnyObj(boolean objIsStmt);
289:
290: /**
291: * Generate an SQL string for a reified statement to match on a property column.
292: * @param reifProp The property column to match, one of S,P,O,T for subject,
293: * predicate, object or type, respectively.
294: * @param hasObj If true, the object value is known so do equality match. Otherwise,
295: * just check for non-null value.
296: * @return qualifier string
297: */
298:
299: public String genSQLReifQualObj(char reifProp, boolean hasObj);
300:
301: /**
302: * Generate an SQL string to match a table column value to a constant.
303: * If the literal does not occur in the database, a match condition
304: * is generated that will always return false.
305: * There's a known bug in this method. the literal is converted to
306: * a string BEFORE the query is run. consequently, there's a race
307: * condition. if the (long) literal is not in the database
308: * when the query is compiled but is added prior to running the
309: * query, then the query will (incorrectly) return no results.
310: * for now, we'll ignore this case and document it as a bug.
311: * @param alias The table alias for this match.
312: * @param col The column to match, one of S,P,O,N,T for subject,
313: * predicate, object, statement or type, respectively.
314: * @param lit The literal value to match.
315: * @return SQL string.
316: */
317:
318: public String genSQLQualConst(int alias, char col, Node lit);
319:
320: /**
321: * Similar to genSQLQualConst except that it generates SQL strings
322: * for the reification statement table.
323: *
324: */
325: public String genSQLReifQualConst(int alias, char pred, Node lit);
326:
327: /**
328: * Generate an SQL string to match a table column value to a parameter.
329: * @param alias The table alias for this match.
330: * @param col The column to match, one of S,P,O,N,T for subject,
331: * predicate, object, statement or type, respectively.
332: * @return SQL string.
333: */
334:
335: public String genSQLQualParam(int alias, char col);
336:
337: /**
338: * Generate an SQL string to match a graph id.
339: * @param alias The table alias for this match.
340: * @param graphId The identifer of the graph to match.
341: * @return SQL string.
342: */
343:
344: public String genSQLQualGraphId(int alias, int graphId);
345:
346: public String genSQLStringMatch(int alias, char col, String fun,
347: String stringToMatch);
348:
349: public String genSQLStringMatchLHS(boolean ignCase, String var);
350:
351: public String genSQLStringMatchLHS_IC(String var);
352:
353: public String genSQLStringMatchOp(boolean ignCase, String fun);
354:
355: public String stringMatchAllChar();
356:
357: public String stringMatchEscapeChar();
358:
359: public String genSQLStringMatchRHS(boolean ignCase,
360: boolean pfxMatch, String strToMatch);
361:
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: * Generate an SQL string to joing two table columns.
380: * @param lhsAlias The left side table alias for the join.
381: * @param lhsCol The left side column to join, one of
382: * S,P,O,N,T.
383: * @param rhsAlias The right side table alias to join.
384: * @param rhsCol The right side column to join.
385: * @return SQL string.
386: */
387:
388: public String genSQLJoin(int lhsAlias, char lhsCol, int rhsAlias,
389: char rhsCol);
390:
391: /**
392: * Generate an SQL string for a result list of a select stmt.
393: * @param binding Array of Var containing the result list bindings.
394: * @return SQL string (not prefixed by "Select").
395: */
396:
397: public String genSQLResList(int resIndex[], VarDesc[] binding);
398:
399: /**
400: * Generate an SQL string for a from list of a select stmt.
401: * @param aliasCnt The number of table aliases in the from list.
402: * @param table The name of the table to be queried.
403: * @return SQL string (not prefixed by "From").
404: */
405:
406: public String genSQLFromList(int aliasCnt, String table);
407:
408: /**
409: * Generate an SQL Select statement given the result list,
410: * the from list and the where clause;
411: * @param res The result list as a string.
412: * @param from The from list as a string.
413: * @param where The where qualifier as a string.
414: * @return SQL statement.
415: */
416:
417: public String genSQLSelectStmt(String res, String from, String where);
418:
419: public class GenSQLAnd {
420: private boolean init;
421:
422: GenSQLAnd() {
423: init = false;
424: }
425:
426: String gen(String qual) {
427: if (qual == "")
428: return "";
429: if (init == false) {
430: init = true;
431: return qual;
432: } else
433: return " AND " + qual;
434: }
435: }
436:
437: /**
438: * Get the maximum possible value of LongObjectLength
439: * @return int
440: */
441: public int getLongObjectLengthMax();
442:
443: /**
444: * Get the value of LongObjectLength
445: * @return int
446: */
447: public int getLongObjectLength();
448:
449: /**
450: * Set the value of LongObjectLength. Throws an exception if
451: * the database has been initialized.
452: * @param int
453: */
454: public void setLongObjectLength(int len);
455:
456: /**
457: * Get the maximum possible value of IndexKeyLength
458: * @return int
459: */
460: public int getIndexKeyLengthMax();
461:
462: /**
463: * Get the value of IndexKeyLength
464: * @return int
465: */
466: public int getIndexKeyLength();
467:
468: /**
469: * Set the value of IndexKeyLength. Throws an exception if
470: * the database has been initialized.
471: * @param int
472: */
473: public void setIndexKeyLength(int len);
474:
475: /**
476: * Get the value of IsTransactionDb
477: * @return bool
478: */
479: public boolean getIsTransactionDb();
480:
481: /**
482: * Set the value of IsTransactionDb. Throws an exception if
483: * the database has been initialized.
484: * @param bool
485: */
486: public void setIsTransactionDb(boolean bool);
487:
488: /**
489: * Get the value of DoCompressURI
490: * @return bool
491: */
492: public boolean getDoCompressURI();
493:
494: /**
495: * Set the value of DoCompressURI. Throws an exception if
496: * the database has been initialized.
497: * @param bool
498: */
499: public void setDoCompressURI(boolean bool);
500:
501: /**
502: * Get the value of CompressURILength
503: * @return int
504: */
505: public int getCompressURILength();
506:
507: /**
508: * Set the value of CompressURILength. Throws an exception if
509: * the database has been initialized.
510: * @param int
511: */
512: public void setCompressURILength(int len);
513:
514: /**
515: * Get the value of DoDuplicateCheck
516: * @return bool
517: */
518: public boolean getDoDuplicateCheck();
519:
520: /**
521: * Set the value of DoDuplicateCheck.
522: * @param bool
523: */
524: public void setDoDuplicateCheck(boolean bool);
525:
526: /**
527: * Get the value of TableNamePrefix
528: * @return String
529: */
530: public String getTableNamePrefix();
531:
532: /**
533: * Set the value of TableNamePrefix.
534: * @param String
535: */
536: public void setTableNamePrefix(String prefix);
537:
538: /**
539: * Get the value of StoreWithModel
540: * @return String
541: */
542: public String getStoreWithModel();
543:
544: /**
545: * Set the value of StoreWithModel.
546: * @param String
547: */
548: public void setStoreWithModel(String modelName);
549:
550: /**
551: * Get the value of CompressCacheSize
552: * @return int
553: */
554: public int getCompressCacheSize();
555:
556: /**
557: * Set the value of CompressCacheSize.
558: * @param int
559: */
560: public void setCompressCacheSize(int count);
561:
562: /**
563: * Return the number of system tables.
564: */
565:
566: public int getSystemTableCount();
567:
568: /**
569: * Return the name of a system table
570: */
571:
572: public String getSystemTableName(int i);
573:
574: }
575:
576: /*
577: * (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
578: * All rights reserved.
579: *
580: * Redistribution and use in source and binary forms, with or without
581: * modification, are permitted provided that the following conditions
582: * are met:
583: * 1. Redistributions of source code must retain the above copyright
584: * notice, this list of conditions and the following disclaimer.
585: * 2. Redistributions in binary form must reproduce the above copyright
586: * notice, this list of conditions and the following disclaimer in the
587: * documentation and/or other materials provided with the distribution.
588: * 3. The name of the author may not be used to endorse or promote products
589: * derived from this software without specific prior written permission.
590:
591: * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
592: * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
593: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
594: * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
595: * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
596: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
597: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
598: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
599: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
600: * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
601: */
|