1 /*-
2  * Copyright (c) 2002, 2020 Oracle and/or its affiliates.  All rights reserved.
3  *
4  * See the file LICENSE for license information.
5  *
6  */
7 
8 package com.sleepycat.persist.raw;
9 
10 import java.io.Closeable;
11 
12 import com.sleepycat.compat.DbCompat;
13 import com.sleepycat.db.DatabaseException;
14 import com.sleepycat.db.Environment;
15 import com.sleepycat.persist.PrimaryIndex;
16 import com.sleepycat.persist.SecondaryIndex;
17 import com.sleepycat.persist.StoreConfig;
18 import com.sleepycat.persist.StoreExistsException;
19 import com.sleepycat.persist.StoreNotFoundException;
20 import com.sleepycat.persist.evolve.IncompatibleClassException;
21 import com.sleepycat.persist.evolve.Mutations;
22 import com.sleepycat.persist.impl.Store;
23 import com.sleepycat.persist.model.EntityModel;
24 
25 /**
26  * Provides access to the raw data in a store for use by general purpose tools.
27  * A <code>RawStore</code> provides access to stored entities without using
28  * entity classes or key classes.  Keys are represented as simple type objects
29  * or, for composite keys, as {@link RawObject} instances, and entities are
30  * represented as {@link RawObject} instances.
31  *
32  * <p>{@code RawStore} objects are thread-safe.  Multiple threads may safely
33  * call the methods of a shared {@code RawStore} object.</p>
34  *
35  * <p>When using a {@code RawStore}, the current persistent class definitions
36  * are not used.  Instead, the previously stored metadata and class definitions
37  * are used.  This has several implications:</p>
38  * <ol>
39  * <li>An {@code EntityModel} may not be specified using {@link
40  * StoreConfig#setModel}.  In other words, the configured model must be
41  * null (the default).</li>
42  * <li>When storing entities, their format will not automatically be evolved
43  * to the current class definition, even if the current class definition has
44  * changed.</li>
45  * </ol>
46  *
47  * @author Mark Hayes
48  */
49 public class RawStore
50     {
51 
52     private Store store;
53 
54     /**
55      * Opens an entity store for raw data access.
56      *
57      * @param env an open Berkeley DB environment.
58      *
59      * @param storeName the name of the entity store within the given
60      * environment.
61      *
62      * @param config the store configuration, or null to use default
63      * configuration properties.
64      *
65      * @throws StoreNotFoundException when the {@link
66      * StoreConfig#setAllowCreate AllowCreate} configuration parameter is false
67      * and the store's internal catalog database does not exist.
68      *
69      * @throws IllegalArgumentException if the <code>Environment</code> is
70      * read-only and the <code>config ReadOnly</code> property is false.
71      *
72      * @throws DatabaseException the base class for all BDB exceptions.
73      */
RawStore(Environment env, String storeName, StoreConfig config)74     public RawStore(Environment env, String storeName, StoreConfig config)
75         throws StoreNotFoundException, DatabaseException {
76 
77         try {
78             store = new Store(env, storeName, config, true /*rawAccess*/);
79         } catch (StoreExistsException e) {
80             /* Should never happen, ExclusiveCreate not used. */
81             throw DbCompat.unexpectedException(e);
82         } catch (IncompatibleClassException e) {
83             /* Should never happen, evolution is not performed. */
84             throw DbCompat.unexpectedException(e);
85         }
86     }
87 
88     /**
89      * Opens the primary index for a given entity class.
90      *
91      * @param entityClass the name of the entity class.
92      *
93      * @return the PrimaryIndex.
94      *
95      * @throws DatabaseException the base class for all BDB exceptions.
96      */
getPrimaryIndex(String entityClass)97     public PrimaryIndex<Object, RawObject> getPrimaryIndex(String entityClass)
98         throws DatabaseException {
99 
100         return store.getPrimaryIndex
101             (Object.class, null, RawObject.class, entityClass);
102     }
103 
104     /**
105      * Opens the secondary index for a given entity class and secondary key
106      * name.
107      *
108      * @param entityClass the name of the entity class.
109      *
110      * @param keyName the secondary key name.
111      *
112      * @return the SecondaryIndex.
113      *
114      * @throws DatabaseException the base class for all BDB exceptions.
115      */
116     public SecondaryIndex<Object, Object, RawObject>
getSecondaryIndex(String entityClass, String keyName)117         getSecondaryIndex(String entityClass, String keyName)
118         throws DatabaseException {
119 
120         return store.getSecondaryIndex
121             (getPrimaryIndex(entityClass), RawObject.class, entityClass,
122              Object.class, null, keyName);
123     }
124 
125     /**
126      * Returns the environment associated with this store.
127      *
128      * @return the Environment.
129      */
getEnvironment()130     public Environment getEnvironment() {
131         return store.getEnvironment();
132     }
133 
134     /**
135      * Returns a copy of the entity store configuration.
136      *
137      * @return the StoreConfig.
138      */
getConfig()139     public StoreConfig getConfig() {
140         return store.getConfig();
141     }
142 
143     /**
144      * Returns the name of this store.
145      *
146      * @return the store name.
147      */
getStoreName()148     public String getStoreName() {
149         return store.getStoreName();
150     }
151 
152     /**
153      * Returns the last configured and stored entity model for this store.
154      *
155      * @return the EntityModel.
156      */
getModel()157     public EntityModel getModel() {
158         return store.getModel();
159     }
160 
161     /**
162      * Returns the set of mutations that were configured and stored previously.
163      *
164      * @return the Mutations.
165      */
getMutations()166     public Mutations getMutations() {
167         return store.getMutations();
168     }
169 
170     /**
171      * Closes all databases and sequences that were opened by this model.  No
172      * databases opened via this store may be in use.
173      *
174      * <p>WARNING: To guard against memory leaks, the application should
175      * discard all references to the closed handle.  While BDB makes an effort
176      * to discard references from closed objects to the allocated memory for an
177      * environment, this behavior is not guaranteed.  The safe course of action
178      * for an application is to discard all references to closed BDB
179      * objects.</p>
180      *
181      * @throws DatabaseException the base class for all BDB exceptions.
182      */
close()183     public void close()
184         throws DatabaseException {
185 
186         store.close();
187     }
188 }
189