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