1 /*** 2 * 3 * Copyright 2004 Hiram Chirino 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 **/ 18 package org.activeio.journal; 19 20 import java.io.IOException; 21 22 import org.activeio.Packet; 23 24 /*** 25 * A Journal is a record logging Interface that can be used to implement 26 * a transaction log. 27 * 28 * 29 * This interface was largely extracted out of the HOWL project to allow 30 * ActiveMQ to switch between different Journal implementations verry easily. 31 * 32 * @version $Revision: 1.1 $ 33 */ 34 public interface Journal { 35 36 /*** 37 * Writes a {@see Packet} of data to the journal. If <code>sync</code> 38 * is true, then this call blocks until the data has landed on the physical 39 * disk. Otherwise, this enqueues the write request and returns. 40 * 41 * @param record - the data to be written to disk. 42 * @param sync - If this call should block until the data lands on disk. 43 * 44 * @return RecordLocation the location where the data will be written to on disk. 45 * 46 * @throws IOException if the write failed. 47 * @throws IllegalStateException if the journal is closed. 48 */ 49 public RecordLocation write(Packet packet, boolean sync) throws IOException, IllegalStateException; 50 51 /*** 52 * Reads a previously written record from the journal. 53 * 54 * @param location is where to read the record from. 55 * 56 * @return the data previously written at the <code>location</code>. 57 * 58 * @throws InvalidRecordLocationException if <code>location</code> parameter is out of range. 59 * It cannot be a location that is before the current mark. 60 * @throws IOException if the record could not be read. 61 * @throws IllegalStateException if the journal is closed. 62 */ 63 public Packet read(RecordLocation location) throws InvalidRecordLocationException, IOException, IllegalStateException; 64 65 /*** 66 * Informs the journal that all the journal space up to the <code>location</code> is no longer 67 * needed and can be reclaimed for reuse. 68 * 69 * @param location the location of the record to mark. All record locations before the marked 70 * location will no longger be vaild. 71 * 72 * @param sync if this call should block until the mark is set on the journal. 73 * 74 * @throws InvalidRecordLocationException if <code>location</code> parameter is out of range. 75 * It cannot be a location that is before the current mark. 76 * @throws IOException if the record could not be read. 77 * @throws IllegalStateException if the journal is closed. 78 */ 79 public abstract void setMark(RecordLocation location, boolean sync) 80 throws InvalidRecordLocationException, IOException, IllegalStateException; 81 82 /*** 83 * Obtains the mark that was set in the Journal. 84 * 85 * @see read(RecordLocation location); 86 * @return the mark that was set in the Journal. 87 * @throws IllegalStateException if the journal is closed. 88 */ 89 public RecordLocation getMark() throws IllegalStateException; 90 91 92 /*** 93 * Close the Journal. 94 * This is blocking operation that waits for any pending put opperations to be forced to disk. 95 * Once the Journal is closed, all other methods of the journal should throw IllegalStateException. 96 * 97 * @throws IOException if an error occurs while the journal is being closed. 98 */ 99 public abstract void close() throws IOException; 100 101 /*** 102 * Allows you to get the next RecordLocation after the <code>location</code> that 103 * is in the journal. 104 * 105 * @param location the reference location the is used to find the next location. 106 * To get the oldest location available in the journal, <code>location</code> 107 * should be set to null. 108 * 109 * 110 * @return the next record location 111 * 112 * @throws InvalidRecordLocationException if <code>location</code> parameter is out of range. 113 * It cannot be a location that is before the current mark. 114 * @throws IllegalStateException if the journal is closed. 115 */ 116 public abstract RecordLocation getNextRecordLocation(RecordLocation location) 117 throws InvalidRecordLocationException, IOException, IllegalStateException; 118 119 120 /*** 121 * Registers a <code>JournalEventListener</code> that will receive notifications from the Journal. 122 * 123 * @param listener object that will receive journal events. 124 * @throws IllegalStateException if the journal is closed. 125 */ 126 public abstract void setJournalEventListener(JournalEventListener listener) throws IllegalStateException; 127 128 }