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.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 }