ccs.cdb
Class CDBFile

java.lang.Object
  ccs.beetree.BeeObject
      ccs.cdb.CDBObject
          ccs.cdb.CDBFileSysObject
              ccs.cdb.CDBFile

All Implemented Interfaces:

CallbackStreamProducer, java.io.Serializable

public class CDBFile
extends CDBFileSysObject
implements CallbackStreamProducer

A CDBFile wraps a java.io.File and allows it to be stored in a CDB. The keys of CDBFiles consist of a unix / URL type "path"; thus the collection of CDBFiles forms a "virtual filesystem". Such a collection will also include CDBDirectory objects with keys ending in "/", if "directory" listings are required. These store the collection of strings comprising the keys of CDBFiles and other CDBDirectory's in that "directory"; this allows efficient indexing. Without these it would be necessary to traverse the entire set to list the root directory.

A CDBFile is marshalled and unmarshalled either into a real file, or into a SwappingBuffer. In the case of a real file, there is usually some relation between the key and the filename, but not invariably. Note. SwappingBuffer is not MT-safe. By extension, neither are any of the operations which involve it. If in doubt, treat this class as MT-UNSAFE.

See Also:

CDBObject, BeeTree, SwappingBuffer, Serialized Form

Field Summary

Fields inherited from class ccs.cdb.CDBObject

clone, key, marshalVersion, owner

Fields inherited from class ccs.beetree.BeeObject

cipher, encodedLength, isBodiless, isForceDirectDecrypt, isZip, slack

Constructor Summary

CDBFile()
Create a new default CDBFile with null key, writing to a null SwappingBuffer, with no compression and no case-lowering.

Method Summary

protected long	cpgetMarshalledLength() return the marshalled data length if known, just like getMarshalledLength
protected void	cpmarshal(java.io.DataOutputStream dos) override this to marshal your data, just like marshal.
protected void	cppreMarshal() Override this to check your object for validity just before marshalling it, just like preMarshal.
protected void	cppreUnmarshal() override this to check that your object is fit to have information unmarshalled into it, just like preUnmarshal.
protected void	cpunmarshal(java.io.DataInputStream dis, int marshalver) override this to unmarshal your data, just like unmarshal.
SwappingBuffer	getBuffer() Returns the SwappingBuffer used as the source / target for virtual files.
CallbackStreamConsumer	getConsumer()
java.io.File	getFile() Returns the current target/source file.
java.lang.String	getInternalPath() return the internal path inside the DB (i.e. the DB key).
void	setBuffer(SwappingBuffer sb) Sets the swapping buffer used as the source / target for writes / reads.
void	setConsumer(CallbackStreamConsumer consumer) Prepare to read this file via a callback.
void	setFile(java.io.File f) Sets the current target/source file.
void	setInternalPath(java.lang.String path) Set the internal path inside the DB (i.e. the DB key).
static void	setMimeRegistry(MimeRegistry mimeReg) Sets the MimeRegistry to use when determining compressibility.
void	setReal(boolean isReal) Deprecated. This is now managed automatically. This call does nothing.
static void	setTrialZipSizeLimits(long lower, long upper) When inserting a file of unknown compressibility, CDBFile will attempt to compress it anyway provided that its size lies between a pair of limits.
long	size()
void	startStreamProduction() Produces a stream, reading the file from the CDB which currently owns this.

Methods inherited from class ccs.cdb.CDBObject

canChangeKeyProgrammatically, canDeleteProgrammatically, canUpdateProgrammatically, cpgetKey, cpsetKey, getCDB, getKey, getMarshalledLength, marshal, preMarshal, preUnmarshal, setCDB, setKey, transientMarshal, transientUnmarshal, unmarshal

Methods inherited from class ccs.beetree.BeeObject

lock, unlock

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CDBFile

public CDBFile()

Create a new default CDBFile with null key, writing to a null SwappingBuffer, with no compression and no case-lowering. If the buffer is still null by the time it's needed, an empty one will be created and used: feel free to rely on this for basic applications (eg. serving furniture or other small files from a CPA).

Method Detail

setInternalPath

public void setInternalPath(java.lang.String path)

Set the internal path inside the DB (i.e. the DB key). There is no causal link between this and the name of the disk file which it maps to if real.

getInternalPath

public java.lang.String getInternalPath()

return the internal path inside the DB (i.e. the DB key).

setReal

public void setReal(boolean isReal)

Deprecated. This is now managed automatically. This call does nothing.

Set whether the CDBFile binds to a real disk file or to a SwappingBuffer.

Parameters:

isReal - true for a real file.

setFile

public void setFile(java.io.File f)

Sets the current target/source file. Ignored if not bound to a real file; i.e. if setReal(false) has been issued.

Parameters:

f - The File.

getFile

public java.io.File getFile()

Returns the current target/source file.

Returns:

The File.

setBuffer

