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