Store.java :  » Database-DBMS » mckoi » com » mckoi » store » Java Open Source

Java Open Source » Database DBMS » mckoi 
mckoi » com » mckoi » store » Store.java
/**
 * com.mckoi.store.Store  30 Aug 2002
 *
 * Mckoi SQL Database ( http://www.mckoi.com/database )
 * Copyright (C) 2000, 2001, 2002  Diehl and Associates, Inc.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * Version 2 as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License Version 2 for more details.
 *
 * You should have received a copy of the GNU General Public License
 * Version 2 along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 *
 * Change Log:
 * 
 * 
 */

package com.mckoi.store;

import java.util.List;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.IOException;

/**
 * A store is a resource where areas can be allocated and freed to store
 * objects.  A store can be backed by a file or main memory, or a combination of
 * the two.
 * <p>
 * Some characteristics of implementations of Store may be separately
 * specified.  For example, a file based store that is intended to persistently
 * store objects may have robustness as a primary requirement.  A main memory
 * based store, or other type of volatile store, may not require robustness.
 *
 * @author Tobias Downer
 */

public interface Store {

  /**
   * Allocates a block of memory in the store of the specified size and returns
   * an AreaWriter object that can be used to initialize the contents of the
   * area.  Note that an area in the store is undefined until the 'finish'
   * method is called in AreaWriter.
   *
   * @param size the amount of memory to allocate.
   * @return an AreaWriter object that allows the area to be setup.
   * @throws IOException if not enough space available to create the area or
   *   the store is read-only.
   */
  AreaWriter createArea(long size) throws IOException;

  /**
   * Deletes an area that was previously allocated by the 'createArea' method
   * by the area id.  Once an area is deleted the resources may be reclaimed.
   * The behaviour of this method is undefined if the id doesn't represent a
   * valid area.
   *
   * @param id the identifier of the area to delete.
   * @throws IOException (optional) if the id is invalid or the area can not
   *   otherwise by deleted.
   */
  void deleteArea(long id) throws IOException;

  /**
   * Returns an InputStream implementation that allows for the area with the
   * given identifier to be read sequentially.  The behaviour of this method,
   * and InputStream object, is undefined if the id doesn't represent a valid
   * area.
   * <p>
   * When 'id' is -1 then a fixed area (64 bytes in size) in the store is
   * returned.  The fixed area can be used to store important static
   * static information.
   *
   * @param id the identifier of the area to read, or id = -1 is a 64 byte
   *   fixed area in the store.
   * @return an InputStream that allows the area to be read from the start.
   * @throws IOException (optional) if the id is invalid or the area can not
   *   otherwise be accessed.
   */
  InputStream getAreaInputStream(long id) throws IOException;
  
  /**
   * Returns an object that allows for the contents of an area (represented by
   * the 'id' parameter) to be read.  The behaviour of this method, and Area
   * object, is undefined if the id doesn't represent a valid area.
   * <p>
   * When 'id' is -1 then a fixed area (64 bytes in size) in the store is
   * returned.  The fixed area can be used to store important static
   * static information.
   *
   * @param id the identifier of the area to read, or id = -1 is a 64 byte
   *   fixed area in the store.
   * @return an Area object that allows access to the part of the store.
   * @throws IOException (optional) if the id is invalid or the area can not
   *   otherwise be accessed.
   */
  Area getArea(long id) throws IOException;

  /**
   * Returns an object that allows for the contents of an area (represented by
   * the 'id' parameter) to be read and written.  The behaviour of this method,
   * and MutableArea object, is undefined if the id doesn't represent a valid
   * area.
   * <p>
   * When 'id' is -1 then a fixed area (64 bytes in size) in the store is
   * returned.  The fixed area can be used to store important static
   * static information.
   *
   * @param id the identifier of the area to access, or id = -1 is a 64 byte
   *   fixed area in the store.
   * @return a MutableArea object that allows access to the part of the store.
   * @throws IOException (optional) if the id is invalid or the area can not
   *   otherwise be accessed.
   */
  MutableArea getMutableArea(long id) throws IOException;

  // ---------- Check Point Locking ----------

  /**
   * It is often useful to guarentee that a certain sequence of updates to a
   * store is completed and not broken in the middle.  For example, when
   * inserting data into a table you don't want a record to be partially
   * written when a check point is made.  You want the entire sequence of
   * modifications to be completed before the check point can run.  This
   * means that if a crash occurs, a check point will not recover to a
   * possible corrupt file.
   * <p>
   * To achieve this, the 'lockForWrite' and 'unlockForWrite' methods are
   * available.  When 'lockForWrite' has been called, a check point can not
   * created until there are no write locks obtained on the table.
   */
  void lockForWrite();

  /**
   * See the 'lockForWrite' method description.
   */
  void unlockForWrite();

  // ---------- Diagnostic ----------

  /**
   * Returns true if the store was closed cleanly.  This is important
   * information that may need to be considered when reading information from
   * the store.  This is typically used to issue a scan on the data in the
   * store when it is not closed cleanly.
   */
  boolean lastCloseClean();

  /**
   * Returns a complete list of pointers to all areas in the Store as Long
   * objects sorted from lowest pointer to highest.  This should be used for
   * diagnostics only because it may be difficult for this to be generated
   * with some implementations.  It is useful in a repair tool to determine if
   * a pointer is valid or not.
   */
  List getAllAreas() throws IOException;

}

java2s.com  | Contact Us | Privacy Policy
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.