AccessFactory


1   /*
2   
3      Derby - Class org.apache.derby.iapi.store.access.AccessFactory
4   
5      Licensed to the Apache Software Foundation (ASF) under one or more
6      contributor license agreements.  See the NOTICE file distributed with
7      this work for additional information regarding copyright ownership.
8      The ASF licenses this file to you under the Apache License, Version 2.0
9      (the "License"); you may not use this file except in compliance with
10     the License.  You may obtain a copy of the License at
11  
12        http://www.apache.org/licenses/LICENSE-2.0
13  
14     Unless required by applicable law or agreed to in writing, software
15     distributed under the License is distributed on an "AS IS" BASIS,
16     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17     See the License for the specific language governing permissions and
18     limitations under the License.
19  
20   */
21  
22  package org.apache.derby.iapi.store.access;
23  
24  import org.apache.derby.catalog.UUID;
25  
26  import org.apache.derby.iapi.services.context.ContextManager;
27  import org.apache.derby.iapi.services.locks.LockFactory;
28  
29  import org.apache.derby.iapi.error.StandardException;
30  
31  import org.apache.derby.iapi.store.access.conglomerate.MethodFactory;
32  
33  import org.apache.derby.iapi.services.property.PropertySetCallback;
34  import java.util.Properties  ;
35  import java.io.File  ;
36  
37  /**
38  
39    Module interface for an access manager.  An access manager provides
40    transactional access via access methods to data in a single storage
41    manager.
42    <p>
43    An AccessFactory is typically obtained from the Monitor:
44    <p>
45    <blockquote><pre>
46      // Get the current transaction controller.
47      AccessFactory af;
48      af = (AccessFactory) Monitor.findServiceModule(this, AccessFactory.MODULE);
49    </pre></blockquote>
50  **/
51  
52  public interface AccessFactory
53  {
54      /**
55       * Used to identify this interface when finding it with the Monitor.
56       **/
57      public static final String   MODULE = 
58          "org.apache.derby.iapi.store.access.AccessFactory";
59  
60      /**
61       * Register an access method that this access manager can use.
62       **/
63      void registerAccessMethod(MethodFactory factory);
64  
65      /**
66       * Database creation has finished.
67       *
68       * @exception StandardException Standard exception policy.
69       **/
70      public void createFinished() throws StandardException;
71  
72      /**
73       *Find an access method that implements an implementation type.
74       *
75       * @exception StandardException Standard exception policy.
76       **/
77      MethodFactory findMethodFactoryByImpl(String   impltype)
78          throws StandardException;
79  
80      /**
81       * Find an access method that implements a format type.
82       **/
83      MethodFactory findMethodFactoryByFormat(UUID format);
84  
85      /**
86       * Get the LockFactory to use with this store.
87       *
88       * @return The lock factory to use with this store.
89       *
90       **/
91      public LockFactory getLockFactory();
92  
93  
94      /**
95       * Return the XAResourceManager associated with this AccessFactory.
96       * <p>
97       * Returns an object which can be used to implement the "offline" 
98       * 2 phase commit interaction between the accessfactory and outstanding
99       * transaction managers taking care of in-doubt transactions.
100      *
101      * @return The XAResourceManager associated with this accessfactory.
102      *
103      * @exception StandardException Standard exception policy.
104      *
105      **/
106     public /* XAResourceManager */ Object   getXAResourceManager()
107         throws StandardException;
108 
109 
110     /**
111      * Is the store read-only.
112      */
113     public boolean isReadOnly();
114 
115 
116 
117     /**************************************************************************
118      * methods that are Property related.
119      **************************************************************************
120      */
121 
122 
123     /**************************************************************************
124      * methods that are transaction related.
125      **************************************************************************
126      */
127 
128     /**
129      * Get a transaction controller with which to manipulate data within
130      * the access manager.  Implicitly creates an access context if one
131      * does not already exist.
132      *
133      * @param cm    The context manager for the current context.
134      *
135      * @exception StandardException Standard exception policy.
136      * @see TransactionController
137      **/
138 
139     TransactionController getTransaction(ContextManager cm)
140         throws StandardException;
141 
142     /**
143      * Get a transaction. If a new transaction is 
144      * implicitly created, give it name transName.
145      *
146      * @param cm            The context manager for the current context.
147      * @param transName     If a new transaction is started, it will be given 
148      *                      this name.  The name is displayed in the 
149      *                      transactiontable VTI.
150      *
151      * @exception StandardException Standard exception policy.
152      *
153      * @see TransactionController
154      * @see AccessFactory#getTransaction
155      */
156     TransactionController getAndNameTransaction(
157     ContextManager  cm, 
158     String            transName)
159         throws StandardException;
160 
161     /**
162      * Return a snap shot of all transactions in the db.
163      * <p>
164      * Take a snap shot of all transactions currently in the database and make
165      * a record of their information.
166      *
167      * @return an array of TransactionInfo, or null if there is 
168      *         no transaction in the database.
169      *
170      **/
171     public TransactionInfo[] getTransactionInfo();
172 
173     /**
174      * Start a global transaction.
175      * <p>
176      * Get a transaction controller with which to manipulate data within
177      * the access manager.  Implicitly creates an access context.
178      * <p>
179      * Must only be called if no other transaction context exists in the
180      * current context manager.  If another transaction exists in the context
181      * an exception will be thrown.
182      * <p>
183      * The (format_id, global_id, branch_id) triplet is meant to come exactly
184      * from a javax.transaction.xa.Xid.  We don't use Xid so that the system
185      * can be delivered on a non-1.2 vm system and not require the javax classes
186      * in the path.
187      * <p>
188      * If the global transaction id given matches an existing in-doubt global
189      * transaction in the current system, then a StandardException will
190      * be thrown with a state of SQLState.STORE_XA_XAER_DUPID.
191      * <p>
192      *
193      * @param cm        The context manager for the current context.
194      * @param format_id the format id part of the Xid - ie. Xid.getFormatId().
195      * @param global_id the global transaction identifier part of XID - ie.
196      *                  Xid.getGlobalTransactionId().
197      * @param branch_id The branch qualifier of the Xid - ie.
198      *                  Xid.getBranchQaulifier()
199      *
200      * @exception StandardException Standard exception policy.
201      * @see TransactionController
202      **/
203     /* XATransactionController */ Object   startXATransaction(
204     ContextManager  cm,
205     int             format_id,
206     byte[]          global_id,
207     byte[]          branch_id)
208         throws StandardException;
209 
210 
211     /**************************************************************************
212      * methods that implement functionality on the 
213      *     org.apache.derby.iapi.db API
214      **************************************************************************
215      */
216 
217     /**
218       * Freeze the database temporarily so a backup can be taken.
219       * <P>Please see Derby on line documentation on backup and restore.
220       *
221       * @exception StandardException Thrown on error
222       */
223     public void freeze() throws StandardException;
224 
225     /**
226       * Unfreeze the database after a backup has been taken.
227       * <P>Please see Derby on line documentation on backup and restore.
228       *
229       * @exception StandardException Thrown on error
230       */
231     public void unfreeze() throws StandardException;
232 
233     /**
234      * Backup the database to backupDir.  
235      * <P>Please see Derby on line documentation on backup and restore.
236      *
237      * @param backupDir the name of the directory where the backup should be
238      *                   stored.
239      * @param wait      if <tt>true</tt>, waits for  all the backup blocking 
240      *                  operations in progress to finish.
241      *
242      * @exception StandardException Thrown on error
243      */
244     public void backup(String   backupDir, boolean wait) 
245         throws StandardException;
246 
247     
248     /**
249      * Backup the database to a backup directory and enable the log archive
250      * mode that will keep the archived log files required for roll-forward
251      * from this version backup.
252      *
253      * @param backupDir                     the directory name where the 
254      *                                      database backup should go.  This 
255      *                                      directory will be created if not it
256      *                                      does not exist.
257      *
258      * @param deleteOnlineArchivedLogFiles  If true deletes online archived log
259      *                                      files that exist before this backup,
260      *                                      delete will occur only after backup
261      *                                      is complete.
262      *
263      * @param wait                          if <tt>true</tt>, waits for all the
264      *                                      backup blocking operations in 
265      *                                      progress to finish.
266      *
267      * @exception StandardException Thrown on error
268      */
269     public void backupAndEnableLogArchiveMode(
270     String    backupDir, 
271     boolean deleteOnlineArchivedLogFiles,
272     boolean wait)   
273         throws StandardException;
274     
275     /**
276      * disables the log archival process, i.e No old log files
277      * will be kept around for a roll-forward recovery.
278      *
279      * @param deleteOnlineArchivedLogFiles  If true deletes all online archived
280      *                                      log files that exist before this 
281      *                                      call immediately; Only restore that
282      *                                      can be performed after disabling log
283      *                                      archive mode is version recovery.
284      *
285      * @exception StandardException Thrown on error
286      */
287     public void disableLogArchiveMode(boolean deleteOnlineArchivedLogFiles)
288         throws StandardException;
289 
290 
291     /**
292      * Checkpoints the database, that is, flushes all dirty data to disk.
293      * Records a checkpoint in the transaction log, if there is a log.
294      *
295      * @exception StandardException Thrown on error
296      */
297     public void checkpoint() throws StandardException;
298 
299     /*
300      *Wait until the thread handling the post commit work
301      *finihes the work assigned to it.
302      */
303     public void waitForPostCommitToFinishWork();
304 
305 }
306
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags