/* StormPool.java * * Copyright (c) 2002, Benja Fallenstein * * This file is part of Storm. * * Storm is free software; you can redistribute it and/or modify it under * the terms of the GNU Lesser General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * Storm 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 Lesser General * Public License for more details. * * You should have received a copy of the GNU Lesser General * Public License along with Storm; if not, write to the Free * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, * MA 02111-1307 USA * * */ /* * Written by Benja Fallenstein */ package org.nongnu.storm; import org.nongnu.storm.headers.*; import java.io.*; import java.util.*; /** A Storm Storm pool of blocks. */ public interface StormPool { // BASIC BLOCK HANDLING /** Get a block from this pool. * This does not necessarily load the data (and thus doesn't * necessarily detect spoofing). Depending on the implementation * of Block, it is possible that spoofing isn't * detected until an InputStream retrieved from the Block * is closed. *

* Note: If the block has to be requested from the network, * this method blocks until it has been loaded! * For asynchronous loading, see request(). *

* Calling getPool() on the returned block may return * a different pool than this: If the block is retrieved from * a sub-pool of this pool, getPool() will return * that sub-pool. This is intentional. * @throws FileNotFoundException if the block is not found * in the pool. */ Block get(BlockId id) throws FileNotFoundException, IOException; /** Load a block from the network, if it is not available locally. * If listener is given, it is informed when * the block has either been loaded, or the pool * has given up on loading it. *

* If the block is already available locally, it will be returned. * The BlockListener will not be called at all. * If the block must be loaded, null is returned * (no exception is thrown). If the block is known not to be * available, a FileNotFoundException is thrown. *

* After the block has been loaded, it will be kept locally * for some time, but no guarantees are made as to how long. * It is reasonable to request() a block, * doing nothing if null is returned, * and when notification comes in that the block * has been loaded, repeat the whole procedure. * If the block has already been uncached at the time * of the second request() and we get * another chance. *

* We could make it so that the BlockListener * is always called, even when we can return the block * immediately. However it is easier to simulate that * behavior on top of the current one than it would be * to simulate the current behavior on top of that one, * and both are expected to be needed. * @throws FileNotFoundException if the block is not found * in the pool. */ Block request(BlockId id, BlockListener listener) throws IOException; /** Load a block from the network, if it is not available locally. * Equivalent to request(id, null). * @throws FileNotFoundException if the block is not found * in the pool. */ Block request(BlockId id) throws IOException; /** Add a block to this pool. * The data in the block is checked by this class to assure * that the block's id really matches the data in the block. * If this weren't the case, spoofing could occur by simply * creating a non-checking implementation of Block. */ void add(Block b) throws IOException; /** Remove a block from this pool. * There are two reasons this is not a method of Block: *

* @throws FileNotFoundException if the block is not found * in the pool. */ void delete(Block b) throws IOException; // GETTING THE SET OF IDS /** Get the set of all known ids in this pool. * There is no guarantee that all ids which can be loaded * from this block are in this set. For example, a pool * that represents a p2p network may not know the set of ids * it is able to load. *

* This returns a SetCollector so that * implementations that need to do a network lookup * can spawn a thread to do that. If you want to * block your thread until all ids have been read * from the network, you can write: *

     *      Set ids = pool.getIds().blockSet();
     *  
*

* Never returns null. */ SetCollector getIds() throws IOException; // CREATING NEW BLOCKS /** Get an OutputStream for adding a new block to this pool. * A new UniqueHeader822 with the specified MIME content type * is used. * @see BlockOutputStream */ BlockOutputStream getBlockOutputStream(String contentType) throws IOException; /** Get an OutputStream for adding a new block to this pool. * The header for the new block is passed explicitly. * @see BlockOutputStream */ BlockOutputStream getBlockOutputStream(Header822 hdr) throws IOException; // GETTING POOL NAMES /** This is currently not implemented and probably requires more thought. * When the time comes to replace Mediaserver with Storm, we'll see * how to implement the things currently done through pool names; * these functions might be resurrected, replaced by something else, * or simply gotten rid of if they are not (at that time) needed. * - Benja */ ///** Get the name of the pool new blocks are put into by default. // */ //String getDefaultPoolName() throws IOException; //Set getPoolNames() throws IOException; }