01: /*
02: * Copyright 2004 Outerthought bvba and Schaubroeck nv
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
10: * Unless required by applicable law or agreed to in writing, software
11: * distributed under the License is distributed on an "AS IS" BASIS,
12: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13: * See the License for the specific language governing permissions and
14: * limitations under the License.
15: */
16: package org.outerj.daisy.blobstore;
17:
18: import java.io.InputStream;
19: import java.util.concurrent.locks.Lock;
20:
21: /**
22: * Stores arbitrairy blob ("binary large object") data.
23: *
24: * <p>The store is a write-once, read-many type of store. An existing
25: * blob cannot be updated, rather a new one needs to be written.
26: *
27: * <p>The user of the BlobStore is himself responsible not to retrieve or delete
28: * a blob before it is completely written.
29: */
30: public interface BlobStore {
31: /**
32: * Returns an auto-generated key by which the blob can later be retrieved.
33: */
34: String store(byte[] data) throws BlobIOException;
35:
36: /**
37: * Returns an auto-generated key by which the blob can later be retrieved.
38: * The InputStream will be closed for you.
39: */
40: String store(InputStream is) throws BlobIOException;
41:
42: /**
43: * The caller is responsible himself that a file is not being read before it is completely written.
44: * The caller is also responsible for making sure the stream gets closed, otherwise resource
45: * might leak (thus: always in a try-catch block!).
46: */
47: InputStream retrieve(String name) throws BlobIOException,
48: NonExistingBlobException;
49:
50: void delete(String name) throws NonExistingBlobException;
51:
52: /**
53: * Suspends all write operations to the blob store, after calling this method
54: * only read operation will be allowed. This method only returns after all
55: * active write operations have been finished.
56: *
57: * @param msecs max time to wait for active write operations to finish
58: */
59: boolean suspendWrites(long msecs) throws InterruptedException;
60:
61: /**
62: * Resumes write operations (after being suspended with {@link #suspendWrites(long)}.
63: */
64: void resumeWrites();
65:
66: /**
67: * Returns a lock which can be acquired to avoid that the BlobStore can
68: * go into suspension while you have this lock.
69: */
70: Lock getAvoidSuspendLock();
71: }
|