001/**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.activemq.store.kahadb;
018
019import java.io.DataInput;
020import java.io.DataOutput;
021import java.io.IOException;
022
023import org.apache.activemq.store.kahadb.disk.journal.Location;
024import org.apache.activemq.store.kahadb.disk.page.Page;
025import org.apache.activemq.store.kahadb.disk.page.Transaction;
026
027/**
028 * Interface for the store meta data used to hold the index value and other needed
029 * information to manage a KahaDB store instance.
030 */
031public interface KahaDBMetaData<T> {
032
033    /**
034     * Indicates that this meta data instance has been opened and is active.
035     */
036    public static final int OPEN_STATE = 2;
037
038    /**
039     * Indicates that this meta data instance has been closed and is no longer active.
040     */
041    public static final int CLOSED_STATE = 1;
042
043    /**
044     * Gets the Page in the store PageFile where the KahaDBMetaData instance is stored.
045     *
046     * @return the Page to use to start access the KahaDBMetaData instance.
047     */
048    Page<T> getPage();
049
050    /**
051     * Sets the Page instance used to load and store the KahaDBMetaData instance.
052     *
053     * @param page
054     *        the new Page value to use.
055     */
056    void setPage(Page<T> page);
057
058    /**
059     * Gets the state flag of this meta data instance.
060     *
061     *  @return the current state value for this instance.
062     */
063    int getState();
064
065    /**
066     * Sets the current value of the state flag.
067     *
068     * @param value
069     *        the new value to assign to the state flag.
070     */
071    void setState(int value);
072
073    /**
074     * Returns the Journal Location value that indicates that last recorded update
075     * that was successfully performed for this KahaDB store implementation.
076     *
077     * @return the location of the last successful update location.
078     */
079    Location getLastUpdateLocation();
080
081    /**
082     * Updates the value of the last successful update.
083     *
084     * @param location
085     *        the new value to assign the last update location field.
086     */
087    void setLastUpdateLocation(Location location);
088
089    /**
090     * For a newly created KahaDBMetaData instance this method is called to allow
091     * the instance to create all of it's internal indices and other state data.
092     *
093     * @param tx
094     *        the Transaction instance under which the operation is executed.
095     *
096     * @throws IOException if an error occurs while creating the meta data structures.
097     */
098    void initialize(Transaction tx) throws IOException;
099
100    /**
101     * Instructs this object to load its internal data structures from the KahaDB PageFile
102     * and prepare itself for use.
103     *
104     * @param tx
105     *        the Transaction instance under which the operation is executed.
106     *
107     * @throws IOException if an error occurs while creating the meta data structures.
108     */
109    void load(Transaction tx) throws IOException;
110
111    /**
112     * Reads the serialized for of this object from the KadaDB PageFile and prepares it
113     * for use.  This method does not need to perform a full load of the meta data structures
114     * only read in the information necessary to load them from the PageFile on a call to the
115     * load method.
116     *
117     * @param in
118     *        the DataInput instance used to read this objects serialized form.
119     *
120     * @throws IOException if an error occurs while reading the serialized form.
121     */
122    void read(DataInput in) throws IOException;
123
124    /**
125     * Writes the object into a serialized form which can be read back in again using the
126     * read method.
127     *
128     * @param out
129     *        the DataOutput instance to use to write the current state to a serialized form.
130     *
131     * @throws IOException if an error occurs while serializing this instance.
132     */
133    void write(DataOutput out) throws IOException;
134
135}