//Enhydra API javadoc generation
/*
 * Enhydra Java Application Server Project
 * 
 * The contents of this file are subject to the Enhydra Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License on
 * the Enhydra web site ( http://www.enhydra.org/ ).
 * 
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 
 * the License for the specific terms governing rights and limitations
 * under the License.
 * 
 * The Initial Developer of the Enhydra Application Server is Lutris
 * Technologies, Inc. The Enhydra Application Server and portions created
 * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
 * All Rights Reserved.
 * 
 * Contributor(s):
 * 
 * $Id: PersistentStore.java,v 1.15 2005/06/13 09:26:06 draganr Exp $
 */





package com.lutris.util;
import java.io.*;
import java.util.*;

/**
 * Persitent storage interface.
 *
 * @author Kyle Clark
 */
public interface PersistentStore {

    /**
     * Method to store and object (persistent).
     *
     * @param key The key by which to identify the stored object.
     * @param obj The serializable object to store.
     * @exception com.lutris.util.PersistentStoreException
     *   if an error occurs.
     */
    public void store(String key, Serializable obj)
        throws com.lutris.util.PersistentStoreException;

    /**
     * Method to retrieve a stored object.
     *
     * @param key The key of the user whose session
     *   is to be retreived.
     * @return The stored object.  If an object is not
     *   stored under key, then <code>null</code> is returned.
     * @see #remove
     * @exception com.lutris.util.PersistentStoreException
     *   if an error occurs.
     */
    public Object retrieve(String key)
        throws com.lutris.util.PersistentStoreException;

    /**
     * Method to simultaneously retrieve and remove an
     * object from persistent store.  If an object is not
     * stored under key, then null is returned.
     *
     * @param key The key by which to identify the stored object
     *   that is to be removed.
     * @return The object that has been removed.
     * @exception com.lutris.util.PersistentStoreException
     *   if an error occurs.
     */
    public Object remove(String key)
        throws com.lutris.util.PersistentStoreException;

    /**
     * Method to delete a a key.  Any objects stored under
     * key are also removed.  If key is not defined, then
     * this method does nothing.
     *
     * @param key
     *   The key to remove.
     * @exception com.lutris.util.PersistentStoreException
     *   if an error occurs.
     */
    public void delete(String key)
        throws com.lutris.util.PersistentStoreException;


    /**
     * Method to query if an an object is stored.
     *
     * @param key The key by which to identify the stored object.
     * @exception com.lutris.util.PersistentStoreException
     *   if an error occurs.
     */
    public boolean exists(String key)
        throws com.lutris.util.PersistentStoreException;


    /**
     * Method that returns an enumration of the keys
     * of this persistent store.
     *
     * @exception com.lutris.util.PersistentStoreException
     *   if the enumeration could not be determined.
     */
    public java.util.Enumeration keys()
        throws com.lutris.util.PersistentStoreException;


}