EntityStore


1   /*-
2    * See the file LICENSE for redistribution information.
3    *
4    * Copyright (c) 2002,2006 Oracle.  All rights reserved.
5    *
6    * $Id: EntityStore.java,v 1.28 2006/12/04 18:52:56 linda Exp $
7    */
8   
9   package com.sleepycat.persist;
10  
11  import java.util.Set  ;
12  
13  import com.sleepycat.je.Database; // for javadoc
14  import com.sleepycat.je.DatabaseConfig;
15  import com.sleepycat.je.DatabaseException;
16  import com.sleepycat.je.Environment;
17  import com.sleepycat.je.SecondaryConfig;
18  import com.sleepycat.je.Sequence;
19  import com.sleepycat.je.SequenceConfig;
20  import com.sleepycat.je.Transaction;
21  import com.sleepycat.persist.evolve.EvolveConfig;
22  import com.sleepycat.persist.evolve.EvolveStats;
23  import com.sleepycat.persist.evolve.IncompatibleClassException;
24  import com.sleepycat.persist.evolve.Mutations;
25  import com.sleepycat.persist.impl.Store;
26  import com.sleepycat.persist.model.DeleteAction;
27  import com.sleepycat.persist.model.Entity; // for javadoc
28  import com.sleepycat.persist.model.EntityModel;
29  import com.sleepycat.persist.model.PrimaryKey;
30  import com.sleepycat.persist.model.SecondaryKey;
31  
32  /**
33   * A store for managing persistent entity objects.
34   *
35   * <p>{@code EntityStore} objects are thread-safe.  Multiple threads may safely
36   * call the methods of a shared {@code EntityStore} object.</p>
37   *
38   * <p>See the {@link <a HREF="package-summary.html#example">package
39   * summary example</a>} for an example of using an {@code EntityStore}.</p>
40   *
41   * <p>Before creating an <code>EntityStore</code> you must create an {@link
42   * Environment} object using the Berkeley DB engine API.  The environment may
43   * contain any number of entity stores and their associated databases, as well
44   * as other databases not associated with an entity store.</p>
45   *
46   * <p>An entity store is based on an {@link EntityModel}: a data model which
47   * defines persistent classes (<em>entity classes</em>), primary keys,
48   * secondary keys, and relationships between entities.  A primary index is
49   * created for each entity class.  An associated secondary index is created for
50   * each secondary key.  The {@link Entity}, {@link PrimaryKey} and {@link
51   * SecondaryKey} annotations may be used to define entities and keys.</p>
52   *
53   * <p>To use an <code>EntityStore</code>, first obtain {@link PrimaryIndex} and
54   * {@link SecondaryIndex} objects by calling {@link #getPrimaryIndex
55   * getPrimaryIndex} and {@link #getSecondaryIndex getSecondaryIndex}.  Then use
56   * these indices to store and access entity records by key.</p>
57   *
58   * <p>Although not normally needed, you can also use the entity store along
59   * with the {@link com.sleepycat.je Base API}.  Methods in the {@link
60   * PrimaryIndex} and {@link SecondaryIndex} classes may be used to obtain
61   * databases and bindings.  The databases may be used directly for accessing
62   * entity records.  The bindings should be called explicitly to translate
63   * between {@link com.sleepycat.je.DatabaseEntry} objects and entity model
64   * objects.</p>
65   *
66   * <p>Each primary and secondary index is associated internally with a {@link
67   * Database}.  With any of the above mentioned use cases, methods are provided
68   * that may be used for database performance tuning.  The {@link
69   * #setPrimaryConfig setPrimaryConfig} and {@link #setSecondaryConfig
70   * setSecondaryConfig} methods may be called anytime before a database is
71   * opened via {@link #getPrimaryIndex getPrimaryIndex} or {@link
72   * #getSecondaryIndex getSecondaryIndex}.  The {@link #setSequenceConfig
73   * setSequenceConfig} method may be called anytime before {@link #getSequence
74   * getSequence} is called or {@link #getPrimaryIndex getPrimaryIndex} is called
75   * for a primary index associated with that sequence.</p>
76   *
77   * <h3>Database Names</h3>
78   *
79   * <p>The database names of primary and secondary indices are designed to be
80   * unique within the environment and identifiable for debugging and use with
81   * tools such as {@link com.sleepycat.je.util.DbDump} and {@link
82   * com.sleepycat.je.util.DbLoad}.</p>
83   *
84   * <p>The syntax of a primary index database name is:</p>
85   * <pre>   persist#STORE_NAME#ENTITY_CLASS</pre>
86   * <p>Where STORE_NAME is the name parameter passed to {@link #EntityStore
87   * EntityStore} and ENTITY_CLASS is name of the class passed to {@link
88   * #getPrimaryIndex getPrimaryIndex}.</p>
89   *
90   * <p>The syntax of a secondary index database name is:</p>
91   * <pre>   persist#STORE_NAME#ENTITY_CLASS#KEY_NAME</pre>
92   * <p>Where KEY_NAME is the secondary key name passed to {@link
93   * #getSecondaryIndex getSecondaryIndex}.</p>
94   *
95   * <p>Although you should never have to construct these names manually,
96   * understanding their syntax is useful for several reasons:</p>
97   * <ul>
98   * <li>Exception messages sometimes contain the database name, from which you
99   * can identify the entity class and secondary key.</li>
100  * <li>If you create other databases in the same environment that are not
101  * part of an <code>EntityStore</code>, to avoid naming conflicts the other
102  * database names should not begin with <code>"persist#"</code>.</li>
103  * <li>If you are using {@link com.sleepycat.je.util.DbDump} or {@link
104  * com.sleepycat.je.util.DbLoad} to perform a backup or copy databases between
105  * environments, knowing the database names can be useful.  Normally you will
106  * dump or load all database names starting with
107  * <code>"persist#STORE_NAME#"</code>.</li>
108  * </ul>
109  *
110  * <p>If you are copying all databases in a store as mentioned in the last
111  * point above, there is one further consideration.  There are two internal
112  * databases that must be kept with the other databases in the store in order
113  * for the store to be used.  These contain the data formats and sequences for
114  * the store:</p>
115  * <pre>   persist#STORE_NAME#com.sleepycat.persist.formats</pre>
116  * <pre>   persist#STORE_NAME#com.sleepycat.persist.sequences</pre>
117  * <p>These databases should normally be included with copies of other
118  * databases in the store.  They should not be modified by the application.</p>
119  *
120  * @author Mark Hayes
121  */
122 public class EntityStore {
123 
124     private Store store;
125 
126     /**
127      * Opens an entity store in a given environment.
128      *
129      * @param env an open Berkeley DB Environment.
130      *
131      * @param storeName the name of the entity store within the given
132      * environment.  An empty string is allowed.  Named stores may be used to
133      * distinguish multiple sets of persistent entities for the same entity
134      * classes in a single environment.  Underlying database names are prefixed
135      * with the store name.
136      *
137      * @param config the entity store configuration, or null to use default
138      * configuration properties.
139      *
140      * @throws IncompatibleClassException if an incompatible class change has
141      * been made and mutations are not configured for handling the change.  See
142      * {@link com.sleepycat.persist.evolve Class Evolution} for more
143      * information.
144      */
145     public EntityStore(Environment env, String   storeName, StoreConfig config)
146         throws DatabaseException, IncompatibleClassException  {
147 
148         store = new Store(env, storeName, config, false /*rawAccess*/);
149     }
150 
151     /**
152      * Only public for debugging.
153      */
154     void dumpCatalog() {
155         store.dumpCatalog();
156     }
157 
158     /**
159      * Returns the environment associated with this store.
160      *
161      * @return the environment.
162      */
163     public Environment getEnvironment() {
164         return store.getEnvironment();
165     }
166 
167     /**
168      * Returns a copy of the entity store configuration.
169      *
170      * @return the config.
171      */
172     public StoreConfig getConfig() {
173         return store.getConfig();
174     }
175 
176     /**
177      * Returns the name of this store.
178      *
179      * @return the name.
180      */
181     public String   getStoreName() {
182         return store.getStoreName();
183     }
184 
185     /**
186      * Returns the names of all entity stores in the given environment.
187      *
188      * @return the store names.  An empty set is returned if no stores are
189      * present.
190      */
191     public static Set  <String  > getStoreNames(Environment env)
192         throws DatabaseException {
193 
194         return Store.getStoreNames(env);
195     }
196 
197     /**
198      * Returns the current entity model for this store.  The current model is
199      * derived from the configured entity model and the live entity class
200      * definitions.
201      *
202      * @return the model.
203      */
204     public EntityModel getModel() {
205         return store.getModel();
206     }
207 
208     /**
209      * Returns the set of mutations that were configured when the store was
210      * opened, or if none were configured, the set of mutations that were
211      * configured and stored previously.
212      *
213      * @return the mutations.
214      */
215     public Mutations getMutations() {
216         return store.getMutations();
217     }
218 
219     /**
220      * Returns the primary index for a given entity class, opening it if
221      * necessary.
222      *
223      * <p>If they are not already open, the primary and secondary databases for
224      * the entity class are created/opened together in a single internal
225      * transaction.  When the secondary indices are opened, that can cascade to
226      * open other related primary indices.</p>
227      *
228      * @param primaryKeyClass the class of the entity's primary key field, or
229      * the corresponding primitive wrapper class if the primary key field type
230      * is a primitive.
231      *
232      * @param entityClass the entity class for which to open the primary index.
233      *
234      * @return the primary index.
235      *
236      * @throws IllegalArgumentException if the entity class or classes
237      * referenced by it are not persistent, or the primary key class does not
238      * match the entity's primary key field, or if metadata for the entity or
239      * primary key is invalid.
240      */
241     public <PK,E> PrimaryIndex<PK,E> getPrimaryIndex(Class  <PK> primaryKeyClass,
242                                                      Class  <E> entityClass)
243         throws DatabaseException {
244 
245         return store.getPrimaryIndex
246             (primaryKeyClass, primaryKeyClass.getName(),
247              entityClass, entityClass.getName());
248     }
249 
250     /**
251      * Returns a secondary index for a given primary index and secondary key,
252      * opening it if necessary.
253      *
254      * <p><em>NOTE:</em> If the secondary key field is declared in a subclass
255      * of the entity class, use {@link #getSubclassIndex} instead.</p>
256      *
257      * <p>If a {@link SecondaryKey#relatedEntity} is used and the primary index
258      * for the related entity is not already open, it will be opened by this
259      * method.  That will, in turn, open its secondary indices, which can
260      * casade to open other primary indices.</p>
261      *
262      * @param primaryIndex the primary index associated with the returned
263      * secondary index.  The entity class of the primary index, or one of its
264      * superclasses, must contain a secondary key with the given secondary key
265      * class and key name.
266      *
267      * @param keyClass the class of the secondary key field, or the
268      * corresponding primitive wrapper class if the secondary key field type is
269      * a primitive.
270      *
271      * @param keyName the name of the secondary key field, or the {@link
272      * SecondaryKey#name} if this name annotation property was specified.
273      *
274      * @return the secondary index.
275      *
276      * @throws IllegalArgumentException if the entity class or one of its
277      * superclasses does not contain a key field of the given key class and key
278      * name, or if the metadata for the secondary key is invalid.
279      */
280     public <SK,PK,E> SecondaryIndex<SK,PK,E>
281         getSecondaryIndex(PrimaryIndex<PK,E> primaryIndex,
282                           Class  <SK> keyClass,
283                           String   keyName)
284         throws DatabaseException {
285 
286         return store.getSecondaryIndex
287             (primaryIndex, primaryIndex.getEntityClass(),
288              primaryIndex.getEntityClass().getName(),
289              keyClass, keyClass.getName(), keyName);
290     }
291 
292     /**
293      * Returns a secondary index for a secondary key in an entity subclass,
294      * opening it if necessary.
295      *
296      * <p>If a {@link SecondaryKey#relatedEntity} is used and the primary index
297      * for the related entity is not already open, it will be opened by this
298      * method.  That will, in turn, open its secondary indices, which can
299      * casade to open other primary indices.</p>
300      *
301      * @param primaryIndex the primary index associated with the returned
302      * secondary index.  The entity class of the primary index, or one of its
303      * superclasses, must contain a secondary key with the given secondary key
304      * class and key name.
305      *
306      * @param entitySubclass a subclass of the entity class for the primary
307      * index.  The entity subclass must contain a secondary key with the given
308      * secondary key class and key name.
309      *
310      * @param keyClass the class of the secondary key field, or the
311      * corresponding primitive wrapper class if the secondary key field type is
312      * a primitive.
313      *
314      * @param keyName the name of the secondary key field, or the {@link
315      * SecondaryKey#name} if this name annotation property was specified.
316      *
317      * @return the secondary index.
318      *
319      * @throws IllegalArgumentException if the given entity subclass does not
320      * contain a key field of the given key class and key name, or if the
321      * metadata for the secondary key is invalid.
322      */
323     public <SK,PK,E1,E2 extends E1> SecondaryIndex<SK,PK,E2>
324         getSubclassIndex(PrimaryIndex<PK,E1> primaryIndex,
325                          Class  <E2> entitySubclass,
326                          Class  <SK> keyClass,
327                          String   keyName)
328         throws DatabaseException {
329 
330         /* Make subclass metadata available before getting the index. */
331         getModel().getClassMetadata(entitySubclass.getName());
332 
333         return store.getSecondaryIndex
334             (primaryIndex, entitySubclass,
335              primaryIndex.getEntityClass().getName(),
336              keyClass, keyClass.getName(), keyName);
337     }
338 
339     /**
340      * Performs conversion of unevolved objects in order to reduce lazy
341      * conversion overhead.  Evolution may be performed concurrently with
342      * normal access to the store.
343      *
344      * <p>Conversion is performed one entity class at a time.  An entity class
345      * is converted only if it has {@link Mutations} associated with it via
346      * {@link StoreConfig#setMutations StoreConfig.setMutations}.</p>
347      *
348      * <p>Conversion of an entity class is performed by reading each entity,
349      * converting it if necessary, and updating it if conversion was performed.
350      * When all instances of an entity class are converted, references to the
351      * appropriate {@link Mutations} are deleted.  Therefore, if this method is
352      * called twice successfully without changing class definitions, the second
353      * call will do nothing.</p>
354      *
355      * @see com.sleepycat.persist.evolve Class Evolution
356      */
357     public EvolveStats evolve(EvolveConfig config)
358         throws DatabaseException {
359 
360         return store.evolve(config);
361     }
362 
363     /**
364      * Deletes all instances of this entity class and its (non-entity)
365      * subclasses.
366      *
367      * <p>This is the equivalent of {@link Environment#truncateDatabase
368      * Environment.truncateDatabase}.  The primary and secondary databases
369      * associated with the entity class must not be open except by this store,
370      * since database truncation is only possible when the database is not
371      * open.  The databases to be truncated will be closed before performing
372      * this operation, if they were previously opened by this store.</p>
373      *
374      * <p>Auto-commit is used implicitly if the store is transactional.</p>
375      *
376      * @param entityClass the entity class whose instances are to be deleted.
377      */
378     public void truncateClass(Class   entityClass)
379         throws DatabaseException {
380         
381         store.truncateClass(null, entityClass);
382     }
383 
384     /**
385      * Deletes all instances of this entity class and its (non-entity)
386      * subclasses.
387      *
388      * <p>This is the equivalent of {@link Environment#truncateDatabase
389      * Environment.truncateDatabase}.  The primary and secondary databases
390      * associated with the entity class must not be open except by this store,
391      * since database truncation is only possible when the database is not
392      * open.  The databases to be truncated will be closed before performing
393      * this operation, if they were previously opened by this store.</p>
394      *
395      * @param txn the transaction used to protect this operation, null to use
396      * auto-commit, or null if the store is non-transactional.
397      *
398      * @param entityClass the entity class whose instances are to be deleted.
399      */
400     public void truncateClass(Transaction txn, Class   entityClass)
401         throws DatabaseException {
402 
403         store.truncateClass(txn, entityClass);
404     }
405 
406    /**
407     * Flushes each modified index to disk that was opened in deferred-write
408     * mode.
409     *
410     * <p>All indexes are opened in deferred-write mode if true was passed to
411     * {@link StoreConfig#setDeferredWrite} for the store.</p>
412     *
413     * <p>Alternatively, individual databases may be configured for deferred
414     * write using {@link DatabaseConfig#setDeferredWrite} along with {@link
415     * #getPrimaryConfig} and {@link #setPrimaryConfig}.  Caution should be used
416     * when configuring only some databases for deferred-write, since durability
417     * will be different for these databases than for other databases in the
418     * same store.</p>
419     *
420     * <p>This method is functionally equivalent to calling {@link
421     * Database#sync} for each deferred-write index Database that is open for
422     * this store.  However, while {@link Database#sync} flushes the log to disk
423     * each time it is called, this method flushes the log only once after
424     * syncing all databases; this method therefore causes less I/O than calling
425     * {@link Database#sync} multiple times.</p>
426     *
427     * <p>Instead of calling this method, {@link Environment#sync} may be used.
428     * The difference is that this method will only flush the databases for this
429     * store, while {@link Environment#sync} will sync all deferred-write
430     * databases currently open for the environment and will also perform a full
431     * checkpoint.  This method is therefore less expensive than a full sync of
432     * the environment.</p>
433     */
434     public void sync()
435         throws DatabaseException {
436 
437         store.sync();
438     }
439 
440     /**
441      * Closes the primary and secondary databases for the given entity class
442      * that were opened via this store.  The caller must ensure that the
443      * primary and secondary indices obtained from this store are no longer in
444      * use.
445      *
446      * @param entityClass the entity class whose databases are to be closed.
447      */
448     public void closeClass(Class   entityClass)
449         throws DatabaseException {
450 
451         store.closeClass(entityClass);
452     }
453 
454     /**
455      * Closes all databases and sequences that were opened via this store.  The
456      * caller must ensure that no databases opened via this store are in use.
457      */
458     public void close()
459         throws DatabaseException {
460 
461         store.close();
462     }
463 
464     /**
465      * Returns a named sequence for using Berkeley DB engine API directly,
466      * opening it if necessary.
467      *
468      * @param name the sequence name, which is normally defined using the
469      * {@link PrimaryKey#sequence} annotation property.
470      *
471      * @return the open sequence for the given sequence name.
472      */
473     public Sequence getSequence(String   name)
474         throws DatabaseException {
475 
476         return store.getSequence(name);
477     }
478 
479     /**
480      * Returns the default Berkeley DB engine API configuration for a named key
481      * sequence.
482      * 
483      * </p>The returned configuration is as follows.  All other properties have
484      * default values.</p>
485      * <ul>
486      * <li>The {@link SequenceConfig#setInitialValue InitialValue} is one.</li>
487      * <li>The {@link SequenceConfig#setRange Range} minimum is one.</li>
488      * <li>The {@link SequenceConfig#setCacheSize CacheSize} is 100.</li>
489      * <li>{@link SequenceConfig#setAutoCommitNoSync AutoCommitNoSync} is
490      * true.</li>
491      * <li>{@link SequenceConfig#setAllowCreate AllowCreate} is set to true
492      * if the store is not {@link StoreConfig#setReadOnly ReadOnly}.</li>
493      * </ul>
494      *
495      * @param name the sequence name, which is normally defined using the
496      * {@link PrimaryKey#sequence} annotation property.
497      *
498      * @return the default configuration for the given sequence name.
499      */
500     public SequenceConfig getSequenceConfig(String   name) {
501         return store.getSequenceConfig(name);
502     }
503 
504     /**
505      * Configures a named key sequence using the Berkeley DB engine API.
506      *
507      * <p>To be compatible with the entity model and the Direct Persistence
508      * Layer, the configuration should be retrieved using {@link
509      * #getSequenceConfig getSequenceConfig}, modified, and then passed to this
510      * method.</p>
511      *
512      * <p>If the range is changed to include the value zero, see {@link
513      * PrimaryKey} for restrictions.</p>
514      *
515      * @param name the sequence name, which is normally defined using the
516      * {@link PrimaryKey#sequence} annotation property.
517      *
518      * @param config the configuration to use for the given sequence name.
519      *
520      * @throws IllegalArgumentException if the configuration is incompatible
521      * with the entity model or the Direct Persistence Layer.
522      *
523      * @throws IllegalStateException if the sequence has already been opened.
524      */
525     public void setSequenceConfig(String   name, SequenceConfig config) {
526         store.setSequenceConfig(name, config);
527     }
528 
529     /**
530      * Returns the default primary database Berkeley DB engine API
531      * configuration for an entity class.
532      * 
533      * </p>The returned configuration is as follows.  All other properties have
534      * default values.</p>
535      * <ul>
536      * <li>{@link DatabaseConfig#setTransactional Transactional} is set to
537      * match {@link StoreConfig#setTransactional StoreConfig}.</li>
538      * <li>{@link DatabaseConfig#setAllowCreate AllowCreate} is set to true
539      * if the store is not {@link StoreConfig#setReadOnly ReadOnly}.</li>
540      * <li>{@link DatabaseConfig#setReadOnly ReadOnly} is set to match
541      * {@link StoreConfig#setReadOnly StoreConfig}.</li>
542      * <li>{@link DatabaseConfig#setDeferredWrite DeferredWrite} is set to
543      * match {@link StoreConfig#setDeferredWrite StoreConfig}.</li>
544      * <li>{@link DatabaseConfig#setBtreeComparator BtreeComparator} is set to
545      * an internal class if a key comparator is used.</li>
546      * </ul>
547      *
548      * @param entityClass the entity class identifying the primary database.
549      *
550      * @return the default configuration for the given entity class.
551      */
552     public DatabaseConfig getPrimaryConfig(Class   entityClass) {
553         return store.getPrimaryConfig(entityClass);
554     }
555 
556     /**
557      * Configures the primary database for an entity class using the Berkeley
558      * DB engine API.
559      *
560      * <p>To be compatible with the entity model and the Direct Persistence
561      * Layer, the configuration should be retrieved using {@link
562      * #getPrimaryConfig getPrimaryConfig}, modified, and then passed to this
563      * method.  The following configuration properties may not be changed:</p>
564      * <ul>
565      * <li>{@link DatabaseConfig#setSortedDuplicates SortedDuplicates}</li>
566      * <li>{@link DatabaseConfig#setBtreeComparator BtreeComparator}</li>
567      * </ul>
568      *
569      * @param entityClass the entity class identifying the primary database.
570      *
571      * @param config the configuration to use for the given entity class.
572      *
573      * @throws IllegalArgumentException if the configuration is incompatible
574      * with the entity model or the Direct Persistence Layer.
575      *
576      * @throws IllegalStateException if the database has already been opened.
577      */
578     public void setPrimaryConfig(Class   entityClass, DatabaseConfig config) {
579         store.setPrimaryConfig(entityClass, config);
580     }
581 
582     /**
583      * Returns the default secondary database Berkeley DB engine API
584      * configuration for an entity class and key name.
585      * 
586      * </p>The returned configuration is as follows.  All other properties have
587      * default values.</p>
588      * <ul>
589      * <li>{@link DatabaseConfig#setTransactional Transactional} is set to
590      * match the primary database.</li>
591      * <li>{@link DatabaseConfig#setAllowCreate AllowCreate} is set to true
592      * if the primary database is not {@link StoreConfig#setReadOnly
593      * ReadOnly}.</li>
594      * <li>{@link DatabaseConfig#setReadOnly ReadOnly} is set to match
595      * the primary database.</li>
596      * <li>{@link DatabaseConfig#setDeferredWrite DeferredWrite} is set to
597      * match the primary database.</li>
598      * <li>{@link DatabaseConfig#setBtreeComparator BtreeComparator} is set to
599      * an internal class if a key comparator is used.</li>
600      * <li>{@link DatabaseConfig#setSortedDuplicates SortedDuplicates} is set
601      * according to {@link SecondaryKey#relate}.</p>
602      * <li>{@link SecondaryConfig#setAllowPopulate AllowPopulate} is set to
603      * true when a secondary key is added to an existing primary index.</li>
604      * <li>{@link SecondaryConfig#setKeyCreator KeyCreator} or {@link
605      * SecondaryConfig#setMultiKeyCreator MultiKeyCreator} is set to an
606      * internal instance.</p>
607      * <li>{@link SecondaryConfig#setForeignMultiKeyNullifier
608      * ForeignMultiKeyNullifier} is set to an internal instance if {@link
609      * SecondaryKey#onRelatedEntityDelete} is {@link DeleteAction#NULLIFY}.</li>
610      * </ul>
611      *
612      * @param entityClass the entity class containing the given secondary key
613      * name.
614      *
615      * @param keyName the name of the secondary key field, or the {@link
616      * SecondaryKey#name} if this name annotation property was specified.
617      *
618      * @return the default configuration for the given secondary key.
619      */
620     public SecondaryConfig getSecondaryConfig(Class   entityClass,
621                                               String   keyName) {
622         return store.getSecondaryConfig(entityClass, keyName);
623     }
624 
625     /**
626      * Configures a secondary database for an entity class and key name using
627      * the Berkeley DB engine API.
628      *
629      * <p>To be compatible with the entity model and the Direct Persistence
630      * Layer, the configuration should be retrieved using {@link
631      * #getSecondaryConfig getSecondaryConfig}, modified, and then passed to
632      * this method.  The following configuration properties may not be
633      * changed:</p>
634      * <ul>
635      * <li>{@link DatabaseConfig#setSortedDuplicates SortedDuplicates}</li>
636      * <li>{@link DatabaseConfig#setBtreeComparator BtreeComparator}</li>
637      * <li>{@link DatabaseConfig#setDuplicateComparator
638      * DuplicateComparator}</li>
639      * <li>{@link SecondaryConfig#setAllowPopulate AllowPopulate}</li>
640      * <li>{@link SecondaryConfig#setKeyCreator KeyCreator}</li>
641      * <li>{@link SecondaryConfig#setMultiKeyCreator MultiKeyCreator}</li>
642      * <li>{@link SecondaryConfig#setForeignKeyNullifier
643      * ForeignKeyNullifier}</li>
644      * <li>{@link SecondaryConfig#setForeignMultiKeyNullifier
645      * ForeignMultiKeyNullifier}</li>
646      * <li>{@link SecondaryConfig#setForeignKeyDeleteAction
647      * ForeignKeyDeleteAction}</li>
648      * <li>{@link SecondaryConfig#setForeignKeyDatabase
649      * ForeignKeyDatabase}</li>
650      * </ul>
651      *
652      * @param entityClass the entity class containing the given secondary key
653      * name.
654      *
655      * @param keyName the name of the secondary key field, or the {@link
656      * SecondaryKey#name} if this name annotation property was specified.
657      *
658      * @param config the configuration to use for the given secondary key.
659      *
660      * @throws IllegalArgumentException if the configuration is incompatible
661      * with the entity model or the Direct Persistence Layer.
662      *
663      * @throws IllegalStateException if the database has already been opened.
664      */
665     public void setSecondaryConfig(Class   entityClass,
666                                    String   keyName,
667                                    SecondaryConfig config) {
668         store.setSecondaryConfig(entityClass, keyName, config);
669     }
670 }
671
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags