storage.java

lucene2.2.0版本

/** 
 * Copyright 2004 The Apache Software Foundation 
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); 
 * you may not use this file except in compliance with the License. 
 * You may obtain a copy of the License at 
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0 
 * 
 * Unless required by applicable law or agreed to in writing, software 
 * distributed under the License is distributed on an "AS IS" BASIS, 
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 * See the License for the specific language governing permissions and 
 * limitations under the License. 
 */
package org.apache.lucene.gdata.storage;

import org.apache.lucene.gdata.data.GDataAccount;
import org.apache.lucene.gdata.data.ServerBaseEntry;
import org.apache.lucene.gdata.data.ServerBaseFeed;

import com.google.gdata.data.BaseEntry;
import com.google.gdata.data.BaseFeed;

/**
 * A interface every storage implementation must provide to access the
 * <tt>Storage</tt>. It describes all access methodes needed to store,
 * retrieve and look up data stored in the <tt>Storage</tt> component. This
 * interface acts as a <tt>Facade</tt> to hide the storage implementation from
 * the user.
 * <p>
 * This could also act as a proxy for a remote storage. It also removes any
 * restrictions from custom storage implementations.
 * </p>
 * 
 * 
 * @author Simon Willnauer
 * 
 */
/*
 * not final yet
 */
public interface Storage {

    /**
     * 
     * Stores the given entry. The ServerBaseEntry must provide a feed id and
     * the service type. configuration for the entry.
     * 
     * @param entry -
     *            the entry to store
     * 
     * @return - the stored Entry for the server response
     * @throws StorageException -
     *             if the entry can not be stored or required field are not set.
     */
    public abstract BaseEntry storeEntry(ServerBaseEntry entry)
            throws StorageException;

    /**
     * Deletes the given entry. The ServerBaseEntry just hase to provide the
     * entry id to be deleted.
     * 
     * @param entry -
     *            the entry to delete from the storage
     * @throws StorageException -
     *             if the entry can not be deleted or the entry does not exist
     *             or required field are not set.
     */
    public abstract void deleteEntry(ServerBaseEntry entry)
            throws StorageException;

    /**
     * Updates the given entry. The ServerBaseEntry must provide a feed id,
     * service id and the
     * {@link org.apache.lucene.gdata.server.registry.ProvidedService}
     * 
     * @param entry -
     *            the entry to update
     * 
     * @return - the updated entry for server response.
     * @throws StorageException -
     *             if the entry can not be updated or does not exist or required
     *             field are not set.
     */
    public abstract BaseEntry updateEntry(ServerBaseEntry entry)
            throws StorageException;

    /**
     * Retrieves the requested feed from the storage. The given ServerBaseFeed
     * must provide information about the feed id, max-result count and the
     * start index. To create feeds and entries also the service type must be
     * provided.
     * 
     * @param feed -
     *            the to retieve from the storage
     * @return the requested feed
     * @throws StorageException -
     *             the feed does not exist or can not be retrieved or required
     *             field are not set.
     */
    public abstract BaseFeed getFeed(ServerBaseFeed feed)
            throws StorageException;

    /**
     * Retrieves the requested entry from the storage. The given entry must
     * provide information about the entry id and service type.
     * 
     * @param entry -
     *            the entry to retrieve
     * @return - the requested entry
     * @throws StorageException -
     *             if the entry does not exist or can not be created or required
     *             field are not set.
     */
    public abstract BaseEntry getEntry(ServerBaseEntry entry)
            throws StorageException;

    /**
     * Saves a new account. Required attributes to set are <tt>password</tt>
     * and <tt>accountname</tt>
     * 
     * @param account -
     *            the account to save
     * @throws StorageException -
     *             if the account can not be stored or the account already
     *             exists or required field are not set.
     */
    public abstract void storeAccount(final GDataAccount account)
            throws StorageException;

