001: /*
002: (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
003: [See end of file]
004: */
005:
006: package com.hp.hpl.jena.db;
007:
008: import java.sql.*;
009:
010: import com.hp.hpl.jena.db.impl.*;
011: import com.hp.hpl.jena.rdf.model.Model;
012: import com.hp.hpl.jena.util.iterator.ExtendedIterator;
013:
014: /**
015: * Encapsulate the specification of a jdbc connection, mostly used to
016: * simplify the calling pattern for ModelRDB factory methods.
017: *
018: * @author csayers (based on earlier code by der)
019: * @version $Revision: 1.8 $ on $Date: 2008/01/02 12:09:17 $
020: */
021:
022: public interface IDBConnection {
023:
024: /**
025: * Return the jdbc connection or null if we no longer have access to a connection.
026: */
027: public Connection getConnection() throws SQLException;
028:
029: /**
030: * Close the jdbc connection
031: */
032: public void close() throws SQLException;
033:
034: /**
035: * Clear all RDF information from the database.
036: *
037: * This wipes all the information stored by Jena from the database.
038: * Obviously should be used with care.
039: */
040: public void cleanDB() throws SQLException;
041:
042: /**
043: * Return true if the database seems to be formated for RDF storage.
044: * This is <em>not</em> an integrity check this is simply a flag
045: * recording that a base level table exists.
046: * Any access errors are treated as the database not being formated.
047: */
048: public boolean isFormatOK() throws RDFRDBException;
049:
050: /**
051: * Sets database-specific properties.
052: *
053: * <p>
054: * These properties may only be set before the first Model has been
055: * stored in the database. After that point, the database structure
056: * is frozen.</p>
057: *
058: * <p>
059: * Use these properties to optionally customize the database - this
060: * won't change the results you see when using the graph interface,
061: * but it may alter the speed with which you get them or the space
062: * required by the database.</p>
063: *
064: * <p>
065: * The properties must form a complete and consistent set.
066: * The easist way to get a complete and consistent set is to call
067: * getDatabaseProperties, modify the returned model, and then use
068: * that as an argument in the call to setDatabaseProperties.</p>
069: *
070: * <p>
071: * Note that some implementations may choose to delay actually peforming
072: * the formatting operation until at least one Graph is constructed in
073: * the database. Consequently, a successful return from this call
074: * does not necessarily guarantee that the database properties
075: * were set correctly.</p>
076: *
077: * @param propertyModel is a Model describing the database parameters
078: * @since Jena 2.0
079: *
080: */
081: public void setDatabaseProperties(Model propertyModel)
082: throws RDFRDBException;
083:
084: /**
085: * Returns a Jena Model containing database properties.
086: * <p>
087: * These describe the optimization/layout for the database.</p>
088: *
089: * <p>
090: * If the database has not been formatted, then a default
091: * set of properties is returned. Otherwise the actual properties
092: * are returned.</p>
093: *
094: * <p>
095: * The returned Model is a copy, modifying it will have no
096: * effect on the database. (Use setDatabaseProperties to
097: * make changes).</p>
098: *
099: * @since Jena 2.0
100: */
101: public Model getDatabaseProperties() throws RDFRDBException;
102:
103: /** Set the database type manually.
104: * <p>
105: * This is not for public use (it is preferable to
106: * specify it in the constructor) - included here to handle
107: * older code, which didn't use the new constructor.</p>
108: *
109: * @since Jena 2.0
110: */
111:
112: public void setDatabaseType(String databaseType);
113:
114: /**
115: * Retrieve a default set of model customization properties.
116: *
117: * The returned default set of properties is suitable for use in a call to
118: * ModelRDB.create(..., modelProperties);
119: *
120: * @return Model containing default properties
121: */
122:
123: public Model getDefaultModelProperties() throws RDFRDBException;
124:
125: /** Get the database type.
126: * @return String database type, or null if unset
127: *
128: * @since Jena 2.0
129: */
130: public String getDatabaseType();
131:
132: /*
133: * Returns a property value for the database at the end of the
134: * connection. This is used to retrieve appropriate formating and
135: * driver information from a standard RDF_LAYOUT_INFO table.
136: * For a database that has not been formatted all calls will
137: * return null.
138: * Any access errors are treated as the database not being formated.
139: * Throws an exception if the database is not even openable.
140: *
141: * This is no longer supported in Jena2 - use the property model instead.
142: * (The database implementation in Jena 2 is quite different and there
143: * are no analogous properties for most of the Jena 1 properties.)
144: */
145: //public String getProperty(String propname) throws SQLException;
146: /*
147: * Returns a set of property values for the database at the end of the
148: * connection. This is used to retrieve appropriate formating and
149: * driver information from a standard RDF_LAYOUT_INFO table.
150: * For a database that has not been formatted all calls will
151: * return null.
152: * Any access errors are treated as the database not being formated.
153: *
154: * This is no longer supported in Jena2 - use the property model instead.
155: * (The database implementation in Jena 2 is quite different and there
156: * are no analogous properties for most of the Jena 1 properties.)
157: */
158: //public Properties getProperties() throws SQLException;
159: /*
160: * Add a new property value to both RDF_LAYOUT_INFO table.
161: *
162: * This is no longer supported in Jena2 - use the property model instead.
163: * (The database implementation in Jena 2 is quite different and there
164: * are no analogous properties for most of the Jena 1 properties.)
165: */
166: //public void addProperty(String propname, String value) throws SQLException;
167: /** Retrieve a list of all models in the database
168: *
169: * @return Iterator over String names for graphs.
170: * @throws RDFDBException
171: * @since Jena 2.0
172: */
173: public ExtendedIterator getAllModelNames() throws RDFRDBException;
174:
175: /**
176: * Test if a given model is contained in the database.
177: *
178: * @param name the name of a model which may be in the database
179: * @return Boolean true if the model is contained in the database
180: * @throws RDFDBException
181: * @since Jena 2.0
182: */
183: public boolean containsModel(String name) throws RDFRDBException;
184:
185: /**
186: * Test if a default model is contained in the database.
187: *
188: * A default model is a model for which no specific name was specified.
189: * (One that was created by calling ModelRDB.createModel without specifying
190: * a name).
191: *
192: * @return Boolean true if the model is contained in the database
193: * @throws RDFDBException
194: * @since Jena 2.0
195: */
196: public boolean containsDefaultModel() throws RDFRDBException;
197:
198: /** Get the database-specific driver
199: *
200: * For this to work, it needs to know the type of database being used.
201: * That may be specified in the constructor (preferred) or done later
202: * by using the setDatabaseType method (for backward compatability).
203: */
204:
205: public IRDBDriver getDriver() throws RDFRDBException;
206:
207: /**
208: * Set the IRDBDriver to use for this connection.
209: * Useful to enable external drivers to be registered outside of the
210: * standard driver package.
211: */
212: public void setDriver(IRDBDriver driver);
213:
214: /**
215: * Helper function to locate and instantiate the driver class corresponding
216: * to a given layout and database name
217: * Throws an RDFRDBexception if the driver can't be instantiated
218: * @deprecated As of Jena 2.0 this call should not be used. Instead specify the database type
219: * when constructing a DBConnection and then pass that connection to the GraphRDB. There is
220: * no longer any need for applications to interact with the IRDBDriver. To customize the
221: * database configuration/layout use the formatDB(propertyModel) call.
222: */
223: public IRDBDriver getDriver(String layout, String database)
224: throws RDFRDBException;
225:
226: }
227:
228: /*
229: * (c) Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
230: * All rights reserved.
231: *
232: * Redistribution and use in source and binary forms, with or without
233: * modification, are permitted provided that the following conditions
234: * are met:
235: * 1. Redistributions of source code must retain the above copyright
236: * notice, this list of conditions and the following disclaimer.
237: * 2. Redistributions in binary form must reproduce the above copyright
238: * notice, this list of conditions and the following disclaimer in the
239: * documentation and/or other materials provided with the distribution.
240: * 3. The name of the author may not be used to endorse or promote products
241: * derived from this software without specific prior written permission.
242:
243: * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
244: * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
245: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
246: * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
247: * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
248: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
249: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
250: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
251: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
252: * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
253: */
|