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 }