    /**
     * Updates an existing account. Required attributes to set are
     * <tt>password</tt> and <tt>accountname</tt>
     * 
     * @param account -
     *            the account to update
     * @throws StorageException -
     *             if the account does not exist or required field are not set.
     */
    public abstract void updateAccount(final GDataAccount account)
            throws StorageException;

    /**
     * Deletes the account for the given account name. All feeds and entries
     * referencing this account will be deleted as well!
     * 
     * @param accountname -
     *            the name of the account to delete
     * @throws StorageException -
     *             if the account does not exist
     */
    public abstract void deleteAccount(final String accountname)
            throws StorageException;

    /**
     * Stores a new feed for a existing account. The Feed must provide
     * information about the service type to store the feed for and the feed id
     * used for accessing and retrieving the feed from the storage. Each feed is
     * associated with a provided service. This method does check wheather a
     * feed with the same feed id as the given feed does already exists.
     * 
     * @see org.apache.lucene.gdata.server.registry.ProvidedService
     * @param feed -
     *            the feed to create
     * @param accountname -
     *            the account name belongs to the feed
     * @throws StorageException -
     *             if the feed already exists or the feed can not be stored
     */
    public abstract void storeFeed(final ServerBaseFeed feed, String accountname)
            throws StorageException;

    /**
     * Deletes the feed for the given feed id. All Entries referencing the given
     * feed id will be deleted as well.
     * 
     * @param feedId -
     *            the feed id for the feed to delete.
     * @throws StorageException -
     *             if the feed for the feed id does not exist or the feed can
     *             not be deleted
     */
    public abstract void deleteFeed(final String feedId)
            throws StorageException;

    /**
     * Updates a stored feed. The Feed must provide information about the
     * service type to store the feed for and the feed id used for accessing and
     * retrieving the feed from the storage.
     * 
     * @param feed -
     *            the feed to update
     * @param accountname -
     *            the account name belongs to the feed
     * @throws StorageException -
     *             if the feed does not exist or the feed can not be updated
     */
    public abstract void updateFeed(final ServerBaseFeed feed,
            String accountname) throws StorageException;

    /**
     * Retrieves the service name for a stored feed
     * 
     * @param feedId -
     *            the feed id
     * @return - the name of the service
     * @throws StorageException -
     *             if no feed for the provided id is stored
     */
    public abstract String getServiceForFeed(String feedId)
            throws StorageException;

    /**
     * 
     * Retrieves the {@link GDataAccount} for the given account name
     * @param accountName -
     *            the name of the requested account
     * @return - a {@link GDataAccount} instance for the requested account name
     * @throws StorageException -
     *             if no account for the account name is stored
     * 
     */
    public abstract GDataAccount getAccount(String accountName)
            throws StorageException;

    /**
     * close this storage instance. This method will be called by clients after
     * use.
     */
    public abstract void close();

    /**
     * Each feed belongs to one specific account. This method retrieves the
     * account name for
     * 
     * @param feedId -
     *            the id of the feed to retrieve the accountname
     * @return - the name / id of the account associated with the feed for the
     *         given feed id
     * @throws StorageException -
     *             if the feed is not stored or the storage can not be accessed
     */
    public String getAccountNameForFeedId(String feedId)
            throws StorageException;

    /**
     * Retrieves the date of the last modification for the given id
     * 
     * @param entryId -
     *            the entry Id
     * @param feedId -
     *            the feed which contains the entry
     * @return - The date of the last modifiaction in milliseconds or
     *         <code>new Long(0)</code> if the resource can not be found eg.
     *         the time can not be accessed
     * @throws StorageException -
     *             if the storage can not be accessed
     */
    public Long getEntryLastModified(String entryId, String feedId)
            throws StorageException;

    /**
     * Retrieves the date of the last modification for the given id
     * 
     * @param feedId -
     *            the feed Id
     * @return - The date of the last modifiaction in milliseconds or
     *         <code>new Long(0)</code> if the resource can not be found eg.
     *         the time can not be accessed
     * @throws StorageException -
     *             if the storage can not be accessed
     */
    public Long getFeedLastModified(String feedId) throws StorageException;

}