/*
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
:
*
Block
implementations
* not to depend on specific StormPool
implementations.
* delete()
* method in the Block
would only delete the block
* from the single pool it was loaded from.
*
* 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;
}