001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.raw.data.DataFactory
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.store.raw.data;
023:
024: import org.apache.derby.iapi.store.raw.ContainerKey;
025:
026: import org.apache.derby.iapi.services.daemon.Serviceable;
027: import org.apache.derby.iapi.services.context.ContextManager;
028:
029: import org.apache.derby.iapi.error.StandardException;
030: import org.apache.derby.iapi.store.raw.ContainerHandle;
031: import org.apache.derby.iapi.store.raw.Corruptable;
032: import org.apache.derby.iapi.store.raw.LockingPolicy;
033: import org.apache.derby.iapi.store.raw.RawStoreFactory;
034: import org.apache.derby.iapi.store.raw.RecordHandle;
035: import org.apache.derby.iapi.store.raw.StreamContainerHandle;
036: import org.apache.derby.iapi.store.raw.xact.RawTransaction;
037: import org.apache.derby.iapi.store.raw.Transaction;
038: import org.apache.derby.io.StorageFactory;
039: import org.apache.derby.iapi.store.access.FileResource;
040: import org.apache.derby.iapi.store.access.RowSource;
041: import org.apache.derby.iapi.store.raw.log.LogInstant;
042: import org.apache.derby.iapi.util.ByteArray;
043: import org.apache.derby.catalog.UUID;
044:
045: import java.util.Properties;
046: import java.io.File;
047:
048: public interface DataFactory extends Corruptable {
049:
050: public static final String MODULE = "org.apache.derby.iapi.store.raw.data.DataFactory";
051:
052: /**
053: The temporary segment is called "tmp"
054: */
055: public static final String TEMP_SEGMENT_NAME = "tmp";
056:
057: /**
058: The database lock
059: */
060: public static final String DB_LOCKFILE_NAME = "db.lck";
061:
062: /*
063: ** file name that is used to acquire exclusive lock on DB.
064: **/
065: public static final String DB_EX_LOCKFILE_NAME = "dbex.lck";
066:
067: /**
068: Is the store read-only.
069: */
070: public boolean isReadOnly();
071:
072: /**
073: Open a container that is not droped.
074:
075: @param t the raw transaction that is opening the container
076: @param containerId the container's identity
077: @param locking the locking policy
078: @param mode see the different mode in @see ContainerHandle
079: then will return a null handle if the container is dropped.
080:
081: @return the handle to the opened container
082: @exception StandardException Standard Cloudscape error policy
083:
084: */
085: public ContainerHandle openContainer(RawTransaction t,
086: ContainerKey containerId, LockingPolicy locking, int mode)
087: throws StandardException;
088:
089: /**
090: Open a container that may have been dropped.
091: Only internal raw store code should call this, e.g. recovery.
092:
093: @see #openContainer
094: @exception StandardException Standard Cloudscape error policy
095: */
096: public RawContainerHandle openDroppedContainer(RawTransaction t,
097: ContainerKey containerId, LockingPolicy locking, int mode)
098: throws StandardException;
099:
100: /**
101: Add a container.
102:
103: @param t the transaction that is creating the container
104: @param segmentId the segment where the container is to go
105: @param mode whether or not to LOGGED or not. The effect of this mode
106: is only for this addContainer call, not persisently stored
107: throughout the lifetime of the container
108: @param tableProperties properties of the container that is persistently
109: stored throughout the lifetime of the container
110:
111: @return the containerId of the newly created container
112:
113: @exception StandardException Standard Cloudscape Error policy
114:
115: */
116: public long addContainer(RawTransaction t, long segmentId,
117: long containerid, int mode, Properties tableProperties,
118: int temporaryFlag) throws StandardException;
119:
120: /**
121: Create and load a stream container.
122:
123: @param t the transaction that is creating the container
124: @param segmentId the segment where the container is to go
125: @param tableProperties properties of the container that is persistently
126: stored throughout the lifetime of the container
127: @param rowSource the data to load the container with
128:
129: @return the containerId of the newly created stream container
130:
131: @exception StandardException Standard Cloudscape Error policy
132:
133: */
134: public long addAndLoadStreamContainer(RawTransaction t,
135: long segmentId, Properties tableProperties,
136: RowSource rowSource) throws StandardException;
137:
138: /**
139: Open a stream container.
140:
141: @return a valid StreamContainerHandle or null if the container does not exist.
142:
143: @exception StandardException Standard cloudscape exception policy
144:
145: */
146: public StreamContainerHandle openStreamContainer(RawTransaction t,
147: long segmentId, long containerId, boolean hold)
148: throws StandardException;
149:
150: /**
151: Drop and remove a stream container.
152:
153: @exception StandardException Standard cloudscape exception policy
154: */
155: public void dropStreamContainer(RawTransaction t, long segmentId,
156: long containerId) throws StandardException;
157:
158: /**
159: re-Create a container during redo recovery.
160:
161: Used if container is found to not exist during redo recovery of
162: log records creating the container.
163:
164: @exception StandardException Standard Cloudscape Error policy
165: */
166: public void reCreateContainerForRedoRecovery(RawTransaction t,
167: long segmentId, long containerId, ByteArray containerInfo)
168: throws StandardException;
169:
170: public void dropContainer(RawTransaction t, ContainerKey containerId)
171: throws StandardException;
172:
173: public void checkpoint() throws StandardException;
174:
175: public void idle() throws StandardException;
176:
177: /**
178: Return the identifier that uniquely identifies this raw store at runtime.
179: This identifier is to be used as part of the lokcing key for objects
180: locked in the raw store by value (e.g. Containers).
181: */
182: public UUID getIdentifier();
183:
184: /**
185: make data factory aware of which raw store factory it belongs to
186: Also need to boot the LogFactory
187:
188: @exception StandardException cannot boot the log factory
189: */
190: public void setRawStoreFactory(RawStoreFactory rsf, boolean create,
191: Properties properties) throws StandardException;
192:
193: /**
194: Return a record handle that is initialized to the given page number and
195: record id.
196:
197: @exception StandardException Standard cloudscape exception policy.
198:
199: @param segmentId segment where the RecordHandle belongs.
200: @param containerId container where the RecordHandle belongs.
201: @param pageNumber the page number of the RecordHandle.
202: @param recordId the record id of the RecordHandle.
203:
204: @see RecordHandle
205: */
206: // public RecordHandle makeRecordHandle(long segmentId, long containerId, long pageNumber, int recordId)
207: // throws StandardException;
208: /**
209: Database creation finished
210:
211: @exception StandardException Standard cloudscape exception policy.
212: */
213: public void createFinished() throws StandardException;
214:
215: /**
216: Get an object to handle non-transactional files.
217: */
218: public FileResource getFileHandler();
219:
220: /**
221: Tell the data factory it is OK to remove committed deleted containers
222: when the data factory shuts down.
223: */
224: public void removeStubsOK();
225:
226: /**
227: Get cache statistics for the specified cache
228: */
229: public long[] getCacheStats(String cacheName);
230:
231: /**
232: Reset the cache statistics for the specified cache
233: */
234: public void resetCacheStats(String cacheName);
235:
236: /**
237: Reclaim space used by this factory. Called by post commit daemon.
238: @exception StandardException Standard cloudscape exception policy
239: */
240: public int reclaimSpace(Serviceable work, ContextManager contextMgr)
241: throws StandardException;
242:
243: /**
244: Called after recovery is performed.
245:
246: @exception StandardException Standard Cloudscape Error Policy
247: */
248: public void postRecovery() throws StandardException;
249:
250: /**
251: Encrypt cleartext into ciphertext.
252:
253: @see org.apache.derby.iapi.services.crypto.CipherProvider#encrypt
254: @exception StandardException Standard Cloudscape Error Policy
255: */
256: public int encrypt(byte[] cleartext, int offset, int length,
257: byte[] ciphertext, int outputOffset, boolean newEngine)
258: throws StandardException;
259:
260: /**
261: Decrypt cleartext from ciphertext.
262:
263: @see org.apache.derby.iapi.services.crypto.CipherProvider#decrypt
264: @exception StandardException Standard Cloudscape Error Policy
265: */
266: public int decrypt(byte[] ciphertext, int offset, int length,
267: byte[] cleartext, int outputOffset)
268: throws StandardException;
269:
270: /**
271: * Encrypt all the containers in the data segment.
272: * @param t the transaction that is encrypting the containers.
273: * @exception StandardException Standard Derby Error Policy
274: */
275: public void encryptAllContainers(RawTransaction t)
276: throws StandardException;
277:
278: /*
279: * Remove old versions of the containers after (re)encryption
280: * of the database.
281: * @param inRecovery <code> true </code>, if cleanup is
282: * happening during recovery.
283: * @exception StandardException Standard Derby Error Policy
284: */
285: public void removeOldVersionOfContainers(boolean inRecovery)
286: throws StandardException;
287:
288: /*
289: * Set that the database is encrypted.
290: */
291: public void setDatabaseEncrypted();
292:
293: /**
294: Return the encryption block size used by the algorithm at time of
295: encrypted database creation
296: */
297: public int getEncryptionBlockSize();
298:
299: /**
300: * Backup restore - stop writing dirty pages or container to disk
301: * @exception StandardException Standard Cloudscape error policy
302: */
303: public void freezePersistentStore() throws StandardException;
304:
305: /**
306: * Backup restore - start writing dirty pages or container to disk
307: */
308: public void unfreezePersistentStore();
309:
310: /**
311: * Backup restore - don't allow the persistent store to be frozen - or if
312: * it is already frozen, block. A write is about to commence.
313: * @exception StandardException Standard Cloudscape error policy
314: */
315: public void writeInProgress() throws StandardException;
316:
317: /**
318: * Backup restore - write finished, if this is the last writer, allow the
319: * persistent store to proceed.
320: */
321: public void writeFinished();
322:
323: /**
324: * Back up the data segment of the database.
325: */
326: public void backupDataFiles(Transaction rt, File backupDir)
327: throws StandardException;
328:
329: /**
330: * Return an id which can be used to create a container.
331: * <p>
332: * Return an id number with is greater than any existing container
333: * in the current database. Caller will use this to allocate future
334: * container numbers - most likely caching the value and then incrementing
335: * it as it is used.
336: * <p>
337: *
338: * @return The an id which can be used to create a container.
339: *
340: * @exception StandardException Standard exception policy.
341: **/
342: long getMaxContainerId() throws StandardException;
343:
344: /**
345: * This function is called after a checkpoint to remove the stub files thar are not required
346: * during recovery. Crash recovery uses these files to identify the dropped
347: * containers. Stub files(d*.dat) gets creates when a
348: * table/index(containers) dropped.
349: * @exception StandardException Standard Cloudscape error policy
350: **/
351: public void removeDroppedContainerFileStubs(LogInstant redoLWM)
352: throws StandardException;
353:
354: /**
355: * @return The StorageFactory used by this dataFactory
356: */
357: public StorageFactory getStorageFactory();
358:
359: public void stop();
360: }
|