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


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.raw.Page
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.services.io.FormatableBitSet;
25
26 import org.apache.derby.iapi.error.StandardException;
27
28 import org.apache.derby.iapi.store.access.conglomerate.LogicalUndo;
29
30 import org.apache.derby.iapi.store.access.Qualifier;
31
32 import org.apache.derby.iapi.types.DataValueDescriptor;
33
34
35 /**
36     A Page contains an ordered set of records which are the stored form of rows.
37     A record is a stream of bytes created from a row array. The record
38     contains one or more fields, fields have a one to one correlation with
39     the DataValueDescriptor's contained within a row array.
40   <P>
41     A Page represents <B>exclusive</B> access to a data page within a container.
42     Exclusive access is released by calling the unlatch() method, once that
43     occurs the caller must no longer use the Page reference.
44     <P>
45     Several of the methods in Page take a RecordHandle as an argument.
46     RecordHandles are obtained from a Page, while holding exclusive access of
47     Page or a from a previous exclusive access of a Page representing the same
48     data page.
49     All RecordHandle's used as arguments to methods (with the exception of
50     recordExists()) must be valid for the current state of the page. If they
51     are not valid then the method will throw an exception. A caller can ensure
52     that a record handle is valid by:
53     <UL>
54     <LI> Obtaining the handle during this exclusive access of this page
55     <LI> Checking the record still exists with the method recordExists()
56     <LI> Not using a handle after a delete().
57     </UL>
58     <P>
59     Several of the methods in Page take a slot number as an argument. A slot
60     always correspond to a record, which may be deleted or undeleted.
61
62     <BR>
63     MT - Latched - In general every method requires the page to be latched.
64
65   <P>
66   <B>Latching</B>
67   <P>
68   All page methods which are not valid for a latched page throw an
69   exception if the page is not latched. [@exception clauses on all
70   the methods should be updated to reflect this].
71
72   <P>
73   <B>Aux Objects</B>
74   <BR>
75   The page cache will manage a client object along with the page as long
76   as it remains in cache. This object is called the "aux object". The
77   aux object is associated with the page with setAuxObject(), and can be
78   retreived later with getAuxObject(). The aux object will remain valid
79   as long as the page is latched, but callers cannot assume that an aux
80   object will ever stick around once the page is unlatched. However, the
81   page manager promises to call pageBeingEvicted() once before clearing
82   the aux reference from the page.
83
84     @see Object
85     @see ContainerHandle
86     @see RecordHandle
87     @see AuxObject
88 */
89
90 public interface Page
91 {
92
93     /**************************************************************************
94      * Constants of the class
95      **************************************************************************
96      */
97
98     /**
99      * The slot number of the first slot. This is guaranteed to be zero.
100      **/
101     public static final int FIRST_SLOT_NUMBER = 0;
102     
103     /**
104      * A slot number guaranteed to be invalid.
105      **/
106     public static final int INVALID_SLOT_NUMBER = -1;
107     
108     /**
109      * Return the page number of this page.
110      * <p>
111      * Page numbers are unique within a container and start at
112      * ContainerHandle.FIRST_PAGE_NUMBER and increment by 1 regardless of the
113      * page size.
114      * <p>
115      *
116      * <BR> MT - Latched
117      *
118      * @see ContainerHandle
119      *
120      * @return The page number of this page.
121      **/
122     public long getPageNumber();
123
124     /**************************************************************************
125      * Public Methods of This class: record handle interface.
126      * the following interfaces to page use the record Id or record handle
127      * (rather than the slot interface).
128      **************************************************************************
129      */
130
131     /**
132      * Return an invalid record handle.
133      * <p>
134      *
135      * @return an invalid record handle.
136      *
137      * @exception StandardException Standard exception policy.
138      **/
139     public RecordHandle getInvalidRecordHandle();
140
141     /**
142      * Return a record handle for the given constant record id.
143      * <p>
144      * Return a record handle that doesn't represent a record but rather has
145      * a special meaning. Used for special cases like creating a key
146      * specific to the page, but not specific to a row on the page.
147      * <p>
148      * See RecordHandle interface for a list of "special record handles."
149      *
150      * @see RecordHandle
151      *
152      * @return The created record handle.
153      *
154      * @param recordHandleConstant the special recordId
155      *
156      * @exception StandardException if input is not a special record identifier.
157      **/
158     public RecordHandle makeRecordHandle(int recordHandleConstant)
159          throws StandardException;
160
161     /**
162      * Get a record handle from a previously stored record id.
163      * <p>
164      * Get a record handle from a previously stored record identifier that was
165      * obtained from a RecordHandle.
166      * <p>
167      * <BR> MT - Latched
168      *
169      * @return A valid record handle or null if the record no longer exists.
170      *
171      * @param recordId previously stored recordId.
172      *
173      * @see RecordHandle#getId
174      **/
175     RecordHandle getRecordHandle(int recordId);
176
177     /**
178      * does the record still exist on the page?
179      * <p>
180      * If "ignoreDelete" is true and the record handle represents a record on
181      * the page (either marked deleted or not) return true. If "ignoreDelete"
182      * is false return true if the record handle represents a record on the
183      * page and the record is not marked as deleted. Return false otherwise.
184      *
185      * <BR> MT - Latched
186      *
187      * @return boolean indicating if the record still exists on the page.
188      *
189      * @param handle handle of the record to look for.
190      * @param ignoreDelete if true, then routine will return true even if the
191      * row is marked deleted.
192      *
193      * @exception StandardException Standard exception policy.
194      **/
195     boolean recordExists(RecordHandle handle, boolean ignoreDelete)
196          throws StandardException;
197
198     /**
199      * Fetch and lock a non-deleted record.
200      * <p>
201      * Lock and fetch a non-deleted record identified by a RecordHandle.
202      * Reads data from the page into row.
203      * <P>
204      * <B>Locking Policy</B>
205      * <BR>
206      * Calls the lockRecordForRead() method of the LockingPolicy object
207      * passed to the openContainer() call before the record is accessed.
208      * <BR>
209      * The page latch may be released and re-latched within this method.
210      * This will occur if the record lock has to be waited for.
211      *
212      * @param handle Handle to record.
213      * @param row Row to be filled in with data from the record.
214      * @param validColumns a bit map of which columns in the row is to be
215      * fetched. ValidColumns will not be changed by
216      * RawStore.
217      * @param forUpdate true if the intention is to update this record,
218      * false otherwise.
219      *
220      * @return A handle to the record, null if the record has been deleted.
221      *
222      * @exception StandardException Standard Cloudscape error policy,
223      * a statemente level exception is thrown if
224      * the record handle does not match a record
225      * on the page.
226      *
227      * @see Page#delete
228      * @see LockingPolicy
229      **/
230     RecordHandle fetch(
231     RecordHandle handle,
232     Object [] row,
233     FormatableBitSet validColumns,
234     boolean forUpdate)
235         throws StandardException;
236
237     /**
238      * Is it likely that an insert will fit on this page?
239      * <p>
240      * Return true if there is a good chance an insert will fit on this page,
241      * false otherwise. If this returns true then an insert may still fail by
242      * throwing an exception or by returning null, see insertAtSlot for details.
243      * It is very probable that this call is much faster than the version that
244      * takes a row. In situations where it is expected that the
245      * majority of times a row will fit on a page this method should be used
246      * and the null return handled from insert/insertAtSlot.
247      *
248      * <BR>
249      * MT - latched
250      *
251      * @return true if it is likely an insert will fit on the page.
252      *
253      * @exception StandardException Standard exception policy.
254      **/
255     boolean spaceForInsert()
256         throws StandardException;
257
258     /**
259      * will insert of this row fit on this page?
260      * <p>
261      * Return true if this record is guaranteed to be inserted successfully
262      * using insert() or insertAtSlot(). This guarantee is only valid if the
263      * following conditions are fulfilled before an insert is called with t
264      * his row.
265      * <UL>
266      * <LI> The page is not unlatched
267      * <LI> The page is not modified in any way, ie. no updates or other inserts
268      * <LI> The row is not modified in such a way that would change its
269      * storage size
270      * </UL>
271      *
272      * <BR>
273      * MT - latched
274      *
275      * @return true if insert of this row will fit on this page.
276      *
277      * @param row The row to check for insert.
278      * @param validColumns bit map to interpret valid columns in row.
279      * @param overflowThreshold The percentage of the page to use for the
280      * insert. 100 means use 100% of the page,
281      * 50 means use 50% of page (ie. make sure
282      * 2 rows fit per page).
283      *
284      * @exception StandardException Standard exception policy.
285      **/
286     boolean spaceForInsert(
287     Object [] row,
288     FormatableBitSet validColumns,
289     int overflowThreshold)
290         throws StandardException;
291
292     /**
293      * Insert a record anywhere on the page.
294      * <P>
295      *
296      * <B>Locking Policy</B>
297      * <BR>
298      * Calls the lockRecordForWrite() method of the LockingPolicy object
299      * passed to the openContainer() call before the record is inserted.
300      * <BR>
301      * MT - latched
302      *
303      * @param row The row version of the data
304      * @param validColumns a bit map of which columns in the row is valid.
305      * ValidColumns will not be changed by RawStore.
306      * @param insertFlag see values for insertFlag below.
307      *
308      * @return A RecordHandle representing the new record.
309      *
310      * @exception StandardException Standard Cloudscape error policy
311      * @exception StandardException The container was not opened in update mode.
312      * @exception StandardException Row cannot fit on the page or row is null.
313      **/
314     RecordHandle insert(
315     Object [] row,
316     FormatableBitSet validColumns,
317     byte insertFlag,
318     int overflowThreshold)
319         throws StandardException;
320
321     /**
322      * Update the record identified by the record handle.
323      * <p>
324      * Update the record, the new column values are found in row[] and if
325      * validColumns is not-null, only use the columns indicated as valid in
326      * the bit set.
327      * <p>
328      * <BR>
329      * The page latch may be released and re-latched within this method.
330      * This will occur if the record lock has to be waited for.
331      *
332      * @param handle the record handle
333      * @param row The row version of the data
334      * @param validColumns A bit map of which columns in the row is valid.
335      * ValidColumns will not be changed by RawStore.
336      *
337      * @return true if the record is updated.
338      * False if it is not because the record is already deleted.
339      *
340      * @exception StandardException Standard Cloudscape error policy
341      * @exception StandardException The container was not opened in update mode.
342      * @exception StandardException If the record handle does not match
343      * a record on the page.
344      *
345      * @see Page#updateAtSlot
346      *
347      * @exception StandardException Standard exception policy.
348      **/
349     boolean update(
350     RecordHandle handle,
351     Object [] row,
352     FormatableBitSet validColumns)
353         throws StandardException;
354
355     /**
356      * Mark the record identified by position as deleted.
357      * <p>
358      * Mark the record identified by position as deleted. The record may be
359      * undeleted sometime later using undelete() by any transaction that sees
360      * the record.
361      * <p>
362      * <B>Locking Policy</B>
363      * <P>
364      * Calls the lockRecordForWrite() method of the LockingPolicy object
365      * passed to the openContainer() call before the record is deleted.
366      *
367      * <BR>
368      * The page latch may be released and re-latched within this method.
369      * This will occur if the record lock has to be waited for.
370      *
371      * @param handle record Handle to record
372      * @param undo if logical undo may be necessary, a function pointer to
373      * the access code where the logical undo logic resides.
374      * Null if logical undo is not necessary.
375      *
376      * @return true if the record was updated.
377      * False if it wasn't because it is already deleted.
378      *
379      * @exception StandardException Standard Cloudscape error policy
380      * @exception StandardException The container was not opened in update mode.
381      * @exception StandardException If the record handle does not match
382      * a record on the page.
383      *
384      * @see Page#deleteAtSlot
385      * @see LockingPolicy
386      **/
387     public boolean delete(
388     RecordHandle handle,
389     LogicalUndo undo)
390         throws StandardException;
391
392     /**
393      * Move record to a page toward the beginning of the file.
394      * <p>
395      * As part of compressing the table records need to be moved from the
396      * end of the file toward the beginning of the file. Only the
397      * contiguous set of free pages at the very end of the file can
398      * be given back to the OS. This call is used to purge the row from
399      * the current page, insert it into a previous page, and return the
400      * new row location
401      * Mark the record identified by position as deleted. The record may be
402      * undeleted sometime later using undelete() by any transaction that sees
403      * the record.
404      * <p>
405      * The interface is optimized to work on a number of rows at a time,
406      * optimally processing all rows on the page at once. The call will
407      * process either all rows on the page, or the number of slots in the
408      * input arrays - whichever is smaller.
409      * <B>Locking Policy</B>
410      * <P>
411      * MUST be called with table locked, not locks are requested. Because
412      * it is called with table locks the call will go ahead and purge any
413      * row which is marked deleted. It will also use purge rather than
414      * delete to remove the old row after it moves it to a new page. This
415      * is ok since the table lock insures that no other transaction will
416      * use space on the table before this transaction commits.
417      *
418      * <BR>
419      * A page latch on the new page will be requested and released.
420      *
421      * @param slot Slot of row to move.
422      * @param row A template to read the current row into as part
423      * of moving it.
424      * @param old_handle An array to be filled in by the call with the
425      * old handles of all rows moved.
426      * @param new_handle An array to be filled in by the call with the
427      * new handles of all rows moved.
428      *
429      * @return the number of rows processed.
430      *
431      * @exception StandardException Standard Cloudscape error policy
432      *
433      * @see LockingPolicy
434      **/
435     public int moveRecordForCompressAtSlot(
436     int slot,
437     Object [] row,
438     RecordHandle[] old_handle,
439     RecordHandle[] new_handle)
440         throws StandardException;
441
442     /**
443      * Fetch the number of fields in a record.
444      * <p>
445      * <B>Locking Policy</B>
446      * <P>
447      * No locks are obtained.
448      *
449      * <BR>
450      * MT - latched
451      *
452      * @param handle record handle to deleted or non-deleted record
453      *
454      * @return the number of fields in the record
455      *
456      * @exception StandardException Standard Cloudscape error policy, a
457      * statement level exception is thrown if the
458      * record handle does not match a record on
459      * the page.
460      **/
461     public int fetchNumFields(RecordHandle handle)
462          throws StandardException;
463
464     /**************************************************************************
465      * Public Methods of This class: slot interface.
466      * the following interfaces to page use the slot number
467      * (rather than the record handle interface).
468      **************************************************************************
469      */
470
471
472     /**
473      * Get the slot number.
474      * <p>
475      * Get the slot number of a record on a latched page using its record
476      * handle.
477      *
478      * <P><B>Note</B>
479      * The slot number is only good for as long as the page is latched.
480      *
481      * <BR>
482      * MT - latched
483      *
484      * @param handle the record handle
485      *
486      * @return the slot number
487      *
488      * @exception StandardException Standard Cloudscape error policy
489      **/
490     int getSlotNumber(RecordHandle handle)
491         throws StandardException;
492
493     /**
494      * Get the record handle of row at slot.
495      * <p>
496      * Get the record handle of a record on a latched page using its slot
497      * number.
498      *
499      * <BR>
500      * MT - latched
501      *
502      * @param slot the slot number
503      *
504      * @return the record handle.
505      *
506      * @exception StandardException Standard Cloudscape error policy
507      **/
508     RecordHandle getRecordHandleAtSlot(int slot)
509         throws StandardException;
510
511     /**
512      * Find slot for record with an id greater than the passed in identifier.
513      * <p>
514      * Find the slot for the first record on the page with an id greater than
515      * the passed in identifier.
516      *
517      * <BR>
518      * Returns the slot of the first record on the page with an id greater than
519      * the one passed in. Usefulness of this functionality depends on the
520      * client's use of the raw store interfaces. If all "new" records are
521      * always inserted at the end of the page, and the raw store continues to
522      * guarantee that all record id's will be allocated in increasing order on
523      * a given page (assuming a PAGE_REUSABLE_RECORD_ID container), then a page
524      * is always sorted in record id order. For instance current heap tables
525      * function this way. If the client ever inserts at a particular slot
526      * number, rather than at the "end" then the record id's will not be sorted.
527      * <BR>
528      * In the case where all record id's are always sorted on a page, then this
529      * routine can be used by scan's which "lose" their position because the
530      * row they have as a position was purged. They can reposition their scan
531      * at the "next" row after the row that is now missing from the table.
532      * <BR>
533      * This method returns the record regardless of its deleted status.
534      * <BR>
535      * MT - latched
536      *
537      * @param handle record handle to find the next higher id.
538      *
539      * @return record id of the first record on the page with a record id
540      * higher than the one passed in. If no such record exists,
541      * -1 is returned.
542      *
543      * @exception StandardException Standard exception policy.
544      **/
545     int getNextSlotNumber(RecordHandle handle)
546         throws StandardException;
547
548     /**
549      * Insert a record at the specified slot.
550      * <p>
551      * All records that occupy FIRST_SLOT_NUMBER to (slot - 1) are not moved.
552      * <BR>
553      * All records that occupy slot to (recordCount() - 1) are moved up one
554      * slot.
555      * <BR>
556      * The new record is inserted at the specified slot. <BR>
557      * If slot == FIRST_SLOT_NUMBER, then the new record will be inserted at
558      * the first slot. <BR>
559      * If slot == recordCount(), then the record is inserted in a new slot, no
560      * records are moved. <BR>
561      *
562      * If slot is > recordCount() or if slot < FIRST_SLOT_NUMBER, an exception
563      * will be thrown.
564      *
565      * <P><B>Space Policy</B><BR>
566      * If the row will not fit on a page then:
567      * <UL>
568      * <LI> an exception is thrown if the page has no other rows, this is an
569      * indication that the row could never fit on a page in this container.
570      * <LI> null is returned if there are other rows on the page, this is an
571      * indication that the row can potentially be inserted successfully
572      * onto an empty page.
573      * </UL>
574      *
575      * <P>
576      * <B>Locking Policy</B>
577      * <BR>
578      * Calls the lockRecordForWrite() method of the LockingPolicy object passed
579      * to the openContainer() call before the record is inserted.
580      * <BR>
581      * MT - latched
582      *
583      * @param slot The specified slot
584      * @param row The row version of the data
585      * @param undo if logical undo may be necessary, a function pointer
586      * to the access code where the logical undo logic
587      * resides. Null if logical undo is not necessary.
588      * @param validColumns a bit map of which columns in the row is valid.
589      * ValidColumns will not be changed by RawStore.
590      * @param insertFlag if INSERT_UNDO_WITH_PURGE set, then the undo of this
591      * insert will purge the row rather than mark it as
592      * deleted, which is the default bahavior for
593      * insertAtSlot and insert.
594      *
595      * @return A RecordHandle representing the new record, or null if the row
596      * will not fit on a non-empty page.
597      *
598      * @exception StandardException Standard Cloudscape error policy
599      * @exception StandardException The container was not opened in update mode.
600      * @exception StandardException The row cannot fit on the page
601      *
602      * @see LogicalUndo
603      * @see LogicalUndoable
604      **/
605     RecordHandle insertAtSlot(
606     int slot,
607     Object [] row,
608     FormatableBitSet validColumns,
609     LogicalUndo undo,
610     byte insertFlag,
611     int overflowThreshold)
612         throws StandardException;
613
614     /**
615      * Values for insertFlag.
616      * <p>
617      *
618      * INSERT_INITIAL - flag initializer
619      *
620      * INSERT_DEFAULT - default insert behavior, if the record does
621      * not fit on the page where the insert
622      * operation is called, an error will be
623      * returned, instead of overflowing the record.
624      *
625      * INSERT_UNDO_WITH_PURGE - if this is set, then the undo of this insert
626      * will purge the row rather than mark it as
627      * deleted, which is the default behaviro for
628      * insertAtSlot and insert.
629      *
630      * INSERT_CONDITIONAL - if this flag is set, then, the overflow is
631      * conditional. The record will be overflowed
632      * only if it exceeds the threshold specified
633      * by the properties, or the parameter.
634      *
635      * INSERT_OVERFLOW - if this flag is set, then the insert
636      * operation will overflow the record if it does
637      * not fit on the page.
638      *
639      * INSERT_FOR_SPLIT - a record is being updated that causes new
640      * portions to be inserted *and* the last new
641      * portion needs to point to an existing portion.
642      *
643      * Rules for the insert flags:
644      * 1. If INSERT_DEFAULT is set, INSERT_CONDITIONAL and INSERT_OVERFLOW
645      * will be ignored
646      * 2. INSERT_UNDO_WITH_PURGE can be set with any of the other 3 flags.
647      * 3. If INSERT_OVERFLOW is not set, INSERT_CONDITIONAL will be ignored.
648      * But, it is not necessary to set INSERT_CONDITIONAL when setting
649      * INSERT_OVERFLOW.
650      * 4. If INSERT_DEFAULT, INSERT_OVERFLOW both are not set, then, default
651      * insert action will be taken, i.e. no overflow will be allowed.
652      **/
653     static final byte INSERT_INITIAL = (byte) 0x00; // init the flag
654 static final byte INSERT_DEFAULT = (byte) 0x01; // default flag
655 static final byte INSERT_UNDO_WITH_PURGE = (byte) 0x02; // purge row on undo
656 static final byte INSERT_CONDITIONAL = (byte) 0x04; // conditional
657 // insert
658 static final byte INSERT_OVERFLOW = (byte) 0x08; // insert with
659 // possible overflow
660 static final byte INSERT_FOR_SPLIT = (byte) 0x10; // rawstore only
661
662
663     /**
664      * Fetch a record located in the passed in slot.
665      * <p>
666      * Fetch a record located in the passed in slot and fill-in the passed in
667      * StorebleRow and the Object columns contained within. If row
668      * is null then the record is locked but is not fetched.
669      * <BR>
670      * This interface allows the caller to either return a deleted row or not.
671      * If "ignoreDelete" is set to true, fetch the record regardless of whether
672      * it is deleted or not (same as above fetchFromSlot). However, if
673      * "ignoreDelete" is set to false and the and the slot correspond to a
674      * deleted row, null is returned.
675      * <BR>
676      * If a non-null Qualifier list is provided then the qualifier array will
677      * be applied to the row and the row will only be returned if the row
678      * qualifies, otherwise null will be returned. Values in the columns of
679      * row may or may not be altered while trying to apply the qualifiers, if
680      * null is returned the state of the columns is undefined. If a null
681      * Qualifier list is provided then no qualification is applied.
682      * <BR>
683      * If a non-null record handle is passed in, it is assumed that the record
684      * handle corresponds to the record in the slot. If record handle is null,
685      * a record handle will be manufactured and returned if the record is not
686      * deleted or if "ignoreDelete" is true. This parameter is here for the
687      * case where the caller have already manufactured the record handle for
688      * locking or other purposes so it would make sense for the page to avoid
689      * creating a new record handle object if possible.
690      *
691      *
692      * @param rh the record handle of the row. If non-null it must
693      * refer to the same record as the slot.
694      * @param slot the slot number
695      * @param row Row to be filled in with information from record.
696      * @param fetchDesc A structure to efficiently carry a set of parameters
697      * needed to describe the fetch, these include:
698      *
699      * validColumns - A bit map of which columns in the
700      * row to be fetched. ValidColumns will not be
701      * changed by RawStore.
702      *
703      * qualifier_list -
704      * A list of Qualifiers to apply to the row to see if
705      * the row should be returned.
706      *
707      * An array of qualifiers which restrict whether or not
708      * the row should be returned by the fetch. Rows for
709      * which any one of the qualifiers returns false are
710      * not returned by the fetch. If null, no qualification
711      * is done and the requested columns of the rows are
712      * returned. Qualifiers can only reference columns
713      * which are included in the scanColumnList. The
714      * column id that a qualifier returns is the column id
715      * the table, not the column id in the partial row
716      * being returned.
717      * qualifier_scratch_space -
718      * An array of int's that matches the size of the
719      * row[] array. Used to process qualifiers, if no
720      * qualifiers are input then array need not be
721      * input. Passed in rather than allocated so that
722      * space can be allocated a single time in a scan.
723      * If not passed in then raw store will allocate and
724      * deallocate per call.
725      *
726      * @param ignoreDelete if true, return row regardless of whether it is
727      * deleted or not. If false, only return non-deleted
728      * row.
729      *
730      * @return A handle to the record.
731      *
732      * @exception StandardException Standard Cloudscape error policy
733      *
734      * @see LockingPolicy
735      **/
736     public RecordHandle fetchFromSlot(
737     RecordHandle rh,
738     int slot,
739     Object [] row,
740     FetchDescriptor fetchDesc,
741     boolean ignoreDelete)
742         throws StandardException;
743
744
745     /**
746         Fetch a single field from a deleted or non-deleted record.
747         Fills in the passed in Object column with the field
748         identified by fieldid if column is not null, otherwise the record
749         is locked but not fetched.
750         <BR>
751         The fieldId of the first field is 0.
752         If the fieldId is >= the number of fields on the record,
753         column is restored to null
754         <P>
755         <B>Locking Policy</B>
756         <BR>
757             No locks are obtained.
758             It is up to the caller to obtain the correct locks.
759         <BR>
760
761         It is guaranteed that the page latch is not released by this method
762
763         @param slot is the slot number
764         @param fieldId is the column id
765         @param column is to be filled in with information from the record.
766
767         @return the Handle to the record that is locked
768
769         @exception StandardException Standard Cloudscape error policy, a
770                                         statement level exception is thrown if
771                                         the slot is not on the page.
772
773         @see Page#fetchFromSlot
774         @see LockingPolicy
775      */
776     public RecordHandle fetchFieldFromSlot(
777     int slot,
778     int fieldId,
779     Object column)
780         throws StandardException;
781
782     /**
783      * Test if a record is deleted.
784      * <p>
785      *
786      * <P>
787      * <B>Locking Policy</B>
788      * <BR>
789      * No locks are obtained.
790      *
791      * <BR>
792      * It is guaranteed that the page latch is not released by this method
793      *
794      * @param slot slot of record to be tested.
795      *
796      * @exception StandardException Standard Cloudscape error policy, a
797      * statement level exception is thrown if the
798      * slot is not on the page.
799      **/
800     public boolean isDeletedAtSlot(int slot)
801          throws StandardException;
802
803     /**
804         Update a field within the record, replacing its current value with
805         the stored representation of newValue. Record is identified by slot.
806         If the field does not exist then it is added to the record, but only if
807         (fieldId - 1) exists.
808
809         <BR><B>RESOLVE</B> right now it throws an exception if fieldId is not
810         already on the record, not add the next one as advertised.
811
812         <P>
813         <B>Locking Policy</B>
814         <P>
815         Calls the lockRecordForWrite() method of the LockingPolicy object
816         passed to the openContainer() call before the record is updated.
817
818         <BR>
819         It is guaranteed that the page latch is not released by this method
820         
821
822         @param slot is the slot number
823         @param fieldId is the column id
824         @param newValue has the new colum value to be stored in the record
825         @param undo if logical undo may be necessary, a function pointer to the
826         access code where the logical undo logic resides. Null if logical undo
827         is not necessary.
828
829         @return a Handle to the updated record.
830
831         @exception StandardException Standard Cloudscape error policy, a
832                                         statement level exception is thrown if
833                                         the slot is not on the page, or if the
834                                         record is deleted, or if the fieldId
835                                         is not on the record and (fieldId - 1)
836                                         does not exist.
837
838         @exception StandardException
839         The container was not opened in update mode.
840
841         @see LockingPolicy
842         @see LogicalUndo
843         @see LogicalUndoable
844
845     */
846     public RecordHandle updateFieldAtSlot(
847     int slot,
848     int fieldId,
849     Object newValue,
850     LogicalUndo undo)
851         throws StandardException;
852
853
854     /**
855      * Fetch the number of fields in a record.
856      * <p>
857      *
858      * <P>
859      * <B>Locking Policy</B>
860      * <P>
861      * No locks are obtained.
862      *
863      * <BR>
864      * It is guaranteed that the page latch is not released by this method
865      *
866      * @param slot is the slot number
867      *
868      * @return the number of fields in the record
869      *
870      * @exception StandardException Standard Cloudscape error policy
871      **/
872     public int fetchNumFieldsAtSlot(int slot)
873          throws StandardException;
874
875     /**
876         Mark the record identified by slot as deleted or undeleted according to the
877         delete flag.
878
879
880     */
881     /**
882      * Mark the record at slot as deleted or undeleted according to delete flag.
883      * <p>
884      *
885      * <P>
886      * <B>Locking Policy</B>
887      * <P>
888      * Calls the lockRecordForWrite() method of the LockingPolicy object passed
889      * to the openContainer() call before the record is deleted. If record
890      * already deleted, and an attempt is made to delete it, an exception is
891      * thrown. If record not deleted, and an attempt is made to undelete it,
892      * an exception is thrown.
893      *
894      * <BR>
895      * MT - latched
896      *
897      * @return a Handle to the deleted/undeleted record.
898      *
899      * @param slot is the slot number
900      * @param delete true if this record is to be deleted false if this
901      * deleted record is to be marked undeleted
902      * @param undo if logical undo may be necessary, a function pointer to
903      * the access code where the logical undo logic resides.
904      * Null if logical undo is not necessary.
905      *
906      * @exception StandardException Standard Cloudscape error policy
907      * @exception StandardException The container was not opened in update mode.
908      * @exception StandardException A statement level exception is thrown when
909      * trying to delete an already deleted record,
910      * or undelete a not deleted record.
911      *
912      * @exception StandardException A statement level exception is thrown if
913      * the slot is not on the page.
914      *
915      * @see LockingPolicy
916      * @see Page#delete
917      * @see LogicalUndo
918      * @see LogicalUndoable
919      *
920      **/
921     public RecordHandle deleteAtSlot(
922     int slot,
923     boolean delete,
924     LogicalUndo undo)
925          throws StandardException;
926
927
928     /**
929      * Purge the row(s) from page.
930      * <p>
931      * Purge the row(s) from page, get rid of the row(s) and slot(s) -
932      * <B>USE WITH CAUTION</B>,
933      * please see entire description of this operation before attempting to
934      * use this.
935      *
936      * Starting from the specified slot, n rows will be purged. That is, rows
937      * that occupies from slot to slot+n-1 will be purged from the page.
938      *
939      * <P>
940      * <B>Locking Policy</B>
941      * <P>
942      * Calls the lockRecordForWrite() method of the LockingPolicy object passed
943      * to the openContainer() call before the records are purged.
944      * <P>
945      *
946      * <B>NOTE : CAVEAT</B><BR>
947      * This operation will physically get rid of the row from the page, so if a
948      * subsequent operation on this page uses a slot that has been purged, then
949      * the undo of this operation will fail. It is only safe to use this
950      * operation if the caller knows that it has exclusive access to the page
951      * for the duration of the transaction, i.e, effectively holding a page
952      * lock on the page
953      * <P>
954      * <B>NOTE</B><BR>
955      * Outstanding handles to purged rows are no longer valid, accessing them
956      * will cause an exception to be thrown.
957      *
958      * <BR>
959      *<B>NOTE : Data Logging for Purges</B><BR>
960      * needDataLogged is used to specify whether data is required to be
961      * logged for purge operatios. Data Logging is required
962      * Only if the row can be reused or required for key search if a purge is
963      * rolled back;(rollback can occur if the system crashes in the middle of
964      * purges or some unexpected error condiditions rolled back.
965      * For example:
966      * 1)Btree expects the data to be there if a purge is rolled back;
967      * needDataLogged=true
968      * 2)Heaps does not care if data exist because only operation that can occur
969      * on a row whose purge rolled back is purging again.(needDataLogged=false)
970      *
971      * MT - latched
972      *
973      *
974      * @param slot the starting slot number
975      * @param numpurges number of slots to purge. If <= 0,
976      * just returns as a no-op.
977      * @param needDataLogged if set to true data is logged for purges else
978      * only headers.
979      *
980      * @exception StandardException Standard Cloudscape error policy
981      * @see LockingPolicy
982      **/
983     public void purgeAtSlot(
984     int slot,
985     int numpurges,
986     boolean needDataLogged)
987         throws StandardException;
988
989
990     /**
991      * move rows from one page to another, purging in the process.
992      * <p>
993      *
994      * Move from this page slot[src_slot] to slot[src_slot+num_rows-1] to
995      * destPage slot[dest_slot] to slot[dest_slot + num_rows - 1], in that
996      * order. Both this page and destPage must be latched and from the same
997      * container with the same page and record format.
998      *
999      * <BR>Slot[src_slot] to slot[src_slot+numrows-1] will be purged from this
1000     * page. RecordId on the dest page will be brand new and not in any
1001     * particular order or range. RecordId of the purged rows in this page is
1002     * never reused. Deleted and undeleted rows are copied over just the same.
1003     *
1004     * Exception will be thrown if this page does not have all the rows in the
1005     * moved over range.
1006     *
1007     * <BR><B>RESOLVE: reserve space now not copied over because in btree, a
1008     * row never shrinks. When this routine is called by heap or by some page
1009     * which will have shrunken row, then we need to add that </B>
1010     *
1011     * <BR>DestPage must have at least dest_slot row occupying slot[0] to
1012     * slot[dest_slot-1]. DestPage must have enough space to take the copied
1013     * over data. Rows that occupied slot number > dest_slot will be moved up
1014     * the slot (I.e., slot[dest_slot] -> slot[dest_slot + num_rows]).
1015     *
1016     * <BR>If this operation rolls back, this page (the src page) will get the
1017     * rows back and the dest page will purge the rows that were copied - this
1018     * is as if the rows were inserted into the dest page with
1019     * INSERT_UNDO_WITH_PURGE.
1020     *
1021     * <P>
1022     * <B>Locking Policy</B>
1023     * <P>
1024     * Calls the lockRecordForWrite() method of the LockingPolicy object
1025     * passed to the openContainer() call before the rows are copied over and
1026     * bore the records are purged. I.e, for num_rows moved, there will be
1027     * 2*num_rows calls to lockRecordForWrite.
1028     * <P>
1029     *
1030     * <P><B>Use with caution</B>
1031     * <BR>As with a normal purge, no space is reserved on this page for
1032     * rollback of the purge, so you must commit before inserting any rows
1033     * onto this page - unless those inserts are INSERT_UNDO_WITH_PURGE.
1034     *
1035     * @param destPage the page to copy to
1036     * @param src_slot start copying from this slot
1037     * @param num_rows copy and purge this many rows from this page
1038     * @param dest_slot copying into this slot of destPage
1039     *
1040     * @exception StandardException Standard Cloudscape error policy
1041     **/
1042    public void copyAndPurge(
1043    Page destPage,
1044    int src_slot,
1045    int num_rows,
1046    int dest_slot)
1047         throws StandardException;
1048
1049    /**
1050        Update the complete record identified by the slot.
1051
1052        <P>
1053        <B>Locking Policy</B>
1054        <P>
1055        Calls the lockRecordForWrite() method of the LockingPolicy object
1056        passed to the openContainer() call before the record is undeleted.
1057        If record already deleted, an exception is thrown.
1058
1059        <BR>
1060        It is guaranteed that the page latch is not released by this method
1061
1062        @return a Handle to the updated record.
1063        @param slot is the slot number
1064        @param validColumns a bit map of which columns in the row is valid.
1065        ValidColumns will not be changed by RawStore.
1066
1067        @exception StandardException Standard Cloudscape error policy
1068        @exception StandardException The container was not opened in update mode.
1069        @exception StandardException if the slot is not on the page.
1070
1071        @see Page#update
1072    */
1073    RecordHandle updateAtSlot(
1074    int slot,
1075    Object [] row,
1076    FormatableBitSet validColumns)
1077        throws StandardException;
1078
1079    /*
1080        Page operations
1081    */
1082
1083    /**
1084        Unlatch me, the page is exclusivly latched by its current user until
1085        this method call is made.
1086        <BR>
1087        After using this method the caller must throw away the
1088        reference to the Page object, e.g.
1089        <PRE>
1090            ref.unlatch();
1091            ref = null;
1092        </PRE>
1093        <BR>
1094        The page will be released automatically at the close of the
1095        container if this method is not called explictly.
1096
1097        <BR>
1098        MT - latched
1099
1100    */
1101    public void unlatch();
1102
1103
1104
1105    /**
1106        Return the number of records on the page. The returned count includes rows that are deleted,
1107        i.e. it is the same as the number of slots on the page.
1108
1109        <BR>
1110        MT - latched
1111
1112        @exception StandardException Standard Cloudscape error policy
1113    */
1114
1115    public int recordCount() throws StandardException;
1116
1117    /**
1118        Return the number of records on this page that are <B> not </B> marked as deleted.
1119        
1120         <BR>
1121        MT - latched
1122
1123        @exception StandardException Standard Cloudscape error policy
1124    */
1125
1126    public int nonDeletedRecordCount() throws StandardException;
1127
1128    /**
1129     * Is this page/deleted row a candidate for immediate reclaim space.
1130     * <p>
1131     * Used by access methods after executing a delete on "slot_just_deleted"
1132     * to ask whether a post commit should be queued to try to reclaim space
1133     * after the delete commits.
1134     * <p>
1135     * Will return true if the number of non-deleted rows on the page is
1136     * <= "num_non_deleted_rows". For instance 0 means schedule reclaim
1137     * only if all rows are deleted, 1 if all rows but one are deleted.
1138     * <p>
1139     * Will return true if the row just deleted is either a long row or long
1140     * column. In this case doing a reclaim space on the single row may
1141     * reclaim multiple pages of free space, so better to do it now rather
1142     * than wait for all rows on page to be deleted. This case is to address
1143     * the worst case scenario of all rows with long columns, but very short
1144     * rows otherwise. In this case there could be 1000's of rows on the
1145     * main page with many gigabytes of data on overflow pages in deleted space
1146     * that would not be reclaimed until all rows on the page were deleted.
1147     *
1148     * @return true if a reclaim space should be scheduled post commit on this
1149     * page, false otherwise.
1150     *
1151     * @param num_non_deleted_rows threshold number of non-deleted rows to
1152     * schedule reclaim space.
1153     * @param slot_just_deleted row on page to check for long row/long column
1154     *
1155     * @exception StandardException Standard exception policy.
1156     **/
1157    public boolean shouldReclaimSpace(
1158    int num_non_deleted_rows,
1159    int slot_just_deleted)
1160        throws StandardException;
1161
1162    /**
1163      Set the aux object for this page.
1164      To clear the auxObject in the page, pass in a null AuxObject.
1165      If the AuxObject has already been set, this method will
1166      call auxObjectInvalidated() on the old aux objkect and replace it with aux.
1167
1168        <BR>
1169        MT - latched
1170
1171      @see AuxObject
1172    **/
1173    public void setAuxObject(AuxObject aux);
1174
1175    /**
1176      Retrieve this page's aux object, returning null if there isn't one. The reference returned
1177      must only be used while the page is latched, once unlatch is called the reference to the
1178      aux object must be discarded.
1179
1180        <BR> MT - latched
1181
1182      @see AuxObject
1183    **/
1184    public AuxObject getAuxObject();
1185
1186    /**
1187        Returns true if the page is latched. Only intended to be used as a Sanity check. Callers must
1188        discard Page references once unlatch is called.
1189
1190        <BR>
1191        MT - latched
1192    */
1193
1194
1195    /*
1196     * time stamp - for those implmentation that supports it
1197     */
1198
1199    /**
1200        Set the time stamp to what is on page at this instance. No op if this
1201        page does not support time stamp.
1202
1203        @exception StandardException Standard Cloudscape error policy.
1204    */
1205    void setTimeStamp(PageTimeStamp ts) throws StandardException;
1206
1207
1208    /**
1209        Return a time stamp that can be used to identify the page of this
1210        specific instance. For pages that don't support timestamp, returns
1211        null.
1212    */
1213    PageTimeStamp currentTimeStamp();
1214
1215    /**
1216        See if timeStamp for this page is the same as the current
1217        instance of the page. Null timeStamp never equals the instance of the
1218        page.
1219
1220        @param ts the time stamp gotten from an earlier call to this page's
1221        getTimeStamp
1222        @return true if timestamp is the same
1223        @exception StandardException Standard Cloudscape error policy.
1224
1225        @see PageTimeStamp
1226    */
1227    boolean equalTimeStamp(PageTimeStamp ts) throws StandardException;
1228
1229    public boolean isLatched();
1230
1231    public static final String DIAG_PAGE_SIZE = "pageSize";
1232    public static final String DIAG_RESERVED_SPACE = "reserveSpace";
1233    public static final String DIAG_MINIMUM_REC_SIZE = "minRecSize";
1234    public static final String DIAG_BYTES_FREE = "bytesFree";
1235    public static final String DIAG_BYTES_RESERVED = "bytesReserved";
1236    public static final String DIAG_NUMOVERFLOWED = "numOverFlowed";
1237    public static final String DIAG_ROWSIZE = "rowSize";
1238    public static final String DIAG_MINROWSIZE = "minRowSize";
1239    public static final String DIAG_MAXROWSIZE = "maxRowSize";
1240    public static final String DIAG_PAGEOVERHEAD = "pageOverhead";
1241    public static final String DIAG_SLOTTABLE_SIZE = "slotTableSize";
1242}
1243

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags