001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package org.apache.openjpa.jdbc.conf;
020:
021: import javax.sql.DataSource;
022:
023: import org.apache.openjpa.conf.OpenJPAConfiguration;
024: import org.apache.openjpa.jdbc.kernel.EagerFetchModes;
025: import org.apache.openjpa.jdbc.kernel.LRSSizes;
026: import org.apache.openjpa.jdbc.kernel.UpdateManager;
027: import org.apache.openjpa.jdbc.meta.MappingDefaults;
028: import org.apache.openjpa.jdbc.meta.MappingRepository;
029: import org.apache.openjpa.jdbc.schema.DriverDataSource;
030: import org.apache.openjpa.jdbc.schema.SchemaFactory;
031: import org.apache.openjpa.jdbc.sql.DBDictionary;
032: import org.apache.openjpa.jdbc.sql.SQLFactory;
033: import org.apache.openjpa.kernel.StoreContext;
034: import org.apache.openjpa.lib.jdbc.ConnectionDecorator;
035: import org.apache.openjpa.lib.jdbc.JDBCEvent;
036: import org.apache.openjpa.lib.jdbc.JDBCListener;
037: import org.apache.openjpa.meta.MetaDataFactory;
038:
039: /**
040: * Configuration that defines the properties necessary to configure
041: * runtime and connect to a JDBC DataSource.
042: *
043: * @author Marc Prud'hommeaux
044: */
045: public interface JDBCConfiguration extends OpenJPAConfiguration {
046:
047: /**
048: * Name of the logger for SQL execution messages:
049: * <code>openjpa.jdbc.SQL</code>.
050: */
051: public static final String LOG_SQL = "openjpa.jdbc.SQL";
052:
053: /**
054: * Name of the logger for JDBC-related messages:
055: * <code>openjpa.jdbc.JDBC</code>.
056: */
057: public static final String LOG_JDBC = "openjpa.jdbc.JDBC";
058:
059: /**
060: * Name of the logger for schema-related messages:
061: * <code>openjpa.jdbc.Schema</code>.
062: */
063: public static final String LOG_SCHEMA = "openjpa.jdbc.Schema";
064:
065: /**
066: * Default schema for unqualified tables.
067: */
068: public String getSchema();
069:
070: /**
071: * Default schema for unqualified tables.
072: */
073: public void setSchema(String schema);
074:
075: /**
076: * Comma-separated list of modifiable schemas for persistent instances.
077: */
078: public String getSchemas();
079:
080: /**
081: * Comma-separated list of modifiable schemas for persistent instances.
082: */
083: public void setSchemas(String schemas);
084:
085: /**
086: * Modificable schema components.
087: */
088: public String[] getSchemasList();
089:
090: /**
091: * Modifiable schema components.
092: */
093: public void setSchemas(String[] schemas);
094:
095: /**
096: * The transaction isolation level to use at the database level.
097: * Possible values are:
098: * <ul>
099: * <li><code>default</code>: The JDBC driver's default isolation level.</li>
100: * <li><code>none</code>: The standard JDBC
101: * {@link java.sql.Connection#TRANSACTION_NONE} level.</li>
102: * <li><code>read-committed</code>: The standard JDBC
103: * {@link java.sql.Connection#TRANSACTION_READ_COMMITTED} level.</li>
104: * <li><code>read-uncommitted</code>: The standard JDBC
105: * {@link java.sql.Connection#TRANSACTION_READ_UNCOMMITTED} level.</li>
106: * <li><code>repeatable-read</code>: The standard JDBC
107: * {@link java.sql.Connection#TRANSACTION_REPEATABLE_READ} level.</li>
108: * <li><code>serializable</code>: The standard JDBC
109: * {@link java.sql.Connection#TRANSACTION_SERIALIZABLE} level.</li>
110: * </ul>
111: */
112: public String getTransactionIsolation();
113:
114: /**
115: * The transaction isolation level to use at the database level.
116: * Possible values are:
117: * <ul>
118: * <li><code>default</code>: The JDBC driver's default isolation level.</li>
119: * <li><code>none</code>: The standard JDBC
120: * {@link java.sql.Connection#TRANSACTION_NONE} level.</li>
121: * <li><code>read-committed</code>: The standard JDBC
122: * {@link java.sql.Connection#TRANSACTION_READ_COMMITTED} level.</li>
123: * <li><code>read-uncommitted</code>: The standard JDBC
124: * {@link java.sql.Connection#TRANSACTION_READ_UNCOMMITTED} level.</li>
125: * <li><code>repeatable-read</code>: The standard JDBC
126: * {@link java.sql.Connection#TRANSACTION_REPEATABLE_READ} level.</li>
127: * <li><code>serializable</code>: The standard JDBC
128: * {@link java.sql.Connection#TRANSACTION_SERIALIZABLE} level.</li>
129: * </ul>
130: */
131: public void setTransactionIsolation(String level);
132:
133: /**
134: * Return the proper transaction isolation level constant from
135: * {@link java.sql.Connection}, or -1 for the default level.
136: */
137: public int getTransactionIsolationConstant();
138:
139: /**
140: * Set the proper transaction isolation level constant from
141: * {@link java.sql.Connection}, or -1 for the default level.
142: */
143: public void setTransactionIsolation(int level);
144:
145: /**
146: * The JDBC result set type. Defaults to <code>forward-only</code>.
147: * <ul>
148: * <li><code>forward-only</code>: The standard JDBC
149: * {@link java.sql.ResultSet#TYPE_FORWARD_ONLY} type.</li>
150: * <li><code>scroll-sensitive</code>: The standard JDBC
151: * {@link java.sql.ResultSet#TYPE_SCROLL_SENSITIVE} type.</li>
152: * <li><code>scroll-insensitive</code>: The standard JDBC
153: * {@link java.sql.ResultSet#TYPE_SCROLL_INSENSITIVE} type.</li>
154: * </ul>
155: */
156: public String getResultSetType();
157:
158: /**
159: * Return the result set constant for the result set type.
160: */
161: public int getResultSetTypeConstant();
162:
163: /**
164: * The JDBC result set type. Defaults to <code>forward-only</code>.
165: * <ul>
166: * <li><code>forward-only</code>: The standard JDBC
167: * {@link java.sql.ResultSet#TYPE_FORWARD_ONLY} type.</li>
168: * <li><code>scroll-sensitive</code>: The standard JDBC
169: * {@link java.sql.ResultSet#TYPE_SCROLL_SENSITIVE} type.</li>
170: * <li><code>scroll-insensitive</code>: The standard JDBC
171: * {@link java.sql.ResultSet#TYPE_SCROLL_INSENSITIVE} type.</li>
172: * </ul>
173: */
174: public void setResultSetType(String type);
175:
176: /**
177: * Set the result set constant type.
178: */
179: public void setResultSetType(int type);
180:
181: /**
182: * The JDBC fetch direction. Defaults to <code>forward</code>.
183: * <ul>
184: * <li><code>forward</code>: The standard JDBC
185: * {@link java.sql.ResultSet#FETCH_FORWARD} direction.</li>
186: * <li><code>reverse</code>: The standard JDBC
187: * {@link java.sql.ResultSet#FETCH_REVERSE} direction.</li>
188: * <li><code>unknown</code>: The standard JDBC
189: * {@link java.sql.ResultSet#FETCH_UNKNOWN} direction.</li>
190: * </ul>
191: */
192: public String getFetchDirection();
193:
194: /**
195: * Return the result set constant for the fetch direction.
196: */
197: public int getFetchDirectionConstant();
198:
199: /**
200: * The JDBC fetch direction. Defaults to <code>forward</code>.
201: * <ul>
202: * <li><code>forward</code>: The standard JDBC
203: * {@link java.sql.ResultSet#FETCH_FORWARD} direction.</li>
204: * <li><code>reverse</code>: The standard JDBC
205: * {@link java.sql.ResultSet#FETCH_REVERSE} direction.</li>
206: * <li><code>unknown</code>: The standard JDBC
207: * {@link java.sql.ResultSet#FETCH_UNKNOWN} direction.</li>
208: * </ul>
209: */
210: public void setFetchDirection(String direction);
211:
212: /**
213: * Set the result set fetch direction constant.
214: */
215: public void setFetchDirection(int direction);
216:
217: /**
218: * Specifies the default eager fetch mode to use. Defaults to
219: * <code>parallel</code> unless the query is by-oid. Possible values are:
220: * <ul>
221: * <li><code>none</code>: When querying for an object, do not try to
222: * select for related objects at the same time.</li>
223: * <li><code>join</code>: When querying for objects, also select for
224: * 1-1 relations in the configured fetch groups using joins.</li>
225: * <li><code>parallel</code>: When querying for objects, also select for
226: * both 1-1 relations using joins and to-many relations using batched
227: * selects.</li>
228: * </li>
229: * </ul>
230: *
231: * @since 0.3.0
232: */
233: public String getEagerFetchMode();
234:
235: /**
236: * Specifies the default eager fetch mode to use. Defaults to
237: * <code>parallel</code> unless the query is by-oid. Possible values are:
238: * <ul>
239: * <li><code>none</code>: When querying for an object, do not try to
240: * select for related objects at the same time.</li>
241: * <li><code>join</code>: When querying for objects, also select for
242: * 1-1 relations in the configured fetch groups using joins.</li>
243: * <li><code>parallel</code>: When querying for objects, also select for
244: * both 1-1 relations using joins and to-many relations using batched
245: * selects.</li>
246: * </ul>
247: */
248: public void setEagerFetchMode(String mode);
249:
250: /**
251: * Return the eager fetch mode as one of the following symbolic constants:
252: * <ul>
253: * <li>{@link EagerFetchModes#EAGER_NONE}</li>
254: * <li>{@link EagerFetchModes#EAGER_JOIN}</li>
255: * <li>{@link EagerFetchModes#EAGER_PARALLEL}</li>
256: * </ul>
257: *
258: * @since 0.3.0
259: */
260: public int getEagerFetchModeConstant();
261:
262: /**
263: * Set the eager fetch mode as one of the following symbolic constants:
264: * <ul>
265: * <li>{@link EagerFetchModes#EAGER_NONE}</li>
266: * <li>{@link EagerFetchModes#EAGER_JOIN}</li>
267: * <li>{@link EagerFetchModes#EAGER_PARALLEL}</li>
268: * </ul>
269: *
270: * @since 0.3.0
271: */
272: public void setEagerFetchMode(int eagerFetchMode);
273:
274: /**
275: * Specifies the default subclass fetch mode to use. Defaults to
276: * <code>join</code> unless the query is by-oid. Possible values are:
277: * <ul>
278: * <li><code>none</code>: Only select base class data.</li>
279: * <li><code>join</code>: Select both base class and all possible subclass
280: * data using joins.</li>
281: * <li><code>parallel</code>: Select for each possible subclass
282: * separately.</li>
283: * </ul>
284: *
285: * @since 0.3.2
286: */
287: public String getSubclassFetchMode();
288:
289: /**
290: * Specifies the default subclass fetch mode to use. Defaults to
291: * <code>join</code> unless the query is by-oid. Possible values are:
292: * <ul>
293: * <li><code>none</code>: Only select base class data.</li>
294: * <li><code>join</code>: Select both base class and all possible subclass
295: * data using joins.</li>
296: * <li><code>parallel</code>: Select for each possible subclass
297: * separately.</li>
298: * </ul>
299: *
300: * @since 0.3.2
301: */
302: public void setSubclassFetchMode(String mode);
303:
304: /**
305: * Return the subclass fetch mode as one of the following symbolic
306: * constants:
307: * <ul>
308: * <li>{@link EagerFetchModes#EAGER_NONE}</li>
309: * <li>{@link EagerFetchModes#EAGER_JOIN}</li>
310: * <li>{@link EagerFetchModes#EAGER_PARALLEL}</li>
311: * </ul>
312: *
313: * @since 0.3.2
314: */
315: public int getSubclassFetchModeConstant();
316:
317: /**
318: * Set the subclass fetch mode as one of the following symbolic constants:
319: * <ul>
320: * <li>{@link EagerFetchModes#EAGER_NONE}</li>
321: * <li>{@link EagerFetchModes#EAGER_JOIN}</li>
322: * <li>{@link EagerFetchModes#EAGER_PARALLEL}</li>
323: * </ul>
324: *
325: * @since 0.3.2
326: */
327: public void setSubclassFetchMode(int subclassFetchMode);
328:
329: /**
330: * How to obtain the size of large result sets. Defaults to
331: * <code>unknown</code>.
332: * <ul>
333: * <li><code>unknown</code>: Do not attempt to calculate the size of
334: * large result sets; return {@link Integer#MAX_VALUE}.</li>
335: * <li><code>last</code>: For result sets that support random access,
336: * calculate the size using {@link java.sql.ResultSet#last}.</li>
337: * <li><code>query</code>: Use a separate COUNT query to calculate the
338: * size of the results.</li>
339: * </ul>
340: */
341: public String getLRSSize();
342:
343: /**
344: * Return the {@link LRSSizes} constant for the large result set size
345: * setting.
346: */
347: public int getLRSSizeConstant();
348:
349: /**
350: * How to obtain the size of large result sets. Defaults to
351: * <code>unknown</code>.
352: * <ul>
353: * <li><code>unknown</code>: Do not attempt to calculate the size of
354: * large result sets; return {@link Integer#MAX_VALUE}.</li>
355: * <li><code>last</code>: For result sets that support random access,
356: * calculate the size using {@link java.sql.ResultSet#last}.</li>
357: * <li><code>query</code>: Use a separate COUNT query to calculate the
358: * size of the results.</li>
359: * </ul>
360: */
361: public void setLRSSize(String lrsSize);
362:
363: /**
364: * Set the fetch configuration large result set size constant.
365: */
366: public void setLRSSize(int size);
367:
368: /**
369: * Whether OpenJPA should try to automatically refresh O/R mapping
370: * information and the database schema.
371: */
372: public String getSynchronizeMappings();
373:
374: /**
375: * Whether OpenJPA should try to automatically refresh O/R mapping
376: * information and the database schema.
377: */
378: public void setSynchronizeMappings(String synchronizeMappings);
379:
380: /**
381: * A comma-separated list of the {@link JDBCListener} plugins for
382: * listening to {@link JDBCEvent}s.
383: */
384: public String getJDBCListeners();
385:
386: /**
387: * A comma-separated list of the {@link JDBCListener} plugins for
388: * listening to {@link JDBCEvent}s.
389: */
390: public void setJDBCListeners(String jdbcListeners);
391:
392: /**
393: * The {@link JDBCListener}s to use.
394: */
395: public JDBCListener[] getJDBCListenerInstances();
396:
397: /**
398: * The {@link JDBCListener}s to use.
399: */
400: public void setJDBCListeners(JDBCListener[] jdbcListeners);
401:
402: /**
403: * A comma-separated list of the {@link ConnectionDecorator} for adding
404: * functionality to JDBC connections.
405: */
406: public String getConnectionDecorators();
407:
408: /**
409: * A comma-separated list of the {@link ConnectionDecorator} for
410: * adding functionality to JDBC connections.
411: */
412: public void setConnectionDecorators(String decorators);
413:
414: /**
415: * The {@link ConnectionDecorator}s to use.
416: */
417: public ConnectionDecorator[] getConnectionDecoratorInstances();
418:
419: /**
420: * The {@link ConnectionDecorator}s to use.
421: */
422: public void setConnectionDecorators(ConnectionDecorator[] decorators);
423:
424: /**
425: * The {@link DBDictionary} to use to define the RDBMS SQL information.
426: */
427: public String getDBDictionary();
428:
429: /**
430: * The {@link DBDictionary} to use to define the RDBMS SQL information.
431: */
432: public void setDBDictionary(String dbdictionary);
433:
434: /**
435: * The {@link DBDictionary} to use.
436: */
437: public DBDictionary getDBDictionaryInstance();
438:
439: /**
440: * The {@link DBDictionary} to use.
441: */
442: public void setDBDictionary(DBDictionary dbdictionary);
443:
444: /**
445: * The {@link UpdateManager} to use for managing SQL updates.
446: */
447: public String getUpdateManager();
448:
449: /**
450: * The {@link UpdateManager} to use for managing SQL updates.
451: */
452: public void setUpdateManager(String updateManager);
453:
454: /**
455: * The {@link UpdateManager} for runtime data store interaction.
456: */
457: public UpdateManager getUpdateManagerInstance();
458:
459: /**
460: * The {@link UpdateManager} for runtime data store interaction.
461: */
462: public void setUpdateManager(UpdateManager updateManager);
463:
464: /**
465: * The {@link DriverDataSource} to use for creating a {@link DataSource}
466: * from a JDBC {@link Driver}.
467: */
468: public String getDriverDataSource();
469:
470: /**
471: * The {@link DriverDataSource} to use for creating a {@link DataSource}
472: * from a JDBC {@link Driver}.
473: */
474: public void setDriverDataSource(String driverDataSource);
475:
476: /**
477: * Create an instance of the {@link DriverDataSource} to use
478: * for creating a {@link DataSource} from a JDBC {@link Driver}.
479: */
480: public DriverDataSource newDriverDataSourceInstance();
481:
482: /**
483: * The plugin string for the {@link SchemaFactory} to use to provide
484: * schema information during system initialization.
485: */
486: public String getSchemaFactory();
487:
488: /**
489: * The plugin string for the {@link SchemaFactory} to use to provide
490: * schema information during system initialization.
491: */
492: public void setSchemaFactory(String schemaFactory);
493:
494: /**
495: * The {@link SchemaFactory} to use for schema information.
496: */
497: public SchemaFactory getSchemaFactoryInstance();
498:
499: /**
500: * The {@link SchemaFactory} to use for schema information.
501: */
502: public void setSchemaFactory(SchemaFactory schemaFactory);
503:
504: /**
505: * The SQL factory to use for SQL constructs.
506: */
507: public String getSQLFactory();
508:
509: /**
510: * The SQL factory to use for SQL constructs.
511: */
512: public SQLFactory getSQLFactoryInstance();
513:
514: /**
515: * The SQL factory to use for SQL constructs.
516: */
517: public void setSQLFactory(String sqlFactory);
518:
519: /**
520: * The SQL factory to use for SQL constructs.
521: */
522: public void setSQLFactory(SQLFactory sqlFactory);
523:
524: /**
525: * A plugin string describing the {@link MetaDataFactory} to use for
526: * loading and storing object-relational mapping data.
527: */
528: public String getMappingFactory();
529:
530: /**
531: * A plugin string describing the {@link MetaDataFactory} to use for
532: * loading and storing object-relational mapping data.
533: */
534: public void setMappingFactory(String mappingFactory);
535:
536: /**
537: * A plugin string describing the {@link MappingDefaults} to use.
538: *
539: * @since 0.4.0
540: */
541: public String getMappingDefaults();
542:
543: /**
544: * A plugin string describing the {@link MappingDefaults} to use.
545: *
546: * @since 0.4.0
547: */
548: public void setMappingDefaults(String map);
549:
550: /**
551: * The {@link MappingDefaults} to use with a repository.
552: *
553: * @since 0.4.0
554: */
555: public MappingDefaults getMappingDefaultsInstance();
556:
557: /**
558: * The {@link MappingDefaults} to use with a repository.
559: *
560: * @since 0.4.0
561: */
562: public void setMappingDefaults(MappingDefaults map);
563:
564: /**
565: * Return the mapping repository. Convenience method to cast from
566: * the internal metadata repository.
567: */
568: public MappingRepository getMappingRepositoryInstance();
569:
570: /**
571: * Return a new empty mapping repository of the configured type.
572: * Convenience method to cast from metadata repository.
573: */
574: public MappingRepository newMappingRepositoryInstance();
575:
576: /**
577: * Return the primary data source to use. The data source will
578: * automatically use the given context's user name and password on calls
579: * to {@link DataSource#getConnection}. If the given context is null, the
580: * data source will use the configuration's default connection user name
581: * and password. If those too are null and the first context has been
582: * obtained already, then the user name and password for that context
583: * will be used, as we know they represent a valid combination. This
584: * method avoids casting the result of
585: * {@link OpenJPAConfiguration#getConnectionFactory}, and avoids having to
586: * pass in the user name and password to obtain connections.
587: */
588: public DataSource getDataSource(StoreContext ctx);
589:
590: /**
591: * Return the non-enlisted data source to use. If there is a valid
592: * non-xa connection factory configured, then it will be returned. Its
593: * default user name and password on calls to
594: * {@link DataSource#getConnection} will be the specificed connection 2
595: * user name and password. If those are null and the given context is
596: * non-null, its user name password will be used instead. If the context
597: * is null too, then the user name and password used to retrieve the first
598: * context will be used. If there is no second connection factory the
599: * primary connection factory is used.
600: *
601: * @see #getDataSource
602: */
603: public DataSource getDataSource2(StoreContext ctx);
604: }
|