ItemSubspace is an ItemSpace subclass that wraps
another ItemSpace called the superspace
in order to provide a subspace view based on a fixed
prefix. The view into the ItemSubspace is of a
subspace of the Items visible in the superspace. In other
words, every Item in the ItemSubspace is a
suffix of an Item in the superspace having the given fixed
prefix.
Here is how to create an ItemSubspace:
// cu already has been allocated
cu.clear().append("some prefix");
// db is an existing ItemSpace, such as the InfinityDB itself
ItemSubspace subspace = new ItemSubspace(db, cu);
The db parameter is the superspace or
base ItemSpace.
The ItemSubspace can be used in any situation
needing an ItemSpace: it is a first-class citizen, and it can be
modified or accessed in the same ways. Every retrieval acts by
temporarily prepending the prefix to the supplied Cu (in a temporary Cu), then
accessing the base space with the longer Item, and finally
copying the changed suffix of the longer Item back into the
Cu parameter if necessary. Updates are similar: a longer Item is
temporarily created and inserted, deleted, or updated. There is only a small
performance penalty for this because it is fast to copy data
between Cu's (System.arraycopy() is used), and the retrievals
and updates on the base space are dominant.
Note that close(), commit(),
rollback() and other operations are
passed on directly to the superspace.
ItemSubpaces are
used as inputs to set operations. But anywhere a set of
things is to be represented, we can keep them inside a
subspace (i.e. prepend a common prefix) and
optionally use an ItemSubspace
to simplify access to them.
ItemSpace class, which is the superset for
InfinityDB and all other ItemSpaces, provides various set-oriented
operations to simplify working with subspaces. In these
operations, when a prefix is supplied as an Object,
it can be anything that can be appended to a Cu.
(This includes the primitive wrappers,
String, Date, small byte[], small char[],
implementers of CuAppendable such as
Cu and Objects of classes which
represent the other
basic component types.)
These methods have default ItemSpace implementations but
are overridden in subclasses when the efficiency can be
improved. The source ItemSpaces are not modified. The methods
return this for chaining.
Here are some of the set operations:
| method | description |
|---|---|
ItemSpace clear() |
delete all Items in this ItemSpace |
ItemSpace deleteSubspace(Object prefix) |
delete all Items starting with prefix |
ItemSpace copyFrom(ItemSpace src) |
logically clear this ItemSpace, then copy all Items from src into this ItemSpace |
ItemSpace copyFrom(Object destPrefix, ItemSpace srcSpace, Object srcPrefix) |
logically do deleteSubspace(destPrefix), then
copy the subspace from src into this. Items starting with srcPrefix
in srcSpace are 'reprefixed' to have destPrefix in this ItemSpace.
srcSpace is not changed. |
ItemSpace intersect(ItemSpace srcSpace) |
Remove Items in this ItemSpace not in srcSpace. |
ItemSpace intersect(
Object destPrefix,
ItemSpace srcSpace, Object srcPrefix) |
Remove Items in this ItemSpace not corresponding to Items in the source subspace |
ItemSpace union(ItemSpace srcSpace) |
Add to this ItemSpace all Items from srcSpace. srcSpace is not changed. |
ItemSpace union(Object destPrefix, ItemSpace srcSpace, Object srcPrefix) |
Add to this ItemSpace all corresponding Items from the source subspace. Items starting with srcPrefix in srcSpace are 'reprefixed' to have destPrefix when they are put into this ItemSpace. srcSpace is not changed. |
ItemSpace difference(ItemSpace srcSpace) |
Remove Items from this ItemSpace that are in srcSpace. srcSpace is not changed. |
ItemSpace difference(Object destPrefix, ItemSpace srcSpace,
Object srcPrefix) |
Remove Items from this ItemSpace corresponding to Items in srcSpace. Items starting with srcPrefix in srcSpace are 'reprefixed' to have destPrefix as they are removed from this ItemSpace. srcSpace is not changed. |