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.codehaus.activemq.journal; 19 20 import java.io.IOException; 21 22 /*** 23 * A Journal is a record logging Interface that can be used to implement 24 * a transaction log. 25 * 26 * 27 * This interface was largely extracted out of the HOWL project to allow 28 * ActiveMQ to switch between different Journal implementations verry easily. 29 * 30 * @version $Revision: 1.1 $ 31 */ 32 public interface Journal { 33 34 /*** 35 * Writes a byte array <code>record</code> to the journal. If <code>sync</code> 36 * is true, then this call blocks until the data has landed on the physical 37 * disk. Otherwise, this call returns imeadiatly. 38 * 39 * @param record - the data to be written to disk. 40 * @param sync - If this call should block until the data lands on disk. 41 * 42 * @return RecordLocation the location where the data will be written to on disk. 43 * 44 * @throws IOException if the write failed. 45 * @throws IllegalStateException if the journal is closed. 46 */ 47 public RecordLocation write(byte record[], boolean sync) throws IOException, IllegalStateException; 48 49 /*** 50 * Reads a previously written record from the journal. 51 * 52 * @param location is where to read the record from. 53 * 54 * @return the data previously written at the <code>location</code>. 55 * 56 * @throws InvalidRecordLocationException if <code>location</code> parameter is out of range. 57 * It cannot be a location that is before the current mark. 58 * @throws IOException if the record could not be read. 59 * @throws IllegalStateException if the journal is closed. 60 */ 61 public byte[] read(RecordLocation location) throws InvalidRecordLocationException, IOException, IllegalStateException; 62 63 /*** 64 * Informs the journal that all the journal space up to the <code>location</code> is no longer 65 * needed and can be reclaimed for reuse. 66 * 67 * @param location the location of the record to mark. All record locations before the marked 68 * location will no longger be vaild. 69 * 70 * @param sync if this call should block until the mark is set on the journal. 71 * 72 * @throws InvalidRecordLocationException if <code>location</code> parameter is out of range. 73 * It cannot be a location that is before the current mark. 74 * @throws IOException if the record could not be read. 75 * @throws IllegalStateException if the journal is closed. 76 */ 77 public abstract void setMark(RecordLocation location, boolean sync) 78 throws InvalidRecordLocationException, IOException, IllegalStateException; 79 80 /*** 81 * Obtains the mark that was set in the Journal. 82 * 83 * @see read(RecordLocation location); 84 * @return the mark that was set in the Journal. 85 * @throws IllegalStateException if the journal is closed. 86 */ 87 public RecordLocation getMark() throws IllegalStateException; 88 89 90 /*** 91 * Close the Journal. 92 * This is blocking operation that waits for any pending put opperations to be forced to disk. 93 * Once the Journal is closed, all other methods of the journal should throw IllegalStateException. 94 * 95 * @throws IOException if an error occurs while the journal is being closed. 96 */ 97 public abstract void close() throws IOException; 98 99 /*** 100 * Allows you to get the next RecordLocation after the <code>location</code> that 101 * is in the journal. 102 * 103 * @param location the reference location the is used to find the next location. 104 * To get the oldest location available in the journal, <code>location</code> 105 * should be set to null. 106 * 107 * 108 * @return the next record location 109 * 110 * @throws InvalidRecordLocationException if <code>location</code> parameter is out of range. 111 * It cannot be a location that is before the current mark. 112 * @throws IllegalStateException if the journal is closed. 113 */ 114 public abstract RecordLocation getNextRecordLocation(RecordLocation location) 115 throws InvalidRecordLocationException, IOException, IllegalStateException; 116 117 118 /*** 119 * Registers a <code>JournalEventListener</code> that will receive notifications from the Journal. 120 * 121 * @param listener object that will receive journal events. 122 * @throws IllegalStateException if the journal is closed. 123 */ 124 public abstract void setJournalEventListener(JournalEventListener listener) throws IllegalStateException; 125 126 }