KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > store > raw > ContainerHandle


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.raw.ContainerHandle
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.raw;
23
24 import org.apache.derby.iapi.store.access.SpaceInfo;
25 import org.apache.derby.iapi.error.StandardException;
26
27 import java.util.Properties JavaDoc;
28
29 /**
30     A Container contains a contigious address space of pages, the pages
31     start at page number Container.FIRST_PAGE_NUMBER and are numbered sequentially.
32     
33     The page size is set at addContainer() time.
34
35
36     RESOLVE: this style of coding is not currently enforced
37     If the caller calls getPage (or one of its variants) more than once on the
38     same page, the caller must call unlatch a corresponding number of times in
39     order to ensure that the page is latched. For example:
40     <p>
41     <blockquote><pre>
42     Container c;
43     Page p1 = c.getPage(Container.FIRST_PAGE_NUMBER);
44     Page p2 = c.getPage(Container.FIRST_PAGE_NUMBER);
45     p1.unlatch(); -- Page is still latched.
46     p2.unlatch(); -- Page is now unlatched.
47     </pre></blockquote>
48
49     <p>
50     There is no restriction on the order in which latching and unlatching is
51     done. In the example, p1 could have been unlatched after p2 with no ill
52     effects.
53
54     <P> <B>Open container modes</B>
55     ContainerHandle.MODE are used to open or create the container.
56     Unlike TableProperties, MODEs are not permanantely associated with the
57     container, it is effective only for the lifetime of the containerHandle
58     itself.
59     <BR>A container may use any of these mode flags when it is opened.
60     <UL>
61     <LI>MODE_READONLY - Open the container in read only mode.
62     <LI>MODE_FORUPDATE - Open the container in update mode, if the underlying
63     storage does not allow updates
64     then the container will be opned in read only mode.
65     <LI>MODE_UNLOGGED - If Unset, any changes to the container are logged.
66     If set, any user changes to the container are unlogged. It is guaranteed
67     at commit time that all changes made during the transaction will have been
68     flushed to disk. Using this mode automatically opens the container in
69     container locking, isolation 3 level. The state of the container following
70     an abort or any type of rollback is unspecified.
71     <LI>MODE_CREATE_UNLOGGED - If set, not only are user changes to the
72     container are unlogged, page allocations are also unlogged. This MODE is
73     only useful for container is created in the same statement and no change on
74     the container (other than the create) is ever logged. The difference
75     between MODE_UNLOGGED and MODE_CREATE_UNLOGGED is that page allocation is
76     also unlogged and commit of nested transaction will not cause the container
77     to be forced from the cache. Unlike MODE_UNLOGGED, MODE_CREATE_UNLOGGED
78     does not force the cache. It is up to the client of raw store to force the
79     cache at the appropriate time - this allows a statement to create and open
80     the container serveral times for bulk loading without logging or doing any
81     synchronous I/O.
82     <LI>MODE_LOCK_NOWAIT - if set, then don't wait for the container lock, else
83     wait for the container lock. This flag only dictates whether the lock
84     should be waited for or not. After the container is successfully opened,
85     whether this bit is set or not has no effect on the container handle.
86     </UL>
87     If neither or both of the {MODE_READONLY, MODE_FORUPDATE} modes are
88     specified then the behaviour of the container is unspecified.
89     <BR>
90     MODE_UNLOGGED must be set for MODE_CREATE_UNLOGGED to be set.
91     <P>
92     <B>Temporary Containers</B><BR>
93     If when creating a container the segment used is
94     ContainerHandle.TEMPORARY_SEGMENT then the container is a temporary
95     container. Temporary containers are not logged or locked and do not live
96     across re-boots of the system. In addition any abort or rollback including
97     rollbacks to savepoints truncate the container if it has been opened for
98     update since the last commit or abort. Temporary containers are private
99     to a transaction and must only be used a single thread within the
100     transaction at any time, these restrictions are not currently enforced.
101     <BR>
102     When opening a temporary container for update access these additional mode
103     flags may be used
104     <UL>
105     <LI> MODE_TRUNCATE_ON_COMMIT - At commit/abort time container is truncated.
106     <LI> MODE_DROP_ON_COMMIT - At commit/abort time the container is dropped.
107     <LI> MODE_TEMP_IS_KEPT - At commit/abort time the container is kept around.
108     </UL>
109     If a temporary container is opened multiple times in the same transaction
110     with different modes then the most severe mode is used, ie. none &lt;
111     truncate on commit &lt; drop on commit.
112     The MODE_UNLOGGED, MODE_CREAT_UNLOGGED flags are ignored when opening a
113     temporary container, not logged is always assumed. */
114
115 public interface ContainerHandle
116 {
117
118     /**
119         Used in add container.
120     */
121     public static final int DEFAULT_PAGESIZE = -1;
122
123     public static final int DEFAULT_SPARESPACE = -1;
124
125     public static final int DEFAULT_ASSIGN_ID = 0;
126
127     /**
128         See comments above for these modes.
129      */
130     public static final int MODE_DEFAULT = 0x00000000;
131     public static final int MODE_UNLOGGED = 0x00000001;
132     public static final int MODE_CREATE_UNLOGGED = 0x00000002;
133     public static final int MODE_FORUPDATE = 0x00000004;
134     public static final int MODE_READONLY = 0x00000008;
135     public static final int MODE_TRUNCATE_ON_COMMIT = 0x00000010;
136     public static final int MODE_DROP_ON_COMMIT = 0x00000020;
137     public static final int MODE_OPEN_FOR_LOCK_ONLY = 0x00000040;
138     public static final int MODE_LOCK_NOWAIT = 0x00000080;
139     public static final int MODE_TRUNCATE_ON_ROLLBACK = 0x00000100; // internal raw store
140 public static final int MODE_FLUSH_ON_COMMIT = 0x00000200; // internal raw store
141 public static final int MODE_NO_ACTIONS_ON_COMMIT = 0x00000400; // internal raw store
142 public static final int MODE_TEMP_IS_KEPT = 0x00000800; // internal raw store
143
144     public static final int MODE_USE_UPDATE_LOCKS = 0x00001000; // external access
145 public static final int MODE_SECONDARY_LOCKED = 0x00002000; // external access
146 public static final int MODE_BASEROW_INSERT_LOCKED = 0x00004000; // external access
147
148     public static final int TEMPORARY_SEGMENT = -1;
149
150
151     /**
152         The first valid page number
153     */
154     public static final long FIRST_PAGE_NUMBER = 1;
155     
156     /**
157         A page number that is guaranteed to be invalid.
158     */
159     public static final long INVALID_PAGE_NUMBER = -1;
160
161     /**
162         Return my identifier.
163     */
164     public ContainerKey getId();
165
166     /**
167         Return my unique identifier, this identifier will be unique to each
168         instance of an open container handle. This id is used by the locking
169         system to group locks to an open container handle.
170     */
171     public Object JavaDoc getUniqueId();
172
173     /**
174      * Is the container opened for read only or update?
175      *
176      * @return true if container is opened for read only, else false.
177      **/
178     boolean isReadOnly();
179
180     /**
181         Add an empty page to the container and obtain exclusive access to it.
182         <P>
183         Note that the added page may not be the last page in the Container.
184
185         Once the Page is no longer required the Page's unlatch() method must
186         be called.
187
188         @return a reference to the page that was added.
189
190         @see Page#unlatch
191
192         @exception StandardException Standard Cloudscape error policy
193         @exception StandardException If a page could not be allocated.
194     */
195     public Page addPage() throws StandardException;
196
197
198     /**
199         Release free space to the OS.
200         <P>
201         As is possible release any free space to the operating system. This
202         will usually mean releasing any free pages located at the end of the
203         file using the java truncate() interface.
204
205         @exception StandardException Standard Cloudscape error policy
206     */
207     public void compressContainer() throws StandardException;
208
209     /**
210      * Get the reusable recordId sequence number.
211      * @return version sequence number
212      * @exception StandardException Standard Derby error policy
213      */
214     public long getReusableRecordIdSequenceNumber() throws StandardException;
215
216     /**
217         Add an empty page to the container and obtain exclusive access to it.
218         <P>
219         If flag == ADD_PAGE_DEFAULT, this call is identical to addPage().
220         <BR>
221         If flag == ADD_PAGE_BULK, then this call signifies to the container that
222         this addPage is part of a large number of additional pages and it is
223         desirable to do whatever possible to facilitate adding many subsequent pages.
224         The actual container implementation will decide whether or not to heed
225         this hint and what to do about it.
226
227         @return a reference to the page that was added.
228
229         @see Page#unlatch
230
231         @exception StandardException Standard Cloudscape error policy
232         @exception StandardException If a page could not be allocated.
233
234     */
235     public Page addPage(int flag) throws StandardException;
236     public static final int ADD_PAGE_DEFAULT = 0x1;
237     public static final int ADD_PAGE_BULK = 0x2;
238
239
240     /**
241         Try to preallocate numPage new pages if possible.
242      */
243     public void preAllocate(int numPage);
244
245
246     /**
247         Remove this page from the container and unlatch the page. <B>Caller
248         should commit or abort this transaction ASAP because failure to do so
249         will slow down page allocation of this container. </B>
250
251         <BR>The page to be removed must be latched and gotten (or added) by
252         this ContainerHandle. The page should not be used again after this
253         call as if it has been unlatched. If the call to removePage is
254         successful, this page is invalid should not be gotten again with
255         getPage.
256
257         <BR>RemovePage will guarantee to unlatch the page even if a
258         StandardException is thrown.
259
260         <P>
261         <B>Locking Policy</B>
262         <BR>
263         The page will not be freed until the transaction that removed the page
264         commits. A special RecordHandle.DEALLOC_PROTECTION_HANDLE lock will be
265         gotten for the transaction and which is used to prevent the page from
266         being freed. This lock will be held regardless of the default locking
267         policy of the transaction that called removedPage.
268
269         @see LockingPolicy
270         @see RecordHandle
271
272         @exception StandardException Standard Cloudscape error policy
273     */
274     public void removePage(Page page) throws StandardException;
275
276
277     /**
278         Obtain exclusive access to the page with the given page number.
279         
280         Once the Page is no longer required the Page's unlatch() method must
281         be called.
282
283         <P>
284         The Page object is guaranteed to remain in-memory and exclusive to the
285         caller until its unlatch() method is called.
286
287         @return the required Page or null if the page does not exist or is not
288         valid (i.e, it has been deallocated or freed or never initialized)
289         Note that an overflow page will be returned since it is a valid page.
290
291         @exception StandardException Standard Cloudscape error policy
292     */
293     public Page getPage(long pageNumber)
294         throws StandardException;
295
296     /**
297         Identical to getPage but returns null immediately if the desired page
298         is already latched by another Container.
299
300         @return the required Page or null if the page does not exist or the page
301         is already latched.
302
303         @exception StandardException Standard Cloudscape error policy
304
305     */
306     public Page getPageNoWait(long pageNumber) throws StandardException;
307
308     /**
309         Obtain exclusive access to the page with the given page number.
310
311         Will only return a valid, non-overflow user page - so can be used by
312         routines in post commit to get pages to attempt deleted row space
313         reclamation. If for some reason a request is made for an overflow
314         page a null will be returned.
315
316         Once the Page is no longer required the Page's unlatch() method must
317         be called.
318
319         <P>
320         The Page object is guaranteed to remain in-memory and exclusive to the
321         caller until its unlatch() method is called.
322
323         @return the required Page or null if the page does not exist or is not
324         valid (i.e, it has been deallocated, freed, never initialized, or is
325         an allocation page or overflow page)
326
327         @exception StandardException Standard Cloudscape error policy
328     */
329     public Page getUserPageNoWait(long pageNumber) throws StandardException;
330     /**
331         Obtain exclusive access to the page with the given page number.
332
333         Will only return a valid, non-overflow user page - so can be used by
334         routines in post commit to get pages to attempt deleted row space
335         reclamation. If for some reason a request is made for an overflow
336         page a null will be returned.
337
338         Once the Page is no longer required the Page's unlatch() method must
339         be called.
340
341         <P>
342         The Page object is guaranteed to remain in-memory and exclusive to the
343         caller until its unlatch() method is called.
344
345         @return the required Page or null if the page does not exist or is not
346         valid (i.e, it has been deallocated, freed, never initialized, or is
347         an allocation page or overflow page)
348
349         @exception StandardException Standard Cloudscape error policy
350     */
351     public Page getUserPageWait(long pageNumber) throws StandardException;
352
353     /**
354         Obtain exclusive access to the current first page of the container.
355         Only a valid, non overflow page will be returned.
356         Pages in the container are ordered in an internally defined ordering.
357         <P>
358         Note that once this method returns this page may no longer be the
359         first page of the container. I.e, other threads may allocate pages
360         prior to this page number while this page is latched. It is up to
361         the caller of this routine to synchronize this call with addPage to
362         assure that this is the first page.
363         <BR>
364         As long as the client provide the necessary lock to ensure
365         that no addPage is called, then this page is guaranteed to be the
366         first page of the container in some internally defined ordering of
367         the pages.
368
369         @return latched page or null if there is no page in the container
370         @exception StandardException Standard Cloudscape error policy
371
372         @see ContainerHandle#getPage
373     */
374     public Page getFirstPage() throws StandardException;
375
376     /**
377         Obtain exclusive access to the next valid page of the given page number
378         in the container. Only a valid, non overflow page will be returned.
379         Pages in the container are ordered in an internally defined ordering.
380         <P>
381         Note that once this method returns this page may no longer be the
382         next page of the container. I.e, other threads may allocate pages
383         prior to this page number while this page is latched. It is up to
384         the caller of this routine to synchronize this call with addPage to
385         assure that this is the first page.
386         <BR>
387         As long as the client provide the necessary lock to ensure
388         that no addPage is called, then this page is guaranteed to be the
389         next page of the container in some internally defined ordering of
390         the pages.
391         <BR>
392         If no pages are added or removed, then an iteration such as:
393         <PRE>
394         for (Page p = containerHandle.getFirstPage();
395              p != null;
396              p = containerHandle.getNextPage(p.getPageNumber()))
397         <PRE>
398         will guarentee to iterate thru and latched all the valid pages
399         in the container
400
401         @param prevNum the pagenumber of the page previous to the page
402         that is to be gotten. The page which correspond to prevNum
403         may or may not be latched by the caller, but it must be gotten
404         via a page which was (or currently still is) latched, and the page
405         number must be gotten while the container must not have been closed
406         or dropped or removed in the interim.
407
408         In other words, if the user manufactures a page number, or remembers
409         the page number from a previous session or a previous openContainer,
410         then the behavior of this routine is undefined.
411
412         @return latched page or null if there is no next page in the container
413         @exception StandardException Standard Cloudscape error policy
414
415         @see ContainerHandle#getPage
416     */
417     public Page getNextPage(long prevNum) throws StandardException;
418
419
420     /**
421         Get a page for insert. If RawStore thinks it knows where a potentially
422         suitable page is for insert, it will return it. If RawStore doesn't
423         know where a suitable page for insert is, or if there are no allocated
424         page, then null is returned. If a page is returned, it will be a
425         valid, non-overflow page. A potentially suitable page is one which
426         has enough space for a minium sized record.
427
428         @return a valid, non-overflow page. Or null if RawStore doesn't know
429         where to find a good valid, non-overflow page.
430
431         @param flag a GET_PAGE_* flag.
432
433         @exception StandardException Standard Cloudscape error policy
434     */
435     public Page getPageForInsert(int flag)
436          throws StandardException;
437
438     public Page getPageForCompress(
439     int flag,
440     long pageno)
441          throws StandardException;
442
443     // Try to get a page that is unfilled, 'unfill-ness' is defined by the
444 // page. Since unfill-ness is defined by the page, the only thing RawStore
445 // guarentees about the page is that it has space for a a minimum sized
446 // record.
447 //
448 // If this bit is not set, then getPageForInsert will get the page that was
449 // last gotten, provided it has space for a minimum sized record.
450 //
451 // If for whatever reasons RawStore is unable to come up with such a page,
452 // null will be returned.
453 public static final int GET_PAGE_UNFILLED = 0x1;
454
455
456     /**
457      * Request the system properties associated with a container.
458      * <p>
459      * Request the value of properties that are associated with a table. The
460      * following properties can be requested:
461      * derby.storage.pageSize
462      * derby.storage.pageReservedSpace
463      * derby.storage.minimumRecordSize
464      * <p>
465      * To get the value of a particular property add it to the property list,
466      * and on return the value of the property will be set to it's current
467      * value. For example:
468      *
469      * get_prop(ConglomerateController cc)
470      * {
471      * Properties prop = new Properties();
472      * prop.put("derby.storage.pageSize", "");
473      * cc.getTableProperties(prop);
474      *
475      * System.out.println(
476      * "table's page size = " +
477      * prop.getProperty("derby.storage.pageSize");
478      * }
479      *
480      * @param prop Property list to fill in.
481      *
482      * @exception StandardException Standard exception policy.
483      **/
484     void getContainerProperties(Properties JavaDoc prop)
485         throws StandardException;
486
487     /**
488         Close me. After using this method the caller must throw away the
489         reference to the Container object, e.g.
490         <PRE>
491             ref.close();
492             ref = null;
493         </PRE>
494         <BR>
495         The container will be closed automatically at the commit or abort
496         of the transaction if this method is not called explictly.
497         <BR>
498         Any pages that were obtained using me and have not been released
499         using Page's unlatch method are released, and references to them must be
500         thrown away.
501
502
503         @see Page#unlatch
504         @see Page#fetch
505     */
506     public void close();
507
508     /**
509         Cost estimation
510     */
511
512     /**
513         Get the total estimated number of rows in the container, not including
514         overflow rows. This number is a rough estimate and may be grossly off.
515
516         @param flag different flavors of row count (reserved for future use)
517         @exception StandardException Standard Cloudscape error policy
518      */
519     public long getEstimatedRowCount(int flag) throws StandardException;
520
521     /**
522         Set the total estimated number of rows in the container. Often, after
523         a scan, the client of RawStore has a much better estimate of the number
524         of rows in the container then what RawStore has. Use this better
525         number for future reference.
526         <BR>
527         It is OK for a ReadOnly ContainerHandle to set the estimated row count.
528
529         @param count the estimated number of rows in the container.
530         @param flag different flavors of row count (reserved for future use)
531
532         @exception StandardException Standard Cloudscape error policy
533      */
534     public void setEstimatedRowCount(long count, int flag) throws StandardException;
535
536     /**
537         Get the total estimated number of allocated (not freed, not
538         deallocated) user pages in the container, including overflow pages.
539         this number is a rough estimate and may be grossly off.
540
541         @param flag different flavors of page count (reserved for future use)
542
543         @exception StandardException Standard Cloudscape error policy
544      */
545     public long getEstimatedPageCount(int flag) throws StandardException;
546
547
548     /**
549         Flush all dirty pages of the container to disk. Used mainly for
550         UNLOGGED or CREATE_UNLOGGED operation.
551
552         @exception StandardException Standard Cloudscape error policy
553     */
554     public void flushContainer() throws StandardException;
555
556     /**
557         Return the locking policy for this open container.
558     */
559     public LockingPolicy getLockingPolicy();
560
561     /**
562         Set the locking policy for this open container
563     */
564     public void setLockingPolicy(LockingPolicy newLockingPolicy);
565
566     /**
567         Return a record handle that is initialized to the given segment id,
568         container id, page number and record id.
569
570         @exception StandardException Standard cloudscape exception policy.
571
572         @param pageNumber the page number of the RecordHandle.
573         @param recordId the record id of the RecordHandle.
574
575         @see RecordHandle
576     */
577     public RecordHandle makeRecordHandle(long pageNumber, int recordId)
578          throws StandardException;
579
580
581     /**
582         This record probably has shrunk considerably. Free its reserved space
583         or compact it.
584
585         @param record The record handle, the record must have been locked execlusively already.
586         @exception StandardException Standard cloudscape exception policy.
587     */
588     public void compactRecord(RecordHandle record) throws StandardException;
589
590     /**
591         Return true if this containerHandle refers to a temporary container.
592         @exception StandardException Standard cloudscape exception policy.
593      */
594     public boolean isTemporaryContainer() throws StandardException;
595
596     /**
597     Get information about space used by the container.
598     **/
599     public SpaceInfo getSpaceInfo() throws StandardException;
600
601     /**
602        Backup the container to the specified path.
603        @exception StandardException Standard Cloudscape error policy
604     */
605     public void backupContainer(String JavaDoc backupContainerPath) throws StandardException;
606 }
607
Popular Tags