ItemSubspaces

Previous Next

Subspaces are Simple

A subspace, is a set of Items that are the suffixes for the Items having a given prefix in an ItemSpace. An 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.

Uses

Why is the ItemSpace idea so important? One application will hopefully become clear in the next section, AndOrSpaces, where we show a simple query. In that application, multiple 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.

Subspace Set Operations

The 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:

methoddescription
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.

Previous Next


Copyright © 1997-2006 Boiler Bay.