001: /* Copyright (C) 2004 - 2007 db4objects Inc. http://www.db4o.com
002:
003: This file is part of the db4o open source object database.
004:
005: db4o is free software; you can redistribute it and/or modify it under
006: the terms of version 2 of the GNU General Public License as published
007: by the Free Software Foundation and as clarified by db4objects' GPL
008: interpretation policy, available at
009: http://www.db4o.com/about/company/legalpolicies/gplinterpretation/
010: Alternatively you can write to db4objects, Inc., 1900 S Norfolk Street,
011: Suite 350, San Mateo, CA 94403, USA.
012:
013: db4o is distributed in the hope that it will be useful, but WITHOUT ANY
014: WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: for more details.
017:
018: You should have received a copy of the GNU General Public License along
019: with this program; if not, write to the Free Software Foundation, Inc.,
020: 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
021: package com.db4o.types;
022:
023: import java.io.*;
024:
025: /**
026: * the db4o Blob type to store blobs independent of the main database
027: * file and allows to perform asynchronous upload and download operations.
028: * <br><br>
029: * <b>Usage:</b><br>
030: * - Define Blob fields on your user classes.<br>
031: * - As soon as an object of your class is stored, db4o automatically
032: * takes care that the Blob field is set.<br>
033: * - Call readFrom to read a blob file into the db4o system.<br>
034: * - Call writeTo to write a blob file from within the db4o system.<br>
035: * - getStatus may help you to determine, whether data has been
036: * previously stored. It may also help you to track the completion
037: * of the current process.
038: * <br><br>
039: * db4o client/server carries out all blob operations in a separate
040: * thread on a specially dedicated socket. One socket is used for
041: * all blob operations and operations are queued. Your application
042: * may continue to access db4o while a blob is transferred in the
043: * background.
044: */
045: public interface Blob extends Db4oType {
046:
047: /**
048: * returns the name of the file the blob was stored to.
049: * <br><br>The method may return null, if the file was never
050: * stored.
051: * @return String the name of the file.
052: */
053: public String getFileName();
054:
055: /**
056: * returns the status after the last read- or write-operation.
057: * <br><br>The status value returned may be any of the following:<br>
058: * Status.UNUSED no data was ever stored to the Blob field.<br>
059: * Status.AVAILABLE available data was previously stored to the Blob field.<br>
060: * Status.QUEUED an operation was triggered and is waiting for it's turn in the Blob queue.<br>
061: * Status.COMPLETED the last operation on this field was completed successfully.<br>
062: * Status.PROCESSING for internal use only.<br>
063: * Status.ERROR the last operation failed.<br>
064: * or a double between 0 and 1 that signifies the current completion percentage of the currently
065: * running operation.<br><br> the five STATUS constants defined in this interface or a double
066: * between 0 and 1 that signifies the completion of the currently running operation.<br><br>
067: * @return status - the current status
068: * @see com.db4o.ext.Status STATUS constants
069: */
070: public double getStatus();
071:
072: /**
073: * reads a file into the db4o system and stores it as a blob.
074: * <br><br>
075: * In Client/Server mode db4o will open an additional socket and
076: * process writing data in an additional thread.
077: * <br><br>
078: * @param file the file the blob is to be read from.
079: * @throws IOException in case of errors
080: */
081: public void readFrom(File file) throws IOException;
082:
083: /**
084: * reads a file into the db4o system and stores it as a blob.
085: * <br><br>
086: * db4o will use the local file system in Client/Server mode also.
087: * <br><br>
088: * @param file the file the blob is to be read from.
089: * @throws IOException in case of errors
090: */
091: public void readLocal(File file) throws IOException;
092:
093: /**
094: * writes stored blob data to a file.
095: * <br><br>
096: * db4o will use the local file system in Client/Server mode also.
097: * <br><br>
098: * @throws IOException in case of errors and in case no blob
099: * data was stored
100: * @param file the file the blob is to be written to.
101: */
102: public void writeLocal(File file) throws IOException;
103:
104: /**
105: * writes stored blob data to a file.
106: * <br><br>
107: * In Client/Server mode db4o will open an additional socket and
108: * process writing data in an additional thread.
109: * <br><br>
110: * @throws IOException in case of errors and in case no blob
111: * data was stored
112: * @param file the file the blob is to be written to.
113: */
114: public void writeTo(File file) throws IOException;
115:
116: /**
117: * Deletes the current file stored in this BLOB.
118: *
119: * @throws IOException in case of errors and in case no
120: * data was stored
121: */
122: public void deleteFile() throws IOException;
123: }
|