001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.access.AccessFactory
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.access;
023:
024: import org.apache.derby.catalog.UUID;
025:
026: import org.apache.derby.iapi.services.context.ContextManager;
027: import org.apache.derby.iapi.services.locks.LockFactory;
028:
029: import org.apache.derby.iapi.error.StandardException;
030:
031: import org.apache.derby.iapi.store.access.conglomerate.MethodFactory;
032:
033: import org.apache.derby.iapi.services.property.PropertySetCallback;
034: import java.util.Properties;
035: import java.io.File;
036:
037: /**
038:
039: Module interface for an access manager. An access manager provides
040: transactional access via access methods to data in a single storage
041: manager.
042: <p>
043: An AccessFactory is typically obtained from the Monitor:
044: <p>
045: <blockquote><pre>
046: // Get the current transaction controller.
047: AccessFactory af;
048: af = (AccessFactory) Monitor.findServiceModule(this, AccessFactory.MODULE);
049: </pre></blockquote>
050: **/
051:
052: public interface AccessFactory {
053: /**
054: * Used to identify this interface when finding it with the Monitor.
055: **/
056: public static final String MODULE = "org.apache.derby.iapi.store.access.AccessFactory";
057:
058: /**
059: * Register an access method that this access manager can use.
060: **/
061: void registerAccessMethod(MethodFactory factory);
062:
063: /**
064: * Database creation has finished.
065: *
066: * @exception StandardException Standard exception policy.
067: **/
068: public void createFinished() throws StandardException;
069:
070: /**
071: *Find an access method that implements an implementation type.
072: *
073: * @exception StandardException Standard exception policy.
074: **/
075: MethodFactory findMethodFactoryByImpl(String impltype)
076: throws StandardException;
077:
078: /**
079: * Find an access method that implements a format type.
080: **/
081: MethodFactory findMethodFactoryByFormat(UUID format);
082:
083: /**
084: * Get the LockFactory to use with this store.
085: *
086: * @return The lock factory to use with this store.
087: *
088: **/
089: public LockFactory getLockFactory();
090:
091: /**
092: * Return the XAResourceManager associated with this AccessFactory.
093: * <p>
094: * Returns an object which can be used to implement the "offline"
095: * 2 phase commit interaction between the accessfactory and outstanding
096: * transaction managers taking care of in-doubt transactions.
097: *
098: * @return The XAResourceManager associated with this accessfactory.
099: *
100: * @exception StandardException Standard exception policy.
101: *
102: **/
103: public/* XAResourceManager */Object getXAResourceManager()
104: throws StandardException;
105:
106: /**
107: * Is the store read-only.
108: */
109: public boolean isReadOnly();
110:
111: /**************************************************************************
112: * methods that are Property related.
113: **************************************************************************
114: */
115:
116: /**************************************************************************
117: * methods that are transaction related.
118: **************************************************************************
119: */
120:
121: /**
122: * Get a transaction controller with which to manipulate data within
123: * the access manager. Implicitly creates an access context if one
124: * does not already exist.
125: *
126: * @param cm The context manager for the current context.
127: *
128: * @exception StandardException Standard exception policy.
129: * @see TransactionController
130: **/
131:
132: TransactionController getTransaction(ContextManager cm)
133: throws StandardException;
134:
135: /**
136: * Get a transaction. If a new transaction is
137: * implicitly created, give it name transName.
138: *
139: * @param cm The context manager for the current context.
140: * @param transName If a new transaction is started, it will be given
141: * this name. The name is displayed in the
142: * transactiontable VTI.
143: *
144: * @exception StandardException Standard exception policy.
145: *
146: * @see TransactionController
147: * @see AccessFactory#getTransaction
148: */
149: TransactionController getAndNameTransaction(ContextManager cm,
150: String transName) throws StandardException;
151:
152: /**
153: * Return a snap shot of all transactions in the db.
154: * <p>
155: * Take a snap shot of all transactions currently in the database and make
156: * a record of their information.
157: *
158: * @return an array of TransactionInfo, or null if there is
159: * no transaction in the database.
160: *
161: **/
162: public TransactionInfo[] getTransactionInfo();
163:
164: /**
165: * Start a global transaction.
166: * <p>
167: * Get a transaction controller with which to manipulate data within
168: * the access manager. Implicitly creates an access context.
169: * <p>
170: * Must only be called if no other transaction context exists in the
171: * current context manager. If another transaction exists in the context
172: * an exception will be thrown.
173: * <p>
174: * The (format_id, global_id, branch_id) triplet is meant to come exactly
175: * from a javax.transaction.xa.Xid. We don't use Xid so that the system
176: * can be delivered on a non-1.2 vm system and not require the javax classes
177: * in the path.
178: * <p>
179: * If the global transaction id given matches an existing in-doubt global
180: * transaction in the current system, then a StandardException will
181: * be thrown with a state of SQLState.STORE_XA_XAER_DUPID.
182: * <p>
183: *
184: * @param cm The context manager for the current context.
185: * @param format_id the format id part of the Xid - ie. Xid.getFormatId().
186: * @param global_id the global transaction identifier part of XID - ie.
187: * Xid.getGlobalTransactionId().
188: * @param branch_id The branch qualifier of the Xid - ie.
189: * Xid.getBranchQaulifier()
190: *
191: * @exception StandardException Standard exception policy.
192: * @see TransactionController
193: **/
194: /* XATransactionController */Object startXATransaction(
195: ContextManager cm, int format_id, byte[] global_id,
196: byte[] branch_id) throws StandardException;
197:
198: /**************************************************************************
199: * methods that implement functionality on the
200: * org.apache.derby.iapi.db API
201: **************************************************************************
202: */
203:
204: /**
205: * Freeze the database temporarily so a backup can be taken.
206: * <P>Please see Derby on line documentation on backup and restore.
207: *
208: * @exception StandardException Thrown on error
209: */
210: public void freeze() throws StandardException;
211:
212: /**
213: * Unfreeze the database after a backup has been taken.
214: * <P>Please see Derby on line documentation on backup and restore.
215: *
216: * @exception StandardException Thrown on error
217: */
218: public void unfreeze() throws StandardException;
219:
220: /**
221: * Backup the database to backupDir.
222: * <P>Please see Derby on line documentation on backup and restore.
223: *
224: * @param backupDir the name of the directory where the backup should be
225: * stored.
226: * @param wait if <tt>true</tt>, waits for all the backup blocking
227: * operations in progress to finish.
228: *
229: * @exception StandardException Thrown on error
230: */
231: public void backup(String backupDir, boolean wait)
232: throws StandardException;
233:
234: /**
235: * Backup the database to a backup directory and enable the log archive
236: * mode that will keep the archived log files required for roll-forward
237: * from this version backup.
238: *
239: * @param backupDir the directory name where the
240: * database backup should go. This
241: * directory will be created if not it
242: * does not exist.
243: *
244: * @param deleteOnlineArchivedLogFiles If true deletes online archived log
245: * files that exist before this backup,
246: * delete will occur only after backup
247: * is complete.
248: *
249: * @param wait if <tt>true</tt>, waits for all the
250: * backup blocking operations in
251: * progress to finish.
252: *
253: * @exception StandardException Thrown on error
254: */
255: public void backupAndEnableLogArchiveMode(String backupDir,
256: boolean deleteOnlineArchivedLogFiles, boolean wait)
257: throws StandardException;
258:
259: /**
260: * disables the log archival process, i.e No old log files
261: * will be kept around for a roll-forward recovery.
262: *
263: * @param deleteOnlineArchivedLogFiles If true deletes all online archived
264: * log files that exist before this
265: * call immediately; Only restore that
266: * can be performed after disabling log
267: * archive mode is version recovery.
268: *
269: * @exception StandardException Thrown on error
270: */
271: public void disableLogArchiveMode(
272: boolean deleteOnlineArchivedLogFiles)
273: throws StandardException;
274:
275: /**
276: * Checkpoints the database, that is, flushes all dirty data to disk.
277: * Records a checkpoint in the transaction log, if there is a log.
278: *
279: * @exception StandardException Thrown on error
280: */
281: public void checkpoint() throws StandardException;
282:
283: /*
284: *Wait until the thread handling the post commit work
285: *finihes the work assigned to it.
286: */
287: public void waitForPostCommitToFinishWork();
288:
289: }
|