View Javadoc

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 }