1/*- 2 * See the file LICENSE for redistribution information. 3 * 4 * Copyright (c) 2001,2008 Oracle. All rights reserved. 5 * 6 * $Id: LogCursor.java,v 12.9 2008/01/17 05:04:53 mjc Exp $ 7 */ 8 9package com.sleepycat.db; 10 11import com.sleepycat.db.internal.DbConstants; 12import com.sleepycat.db.internal.DbLogc; 13 14/** 15The LogCursor object is the handle for a cursor into the log files, 16supporting sequential access to the records stored in log files. 17<p> 18The handle is not free-threaded. Once the {@link com.sleepycat.db.LogCursor#close LogCursor.close} 19method is called, the handle may not be accessed again, regardless of 20that method's success or failure. 21*/ 22public class LogCursor { 23 /* package */ DbLogc logc; 24 25 /* package */ LogCursor(final DbLogc logc) { 26 this.logc = logc; 27 } 28 29 /* package */ 30 static LogCursor wrap(DbLogc logc) { 31 return (logc == null) ? null : new LogCursor(logc); 32 } 33 34 public synchronized void close() 35 throws DatabaseException { 36 37 logc.close(0); 38 } 39 40 /** 41 Return the LogSequenceNumber and log record to which the log cursor 42 currently refers. 43 <p> 44 @param lsn 45 The returned LogSequenceNumber. 46 <p> 47 @param data 48 The returned log record. The data field is set to the record 49 retrieved, and the size field indicates the number of bytes in 50 the record. 51 <p> 52 @return 53 The status of the operation. 54 <p> 55 <p> 56@throws DatabaseException if a failure occurs. 57 */ 58 public OperationStatus getCurrent(final LogSequenceNumber lsn, 59 final DatabaseEntry data) 60 throws DatabaseException { 61 62 return OperationStatus.fromInt( 63 logc.get(lsn, data, DbConstants.DB_CURRENT)); 64 } 65 66 /** 67 Return the next LogSequenceNumber and log record. 68 <p> 69 The current log position is advanced to the next record in the log, 70 and its LogSequenceNumber and data are returned. If the cursor has 71 not been initialized, the first available log record in the log will 72 be returned. 73 <p> 74 @param lsn 75 The returned LogSequenceNumber. 76 <p> 77 @param data 78 The returned log record. 79 <p> 80 @return 81 The status of the operation; a return of NOTFOUND indicates the last 82 log record has already been returned or the log is empty. 83 <p> 84 <p> 85@throws DatabaseException if a failure occurs. 86 */ 87 public OperationStatus getNext(final LogSequenceNumber lsn, 88 final DatabaseEntry data) 89 throws DatabaseException { 90 91 return OperationStatus.fromInt( 92 logc.get(lsn, data, DbConstants.DB_NEXT)); 93 } 94 95 /** 96 Return the first LogSequenceNumber and log record. 97 <p> 98 The current log position is set to the first record in the log, 99 and its LogSequenceNumber and data are returned. 100 <p> 101 @param lsn 102 The returned LogSequenceNumber. 103 <p> 104 @param data 105 The returned log record. 106 <p> 107 @return 108 The status of the operation; a return of NOTFOUND indicates the log 109 is empty. 110 <p> 111 <p> 112@throws DatabaseException if a failure occurs. 113 */ 114 public OperationStatus getFirst(final LogSequenceNumber lsn, 115 final DatabaseEntry data) 116 throws DatabaseException { 117 118 return OperationStatus.fromInt( 119 logc.get(lsn, data, DbConstants.DB_FIRST)); 120 } 121 122 /** 123 Return the last LogSequenceNumber and log record. 124 <p> 125 The current log position is set to the last record in the log, 126 and its LogSequenceNumber and data are returned. 127 <p> 128 @param lsn 129 The returned LogSequenceNumber. 130 <p> 131 @param data 132 The returned log record. 133 <p> 134 @return 135 The status of the operation; a return of NOTFOUND indicates the log 136 is empty. 137 <p> 138 <p> 139@throws DatabaseException if a failure occurs. 140 */ 141 public OperationStatus getLast(final LogSequenceNumber lsn, 142 final DatabaseEntry data) 143 throws DatabaseException { 144 145 return OperationStatus.fromInt( 146 logc.get(lsn, data, DbConstants.DB_LAST)); 147 } 148 149 /** 150 Return the previous LogSequenceNumber and log record. 151 <p> 152 The current log position is advanced to the previous record in the log, 153 and its LogSequenceNumber and data are returned. If the cursor has 154 not been initialized, the last available log record in the log will 155 be returned. 156 <p> 157 @param lsn 158 The returned LogSequenceNumber. 159 <p> 160 @param data 161 The returned log record. 162 <p> 163 @return 164 The status of the operation; a return of NOTFOUND indicates the first 165 log record has already been returned or the log is empty. 166 <p> 167 <p> 168@throws DatabaseException if a failure occurs. 169 */ 170 public OperationStatus getPrev(final LogSequenceNumber lsn, 171 final DatabaseEntry data) 172 throws DatabaseException { 173 174 return OperationStatus.fromInt( 175 logc.get(lsn, data, DbConstants.DB_PREV)); 176 } 177 178 /** 179 Return a specific log record. 180 <p> 181 The current log position is set to the specified record in the log, 182 and its data is returned. 183 <p> 184 @param lsn 185 The specified LogSequenceNumber. 186 <p> 187 @param data 188 The returned log record. 189 <p> 190 @return 191 The status of the operation. 192 <p> 193 <p> 194@throws DatabaseException if a failure occurs. 195 */ 196 public OperationStatus set(final LogSequenceNumber lsn, 197 final DatabaseEntry data) 198 throws DatabaseException { 199 200 return OperationStatus.fromInt( 201 logc.get(lsn, data, DbConstants.DB_SET)); 202 } 203 204 /** 205 Get the log file version. 206 <p> 207 @return 208 The log file version. 209 <p> 210 <p> 211@throws DatabaseException if a failure occurs. 212 */ 213 public int version() 214 throws DatabaseException { 215 216 return logc.version(0); 217 } 218} 219