public void setBuffer(SwappingBuffer sb)

Sets the swapping buffer used as the source / target for writes / reads. Supply a writable SwappingBuffer for find/next/prev, and a full one (ready to be read) for insert. If null, the operations will create a new buffer (ie. write operations will write the empty stream). Note: SwappingBuffer is MT-unsafe. Use only in one thread, or within a synchronized block.

Parameters:

sb - The swapping buffer.

getBuffer

public SwappingBuffer getBuffer()

Returns the SwappingBuffer used as the source / target for virtual files.

Returns:

The buffer.

setConsumer

public void setConsumer(CallbackStreamConsumer consumer)

Prepare to read this file via a callback. This allows direct streaming from the CDB - you don't have to extract the file completely before you can start processing it. This reduces latency, which is otherwise a performance problem in the case of large files (particularly media). However, there are two issues to be aware of: firstly, this will block the CDBeeTree object involved until the stream has finished (typically minutes to hours!). Secondly, if the stream is corrupt you won't find this out until the end of the stream. For this reason, you should avoid using individual ciphers on CDBFiles you intend to stream in this way; however, you probably wouldn't want to do that anyway.

Specified by:

setConsumer in interface CallbackStreamProducer

Parameters:

consumer - The stream consumer which will be called back to take delivery of the file data.

getConsumer

public CallbackStreamConsumer getConsumer()

startStreamProduction

public void startStreamProduction()
                           throws java.io.IOException

Produces a stream, reading the file from the CDB which currently owns this. Either use setCDB explicitly, or do a findExactKey first.

Specified by:

startStreamProduction in interface CallbackStreamProducer

Throws:

java.io.IOException

size

public long size()

cppreMarshal

protected void cppreMarshal()
                     throws java.io.IOException

Description copied from class: CDBObject

Override this to check your object for validity just before marshalling it, just like preMarshal. The default implementation does nothing.

Overrides:

cppreMarshal in class CDBObject

Throws:

java.io.IOException - if the object is not fit to be marshalled.

cppreUnmarshal

protected void cppreUnmarshal()
                       throws java.io.IOException

Description copied from class: CDBObject

override this to check that your object is fit to have information unmarshalled into it, just like preUnmarshal. The default implementation does nothing.

Note: This method is not called on objects created through the "cloning" method employed when the supplied object is not of the correct class - see introductory essay. This is a misfeature. The reason that it persists is that if the method _were_ called and then threw, the CDB would be marked as corrupt, which would be highly undesirable. The method is therefore only really useful for set classes which have no sub-classes other than the set class itself (i.e. give a homogeneous set, where cloning is never needed).

Overrides:

cppreUnmarshal in class CDBObject

Throws:

java.io.IOException - If the object is not fit to be unmarshalled into.

cpgetMarshalledLength

protected long cpgetMarshalledLength()

Description copied from class: CDBObject

return the marshalled data length if known, just like getMarshalledLength

Overrides:

cpgetMarshalledLength in class CDBObject

Returns:

the marshalled length if known, -1 if not.

cpmarshal

protected void cpmarshal(java.io.DataOutputStream dos)
                  throws java.io.IOException

Description copied from class: CDBObject

override this to marshal your data, just like marshal. The data will be in the object's fields when this is called (rather than within any UI objects).

Overrides:

cpmarshal in class CDBFileSysObject

Parameters:

dos - The stream to marshal onto.

Throws:

java.io.IOException - If this breaks (breaks the CDB too).

cpunmarshal

protected void cpunmarshal(java.io.DataInputStream dis,
                           int marshalver)
                    throws java.io.IOException

Description copied from class: CDBObject

override this to unmarshal your data, just like unmarshal.

Overrides:

cpunmarshal in class CDBFileSysObject

Parameters:

dis - The stream to unmarshal from

marshalver - The marshal version of the data in src - i.e. the version of this class which wrote the data. This may be different from the current marshalVersion. If so (i.e. the stored data is the wrong version) your method should allow for it. This allows comparatively painless data migration between versions of your objects.

Throws:

java.io.IOException - if this breaks (breaks the CDB too).

setMimeRegistry

public static void setMimeRegistry(MimeRegistry mimeReg)

Sets the MimeRegistry to use when determining compressibility. If none is provided, CDBFile assumes that all types are of unknown compressibility and acts accordingly.

setTrialZipSizeLimits

public static void setTrialZipSizeLimits(long lower,
                                         long upper)

When inserting a file of unknown compressibility, CDBFile will attempt to compress it anyway provided that its size lies between a pair of limits. (Below some lower limit, there's probably not enough material for the compressor to get its teeth into; above some upper limit, it'll waste too much time if the compression fails.) This sets the limits. Although the parameters are longs, in practice sound values will be much smaller - a few K for the lower limit, a few hundred K for the upper. (Possibly for larger values of "a few" in the latter case). The defaults are probably reasonable in most cases.