Journal xref

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 }