|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object ccs.cdb.CDBeeTree
public class CDBeeTree
CDBeeTree provides a persistent object store (a "CDB") based on the encrypted,
concurrent BLOB persistence provided by BeeTree
. See the
package description for an explanation of the "CDB" prefix.
CDBeeTree's type separation system is based on the notion of "sets". A set,
as used here, is a collection of classes - here called sub-classes -
which are all assignable from (ie. are, or are subclasses of) a single
set class. The set class must be a subclass of CDBObject
.
All objects which are instances of classes in the same set - informally,
we say below that the object is "a member of" the class, although strictly
the member is the object's class, not the object itself - share the same
key space, which is separate from the key space of any other set (in that CDB
or another). In other words, two objects in different sets can have the same
key without there being a clash.
To retrieve an object which belongs to a set which contains several sub-classes,
use find / next / prev in the usual way. However, the parameter object
you supply (which is to be populated with the state of the retrieved object)
may be an instance of any sub-class in the set. If the supplied object is not
of the same class as the object to be retrieved, a "clone" object is created
and populated (unmarshalled) instead, and made available as the
clone member of
CDBObject
.
CDBObject
s all define their own marshal versions.
When marshalling a CDBObject
for storage, the latest version
is always stored. When unmarshalling, the unmarshal method is given the
marshal version which was used to marshal. In this way objects can transparently
evolve over time: as each object is read out of the CDB and written back in,
the object is automatically upgraded.
Most methods are marked as throwing IOException
. In particular, you
may expect:
BeeException
: A minor problem, such as object not
found. (Clearly, this may represent a more serious problem from the
point of view of your application!).ConsistencyException
: A serious problem, such as
database corruption.IOException
and variants: miscellaneous IO problems,
mostly thrown by the Java runtime. Apart from FileNotFoundException,
exceptions due to insufficient priviliege on multi-user systems and
others which are clearly due to misconfiguration, these indicate a fault
and should be taken as seriously as an ConsistencyException.
CDBObject
,
BeeTree
Constructor Summary | |
---|---|
CDBeeTree(java.io.File f,
byte[] password,
boolean create)
Create a new CDBeeTree indexing the supplied File. |
Method Summary | ||
---|---|---|
|
addAutoSet(java.lang.Class<T> setClass)
Add a set, then add the set class as its own sub-class. |
|
void |
addSet(java.lang.Class setClass)
Add a new set to the CDB. |
|
|
addSubClass(java.lang.Class<T> setClass,
java.lang.Class<? extends T> subClass)
Add a new sub-class to an existing set of the CDB. |
|
|
assertAutoSet(java.lang.Class<T> setClass)
Add a set, then add the set class as its own sub-class, only as required. |
|
|
assertSet(java.lang.Class<T> setClass,
java.lang.Class<? extends T> subClass)
Add a set and one of its sub-classes, only as required. |
|
void |
changeKey(CDBObject cdbo,
java.lang.String newkey)
Changes the key of the supplied object. |
|
void |
delete(CDBObject cdbo)
Deletes the supplied object from the CDB. |
|
void |
delSet(java.lang.Class setClass,
BeeTreeObserver bto,
int wipeMode)
Delete a set, and all objects within the CDB which belong to that set. |
|
void |
delSubClass(java.lang.Class setClass,
java.lang.Class subClass,
BeeTreeObserver bto,
int wipeMode)
Delete a sub-class from a set, and all objects within the CDB which belong to that sub-class. |
|
void |
dumpSets(java.io.PrintStream out)
Print the set structure out. |
|
void |
eviscerate(boolean isWipe,
boolean isRemoveMeta)
Removes all objects from the CDB, and optionally removes the set structure as well. |
|
boolean |
findExact(CDBObject cdbo)
Finds an object from an exact key. |
|
boolean |
findExactKey(CDBObject cdbo)
As findExact , except that the object is not unmarshalled. |
|
boolean |
findFirst(CDBObject cdbo)
Finds an object from a partial key. |
|
boolean |
findFirstKey(CDBObject cdbo)
As findFirst , except that the object is not unmarshalled. |
|
BeeTree |
getBeeTree()
Returns the underlying BeeTree blob-persister object. |
|
Cipher |
getCipherInstance()
Returns a new, uninitialised instance of the Cipher corresponding to the current Cipher version. |
|
java.io.File |
getContainingFile()
Returns the File containing the CDB. |
|
Cipher |
getNullCipherInstance()
Returns a new, uninitialised instance of the Cipher the tree uses when it's not actually encrypted. |
|
byte[] |
getPassword()
returns a copy of the current password, if any. |
|
long |
getTotalFree()
Returns the total amount of free space inside the CDB. |
|
int |
getTotalSpaces()
Returns the number of free spaces inside the CDB. |
|
boolean |
hasSet(java.lang.Class setClass)
Whether a set is already in the CDB. |
|
boolean |
hasSubClass(java.lang.Class setClass,
java.lang.Class subClass)
Whether the specified set exists, and has the specified class as a sub-class - see addSubClass and the opening essay. |
|
void |
insert(CDBObject cdbo)
Inserts an object into the CDB. |
|
java.lang.Class[] |
listSetClasses()
Retuns a list of the set classes present in this CDB. |
|
java.lang.Class[] |
listSubClasses(java.lang.Class setClass)
Returns a list of the sub-classes of a given set of this CDB. |
|
boolean |
next(CDBObject cdbo)
Find the next object. |
|
boolean |
nextKey(CDBObject cdbo)
As next , except the CDBObject is not unmarshalled. |
|
boolean |
nextMatch(CDBObject cdbo)
Find the next object which matches the partial key from the most recent findFirst . |
|
boolean |
nextMatchKey(CDBObject cdbo)
As nextMatch , except that the object is not unmarshalled. |
|
boolean |
prev(CDBObject cdbo)
Find the previous object, as next . |
|
boolean |
prevKey(CDBObject cdbo)
Find the previous object but don't unmarshal, as nextKey . |
|
void |
reloadMetadata()
Reload set-management information for this CDBeeTree. |
|
void |
setNodeCacheSize(int size)
Changes the size of the node cache. |
|
void |
setThreshold(int threshold)
Changes the swapping threshold for temporary space when marshalling. |
|
void |
threadLock()
Lock the underlying beetree so that only this thread in this VM can use it; all other threads in all other VMs are locked out. |
|
void |
threadLockRO()
As threadLock , but only acquires an RO lock. |
|
void |
threadUnlock()
Release the beetree from your previously-applied thread lock. |
|
void |
threadUnlockRO()
Release the CDBeeTree from your previously-applied RO thread lock. |
|
void |
update(CDBObject cdbo)
Updates the object, which is already in the CDB. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public CDBeeTree(java.io.File f, byte[] password, boolean create) throws java.io.IOException
BeeTree
)
encrypts the CDB; if zero-length a null cipher is applied. Applying strong
encryption is little slower than applying null encryption.
f
- The disk file to contain the BeeTree.password
- The password for the BeeTree, supplied as a set of bytes. If
your app is using a string, think about character encoding. Supply
null to not use encryption.create
- If true, create a new CDB. Any existing file will be
wiped. If you don't want to bother with wiping, delete it yourself.
If false, read in details from an existing CDB.
java.io.IOException
- See opening discussion.Method Detail |
---|
public boolean hasSet(java.lang.Class setClass) throws DeadlockException
DeadlockException
public void addSet(java.lang.Class setClass) throws java.io.IOException
reloadMetadata
invoked on them for the change to take effect.
You may find assertSet
more convenient.
setClass
- The set class to add.
java.io.IOException
- See opening discussion.CDBObject
public boolean hasSubClass(java.lang.Class setClass, java.lang.Class subClass) throws DeadlockException
addSubClass
and the opening essay.
DeadlockException
public <T extends CDBObject> void addSubClass(java.lang.Class<T> setClass, java.lang.Class<? extends T> subClass) throws java.io.IOException
reloadMetadata
invoked on them for the change to take effect.
setClass
- The set class of the set to which the sub-class will be added.subClass
- the sub-class to add.
java.io.IOException
- See opening discussion.public <T extends CDBObject> void addAutoSet(java.lang.Class<T> setClass) throws java.io.IOException
reloadMetadata
invoked on them for the
change to take effect.
setClass
- The set class.
java.io.IOException
- See opening discussion.public <T extends CDBObject> boolean assertAutoSet(java.lang.Class<T> setClass) throws java.io.IOException
reloadMetadata
invoked on
them for the change to take effect.
setClass
- The set class of the set to create, if need be.
java.io.IOException
- See opening discussion.public <T extends CDBObject> boolean assertSet(java.lang.Class<T> setClass, java.lang.Class<? extends T> subClass) throws java.io.IOException
addSet
/ addSubClass
throw if the elements pre-exist). Utility method. If this causes a change
(ie. the set wasn't there already) then any other CDBeeTree objects looking
at this CDB must have reloadMetadata
invoked on them for the
change to take effect.
setClass
- The set class of the set to create, if need be.subClass
- the sub-class to add to the set, if need be.
java.io.IOException
- See opening discussion.public void delSet(java.lang.Class setClass, BeeTreeObserver bto, int wipeMode) throws java.io.IOException
reloadMetadata
invoked on them immediately after - otherwise
they might create objects of the deleted set, which would cause problems later.
setClass
- the set class of the set to be deleted.bto
- An optional BeeTreeObserver
which can monitor the
compaction process.wipeMode
- A constant from ccs.utils.FileKiller
, dictating how
thoroughly the old database is to be wiped.
java.io.IOException
- See opening discussion.public void delSubClass(java.lang.Class setClass, java.lang.Class subClass, BeeTreeObserver bto, int wipeMode) throws java.io.IOException
reloadMetadata
invoked on them
immediately after - otherwise they might create objects of the deleted
sub-class, which would cause problems later.
setClass
- the set class whose sub-class is to be deleted.subClass
- the sub-class which is to be deleted.bto
- An optional BeeTreeObserver
which can monitor the
compaction process.wipeMode
- A constant from ccs.utils.FileKiller
, dictating how
thoroughly the old database is to be wiped.
java.io.IOException
- See opening discussion.public java.lang.Class[] listSetClasses() throws DeadlockException
DeadlockException
public java.lang.Class[] listSubClasses(java.lang.Class setClass) throws DeadlockException
setClass
- The setclass whose subclasses are to be listed.
DeadlockException
public void eviscerate(boolean isWipe, boolean isRemoveMeta) throws java.io.IOException
isWipe
- Whether to attempt to wipe the underlying file. The wipe is a
rather limited single-pass wipe; for greater security you should use
BeeTreeCompactor
with a multipass FileKiller mode, instead of this
method.isRemoveMeta
- Whether to remove the metadata (set structure) as well as
all objects.
java.io.IOException
public void reloadMetadata() throws java.io.IOException
addSet
etc.
java.io.IOException
public BeeTree getBeeTree()
public void dumpSets(java.io.PrintStream out) throws java.io.IOException
out
- The stream to dump to. If null, System.out
is used.
java.io.IOException
- if out
throws.public void insert(CDBObject cdbo) throws java.io.IOException
cdbo
- The object to insert.
java.io.IOException
- if there was a problem - see opening essay.public void update(CDBObject cdbo) throws java.io.IOException
cdbo
- The object to update.
java.io.IOException
- if there was a problem - see opening essay.public void delete(CDBObject cdbo) throws java.io.IOException
cdbo
- the object to delete.
java.io.IOException
- if there was a problem - see opening essay.public void changeKey(CDBObject cdbo, java.lang.String newkey) throws java.io.IOException
setKey
method (and hence the cpsetKey
method) will be
called on cdbo
to change the key. The app is responsible for
any other action required to bring the object up to date.
Since the object is not marshalled or unmarshalled during the process,
niether preMarshal
or preUnmarshal
will be invoked
on it by this method.
cdbo
- The object to update.newkey
- The new key.
java.io.IOException
- if there was a problem - see opening essay.public boolean findFirst(CDBObject cdbo) throws java.io.IOException
findFirst
,
next
and prev
will find the next and previous records
(and can be applied iteratively).
cdbo
- a CDBObject
of the required set, containing the
partial key.
java.io.IOException
- if there was a problem - see opening essay.public boolean findFirstKey(CDBObject cdbo) throws java.io.IOException
findFirst
, except that the object is not unmarshalled.
For finding keys, when not concerned with the objects.
cdbo
- a CDBObject
of the required set, containing the
partial key.
java.io.IOException
- if there was a problem - see opening essay.public boolean findExact(CDBObject cdbo) throws java.io.IOException
findFirst
.
After a findExact
, next
and prev
will
find the next and previous records. (and can be applied iteratively).
cdbo
- a CDBObject
of the required set, containing the key.
java.io.IOException
- if there was a problem - see opening essay.public boolean findExactKey(CDBObject cdbo) throws java.io.IOException
findExact
, except that the object is not unmarshalled.
For finding keys, when not concerned with the objects.
cdbo
- a CDBObject
of the required set, containing the key.
java.io.IOException
- if there was a problem - see opening essay.public boolean next(CDBObject cdbo) throws java.io.IOException
find
. If the search fails
(as in 'returns false', not as in 'throws an exception') the current-record
pointer remains unchanged.
cdbo
- a blank CDBBObject of the correct set.
java.io.IOException
- if there was a problem - see opening essay.public boolean nextKey(CDBObject cdbo) throws java.io.IOException
next
, except the CDBObject is not unmarshalled. For finding
keys, when not concerned with the objects they index.
cdbo
- a blank CDBBObject of the correct set.
java.io.IOException
- if there was a problem - see opening essay.public boolean nextMatch(CDBObject cdbo) throws java.io.IOException
findFirst
. Returns as next. If the operation returns false, the
current-record pointer remains unchanged. There is no prevMatch because the
process is asymmetrical - prevMatch would be twinned with findLast, and that
is not implemented either. (It could be, were there enough demand).
cdbo
- a blank CDBBObject of the correct set.
java.io.IOException
- if there was a problem - see opening essay.public boolean nextMatchKey(CDBObject cdbo) throws java.io.IOException
nextMatch
, except that the object is not unmarshalled.
cdbo
- a blank CDBBObject of the correct set.
java.io.IOException
- if there was a problem - see opening essay.public boolean prev(CDBObject cdbo) throws java.io.IOException
next
.
cdbo
- a blank CDBBObject of the correct set.
java.io.IOException
- if there was a problem - see opening essay.public boolean prevKey(CDBObject cdbo) throws java.io.IOException
nextKey
.
cdbo
- a blank CDBBObject of the correct set.
java.io.IOException
- if there was a problem - see opening essay.public void threadLock() throws java.io.IOException
Apps should ensure that the lock is released; generally this is best done using a try...finally block.
This call will block until such a lock can be obtained.
java.io.IOException
- if there was a problem with disk I/O.public void threadUnlock() throws java.lang.IllegalStateException, java.io.IOException
java.lang.IllegalStateException
- if this thread does not hold the lock.
java.io.IOException
- if there was a problem with disk I/O.public void threadLockRO() throws java.io.IOException
threadLock
, but only acquires an RO lock. Improves
multithread concurrency, but you do need to make sure that your transaction
doesn't do any write operations. Don't nest RO and RW thread locks.
java.io.IOException
public void threadUnlockRO() throws java.io.IOException
java.io.IOException
public long getTotalFree() throws ConsistencyException
ConsistencyException
- If the BeeTree is invalid.public int getTotalSpaces() throws ConsistencyException
Known bug: the free list is not written back properly. See getTotalFree
ConsistencyException
- If the BeeTree is invalid.public void setThreshold(int threshold)
threshold
- The threshold.public java.io.File getContainingFile()
public byte[] getPassword()
public void setNodeCacheSize(int size)
public Cipher getCipherInstance()
public Cipher getNullCipherInstance()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |