001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.raw.RecordHandle
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.store.raw;
023:
024: import org.apache.derby.iapi.services.locks.Lockable;
025:
026: /**
027: A handle to a record within a container. This interface does not provide
028: an information about the data of the record, it is only used to perform
029: updates, deletes and allow ordered record manipulation.
030:
031: MT - immutable
032:
033: @see Page
034: */
035:
036: public interface RecordHandle extends Lockable {
037:
038: /*****************************************************************
039: * Special record Identifiers.
040: *
041: * Reserved identifiers that does not represent a row but rather have their
042: * own special meaning. No real rows will ever have these record
043: * identifiers.
044: *****************************************************************/
045:
046: /** An invalid record handle */
047: public static final int INVALID_RECORD_HANDLE = 0;
048:
049: /**
050: A lock with this recordHandle protects all the recordIds in the page.
051: No recordId can disappear while this lock is held.
052: New recordIds may appear while this lock is held.
053: */
054: public static final int RECORD_ID_PROTECTION_HANDLE = 1;
055:
056: /**
057: A lock with this recordHandle protects this deallocated page from
058: being freed and reallocated. This lock is released when the
059: transaction that deallocated the page terminates, at which point
060: the page can be freed if the transaction committed.
061: */
062: public static final int DEALLOCATE_PROTECTION_HANDLE = 2;
063:
064: /**
065: A lock with this recordHandle is used to lock the range of keys
066: between the first key in a btree and keys previous to it.
067: */
068: public static final int PREVIOUS_KEY_HANDLE = 3;
069:
070: /**
071: Reserve for future use - name it and define it when you have a need to
072: use one
073: */
074: public static final int RESERVED4_RECORD_HANDLE = 4;
075: public static final int RESERVED5_RECORD_HANDLE = 5;
076:
077: /**
078: First recordId that is used to identify a record.
079: */
080: public static final int FIRST_RECORD_ID = 6;
081:
082: /**
083: Obtain the page-unique identifier for this record.
084: This id combined with a page number is guaranteed to be unique
085: within a container.
086: */
087: public int getId();
088:
089: /**
090: Obtain the page number this record lives on.
091: */
092: public long getPageNumber();
093:
094: /**
095: * What slot number might the record be at?
096: * <p>
097: * The raw store guarantees that the record handle of a record will not
098: * change, but it's slot number may. An implementation of a record handle
099: * may provide a hint of the slot number, which may help routines like
100: * Page.getSlotNumber() perform better.
101: * <p>
102: * If an implementation does not track slot numbers at all the
103: * implementation should just always return Page.FIRST_SLOT_NUMBER.
104: *
105: * @return The slot number the record handle may be at.
106: **/
107: public int getSlotNumberHint();
108:
109: /**
110: Return the identity of my container.
111: */
112: public ContainerKey getContainerId();
113:
114: /**
115: Return the identity of my Page.
116: */
117: public Object getPageId();
118:
119: }
|