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 }