public abstract class NameSpace
extends java.lang.Object
NameSpace
class provides access to the persistent storage
system.The persistent storage system is designed to store searchable information between JDeveloper sessions. This information is stored using a NameSpace. Each NameSpace consists of a set of records which are accessed by a String key. Each record is stored as a byte[]. Both the key and the data array are of arbitrary size. All users of a specific NameSpace must coordinate to ensure that their keys are unique.
By default, all NameSpace instances stored in a single storage file
in the user system directory. It is also possible to create a local
NameSpace in a specific location using
getLocalNameSpace()
.
If multiple instances of JDeveloper (on the same machine or not) attempt to use the same storage file at the same time, multiple storage files will be created with sequential names. For example:
XXXX_N.stf
where XXXX is the base storage name and N a number.
Modifier and Type | Field and Description |
---|---|
protected java.lang.String |
_name
The name of this namespace.
|
static int |
NSTYPE_NORMAL
Type constant for a normal namespace.
|
static int |
NSTYPE_PACKED
Type constant for a packed namespace.
|
Constructor and Description |
---|
NameSpace(java.lang.String name) |
Modifier and Type | Method and Description |
---|---|
abstract void |
cancelAutoFlush()
Cancel auto-flushing for this NameSpace.
|
static boolean |
canOpen(java.lang.String location)
Determine whether storage files can be opened from the given location.
|
abstract boolean |
checkRecord(java.lang.String key)
Check if a key is present in the current namespace
|
static void |
clearStorage(java.lang.String location)
Deprecated.
Replaced by
closeStorage(java.lang.String) |
void |
close()
Close this NameSpace instance.
|
static void |
closeStorage(java.lang.String location)
Close the storage file at the given location.
|
static void |
deleteLocalNameSpace(java.lang.String location,
java.lang.String name)
Permanently delete the NameSpace with the given name at the given
location, and all records contained within it.
|
static void |
deleteLocalNameSpace(java.lang.String location,
java.lang.String name,
java.util.Collection<java.lang.String> secondaryKeys)
Permanently delete the NameSpace with the given name at the given
location, and all records contained within it, as well as any secondary
key data.
|
static void |
deleteNameSpace(java.lang.String name)
Permanently delete the NameSpace with the given name, and all
records contained within it.
|
static void |
deleteNameSpace(java.lang.String name,
java.util.Collection<java.lang.String> secondaryKeys)
Permanently delete the NameSpace with the given name, and all
records contained within it, as well as any secondary key data.
|
abstract void |
delRecord(java.lang.String key)
Delete the record associated with the key, and remove the key itself.
|
abstract void |
flush()
Saves all pending operations to disk, and marks the NameSpace
'clean'.
|
java.util.Iterator<java.lang.String> |
getKeyIterator()
Get an iterator over all keys contained in this NameSpace.
|
java.util.Iterator<java.lang.String> |
getKeyIterator(java.lang.String prefix)
Get an iterator over all keys contained in this NameSpace,
with the given prefix.
|
abstract java.util.Iterator<java.lang.String> |
getKeyIterator(java.lang.String prefix,
boolean ignorecase)
Get an iterator over all keys contained in this NameSpace,
with the given prefix, optionally ignoring case.
|
static NameSpace |
getLocalNameSpace(java.lang.String location,
java.lang.String name)
Get a NameSpace instance with the given name, at the given
location.
|
static NameSpace |
getLocalNameSpace(java.lang.String location,
java.lang.String name,
int type)
Get a NameSpace instance with the given name and type, at the
given location.
|
static NameSpace |
getLocalNameSpace(java.lang.String location,
java.lang.String name,
int type,
SecondaryKeyProvider provider)
Get a local namespace that uses secondary keys.
|
static NameSpace |
getLocalNameSpace(java.lang.String location,
java.lang.String name,
SecondaryKeyProvider provider)
Get a local namespace that uses secondary keys.
|
static java.util.Iterator<java.lang.String> |
getLocalNameSpaceIterator(java.lang.String location,
java.lang.String prefix,
boolean ignorecase)
Returns an iterator over all namespace names in the given storage file
that start with the given prefix, optionally ignoring case.
|
static java.util.Iterator<java.lang.String> |
getLocalReverseNameSpaceIterator(java.lang.String location,
java.lang.String prefix,
boolean ignorecase)
Returns an iterator over all namespace names in the given storage file
that start with the given prefix, in reverse order, optionally ignoring
case.
|
java.lang.String |
getName()
Get the name of this NameSpace.
|
static NameSpace |
getNameSpace(java.lang.String name)
Get a NameSpace instance with the given name.
|
static NameSpace |
getNameSpace(java.lang.String name,
int type)
Get a NameSpace instance with the given name and type.
|
static NameSpace |
getNameSpace(java.lang.String name,
SecondaryKeyProvider provider)
Get a
NameSpace instance that uses secondary keys. |
static NameSpaceFactory |
getNameSpaceFactory()
Get the namespace factory.
|
static java.util.Iterator<java.lang.String> |
getNameSpaceIterator()
Returns an iterator over all namespace names in the default storage file.
|
static java.util.Iterator<java.lang.String> |
getNameSpaceIterator(java.lang.String prefix)
Returns an iterator over all namespace names in the default storage file
that start with the given prefix.
|
static java.util.Iterator<java.lang.String> |
getNameSpaceIterator(java.lang.String prefix,
boolean ignorecase)
Returns an iterator over all namespace names in the default storage file
that start with the given prefix, optionally ignoring case.
|
abstract java.lang.String |
getPrimaryKey(java.lang.String secondaryKeyName,
java.lang.String secondaryKey)
Get the primary key associated with a secondary key.
|
abstract java.util.Collection<java.lang.String> |
getPrimaryKeys(java.lang.String secondaryKeyName,
java.lang.String secondaryKey)
Get all primary keys associated with a secondary key.
|
abstract byte[] |
getRecord(java.lang.String key)
Get the data associated with the given key.
|
abstract byte[] |
getRecord(java.lang.String secondaryKeyName,
java.lang.String secondaryKey)
Get the record associated with a secondary key.
|
abstract java.util.Collection<byte[]> |
getRecords(java.lang.String secondaryKeyName,
java.lang.String secondaryKey)
Get all records associated with a secondary key.
|
abstract java.io.InputStream |
getRecordStream(java.lang.String key)
Returns a stream for reading the data associated with a key.
|
java.util.Iterator<java.lang.String> |
getReverseKeyIterator()
Get an iterator over all keys contained in this NameSpace,
in reverse order.
|
java.util.Iterator<java.lang.String> |
getReverseKeyIterator(java.lang.String prefix)
Get an iterator over all keys contained in this NameSpace,
with the given prefix, in reverse order.
|
abstract java.util.Iterator<java.lang.String> |
getReverseKeyIterator(java.lang.String prefix,
boolean ignorecase)
Get an iterator over all keys contained in this NameSpace,
with the given prefix, in reverse order, optionally ignoring case.
|
static java.util.Iterator<java.lang.String> |
getReverseNameSpaceIterator()
Returns an iterator over all namespace names in the default storage file,
in reverse order.
|
static java.util.Iterator<java.lang.String> |
getReverseNameSpaceIterator(java.lang.String prefix)
Returns an iterator over all namespace names in the default storage file
that start with the given prefix, in reverse order.
|
static java.util.Iterator<java.lang.String> |
getReverseNameSpaceIterator(java.lang.String prefix,
boolean ignorecase)
Returns an iterator over all namespace names in the default storage file
that start with the given prefix, in reverse order, optionally ignoring
case.
|
abstract void |
putRecord(java.lang.String key,
byte[] data)
Add or update the record associated with the key.
|
abstract void |
putRecord(java.lang.String key,
byte[] data,
int offset,
int size)
Add or update the record associated with the key.
|
abstract java.io.OutputStream |
putRecordStream(java.lang.String key)
Add or update the record associated with the key using a stream
To effectively enter the record the close() function have to be called on
this OutputStream.
|
abstract void |
setAutoFlush(long delay)
Sets the auto-flush delay for this NameSpace.
|
static void |
setNameSpaceFactory(NameSpaceFactory factory)
Set the factory used to create
NameSpace instances. |
abstract void |
visitRecords(NameSpaceVisitor visitor)
Visit the records in this namespace.
|
public static final int NSTYPE_NORMAL
public static final int NSTYPE_PACKED
protected final java.lang.String _name
public static void setNameSpaceFactory(NameSpaceFactory factory)
NameSpace
instances.factory
- the NameSpace
factorypublic static NameSpaceFactory getNameSpaceFactory()
public static java.util.Iterator<java.lang.String> getNameSpaceIterator()
public static java.util.Iterator<java.lang.String> getReverseNameSpaceIterator()
public static java.util.Iterator<java.lang.String> getNameSpaceIterator(java.lang.String prefix)
prefix
- the prefixpublic static java.util.Iterator<java.lang.String> getReverseNameSpaceIterator(java.lang.String prefix)
prefix
- the prefixpublic static java.util.Iterator<java.lang.String> getNameSpaceIterator(java.lang.String prefix, boolean ignorecase)
For performance reasons, if ignorecase is true, this iterator will return the first matching group of keys matching this prefix. For example, if the namespaces are:
AAA, BBB, BBb, Bbb, Cxx, aaa, bBB, bbB
This iterator will have no more elements once the prefix changes. getNameSpaceIterator("bb", true), will return only 3 keys:
BBB, BBb, Bbb
prefix
- the prefixignorecase
- whether to ignore casepublic static java.util.Iterator<java.lang.String> getReverseNameSpaceIterator(java.lang.String prefix, boolean ignorecase)
For performance reasons, if ignorecase is true, this iterator will return the first matching group of keys matching this prefix. For example, if the namespaces are:
AAA, BBB, BBb, Bbb, Cxx, aaa, bBB, bbB
This iterator will have no more elements once the prefix changes. getNameSpaceIterator("bb", true), will return only 2 keys:
bbB, bBB
prefix
- the prefixignorecase
- whether to ignore casepublic static java.util.Iterator<java.lang.String> getLocalNameSpaceIterator(java.lang.String location, java.lang.String prefix, boolean ignorecase)
For performance reasons, if ignorecase is true, this iterator will return the first matching group of keys matching this prefix. For example, if the namespaces are:
AAA, BBB, BBb, Bbb, Cxx, aaa, bBB, bbB
This iterator will have no more elements once the prefix changes. getNameSpaceIterator("bb", true), will return only 3 keys:
BBB, BBb, Bbb
location
- the storage file locationprefix
- the prefixignorecase
- whether to ignore casepublic static java.util.Iterator<java.lang.String> getLocalReverseNameSpaceIterator(java.lang.String location, java.lang.String prefix, boolean ignorecase)
For performance reasons, if ignorecase is true, this iterator will return the first matching group of keys matching this prefix. For example, if the namespaces are:
AAA, BBB, BBb, Bbb, Cxx, aaa, bBB, bbB
This iterator will have no more elements once the prefix changes. getNameSpaceIterator("bb", true), will return only 2 keys:
bbB, bBB
location
- the storage file locationprefix
- the prefixignorecase
- whether to ignore casepublic static NameSpace getNameSpace(java.lang.String name)
If multiple threads access the same NameSpace, they should each have their own NameSpace instance to access it.
name
- the name of the NameSpace.public static NameSpace getNameSpace(java.lang.String name, int type)
If multiple threads access the same NameSpace, they should each have their own NameSpace instance to access it.
name
- the name of the NameSpace.type
- the type of namespace, either NSTYPE_NORMAL
or NSTYPE_PACKED
.public static NameSpace getNameSpace(java.lang.String name, SecondaryKeyProvider provider)
NameSpace
instance that uses secondary keys. The same
SecondaryKeyProvider
must be used every time this
NameSpace
is used to ensure data integrity.name
- the name of the NameSpace
provider
- the secondary key providerNameSpace
instancepublic static NameSpace getLocalNameSpace(java.lang.String location, java.lang.String name)
If multiple threads access the same NameSpace, they should each have their own NameSpace instance to access it.
location
- the location of the storage filename
- the name of the NameSpace.public static NameSpace getLocalNameSpace(java.lang.String location, java.lang.String name, int type)
If multiple threads access the same NameSpace, they should each have their own NameSpace instance to access it.
location
- the location of the storage filename
- the name of the NameSpace.type
- the type of namespace, either NSTYPE_NORMAL
or NSTYPE_PACKED
.public static NameSpace getLocalNameSpace(java.lang.String location, java.lang.String name, SecondaryKeyProvider provider)
SecondaryKeyProvider
must be used every time this
NameSpace
is used to ensure data integrity.location
- the location of the storage filesname
- the name of the NameSpace
provider
- the secondary key providerNameSpace
instancepublic static NameSpace getLocalNameSpace(java.lang.String location, java.lang.String name, int type, SecondaryKeyProvider provider)
SecondaryKeyProvider
must be used every time this
NameSpace
is used to ensure data integrity.location
- the location of the storage filesname
- the name of the NameSpace
type
- the type of namespace, either NSTYPE_NORMAL
or NSTYPE_PACKED
provider
- the secondary key providerNameSpace
instance@Deprecated public static void clearStorage(java.lang.String location)
closeStorage(java.lang.String)
public static boolean canOpen(java.lang.String location)
location
- the storage file locationtrue
if storage files can be opened from the location,
false
otherwisepublic static void closeStorage(java.lang.String location)
location
- the storage file locationpublic static void deleteNameSpace(java.lang.String name)
name
- the name of the NameSpace to be deleted.public static void deleteNameSpace(java.lang.String name, java.util.Collection<java.lang.String> secondaryKeys)
name
- the name of the NameSpace to be deleted.secondaryKeys
- the secondary keys associated with the namespacepublic static void deleteLocalNameSpace(java.lang.String location, java.lang.String name)
location
- the location of the storage filename
- the name of the NameSpace to be deleted.public static void deleteLocalNameSpace(java.lang.String location, java.lang.String name, java.util.Collection<java.lang.String> secondaryKeys)
location
- the location of the storage filename
- the name of the NameSpace to be deleted.secondaryKeys
- the secondary keys associated with the namespacepublic abstract java.io.InputStream getRecordStream(java.lang.String key)
key
- key of the record.null
if there is no record with that key.public abstract void setAutoFlush(long delay)
delay
- the new auto-flush delay.flush()
public abstract void cancelAutoFlush()
setAutoFlush(long)
,
flush()
public abstract byte[] getRecord(java.lang.String key)
key
- the key of the record.null
if there is no record with that key.public abstract byte[] getRecord(java.lang.String secondaryKeyName, java.lang.String secondaryKey)
secondaryKeyName
- the secondary key namesecondaryKey
- the secondary keynull
if there is no record with that keypublic abstract java.util.Collection<byte[]> getRecords(java.lang.String secondaryKeyName, java.lang.String secondaryKey)
secondaryKeyName
- the secondary key namesecondaryKey
- the secondary keypublic abstract java.lang.String getPrimaryKey(java.lang.String secondaryKeyName, java.lang.String secondaryKey)
secondaryKeyName
- the secondary key namesecondaryKey
- the secondary keynull
if there is no primary keypublic abstract java.util.Collection<java.lang.String> getPrimaryKeys(java.lang.String secondaryKeyName, java.lang.String secondaryKey)
secondaryKeyName
- the secondary key namesecondaryKey
- the secondary keypublic abstract void flush()
public void close()
public abstract void delRecord(java.lang.String key)
flush()
method must be used to save the changes.key
- key name of the record.flush()
public abstract java.io.OutputStream putRecordStream(java.lang.String key)
Warning, NameSpace.flush() doesn't automaticaly close all 'openned' OutputStream you have to call close() on them before fvlushing the NameSpace.
After this operation the NameSpace will be tagged 'dirty', use flush sometime.
key
- key name of the record.flush()
public abstract boolean checkRecord(java.lang.String key)
key
- key name of the record.public abstract void putRecord(java.lang.String key, byte[] data)
After this operation the NameSpace will be tagged 'dirty'. Use the
flush()
method to flush the changes to disk.
If data is null or have a 0 length, no space will be allocated to store the data. Get functions on this key will return either a 0 length array or an empty stream.
key
- key name of the record.data
- byte[] containing the data associated with the key.flush()
public abstract void putRecord(java.lang.String key, byte[] data, int offset, int size)
After this operation the NameSpace will be tagged 'dirty'. Use the
flush()
method to flush the changes to disk.
If data is null or have a 0 length, no space will be allocated to store the data. Get functions on this key will return either a 0 length array or an empty stream.
key
- key name of the record.data
- byte[] containing the data associated with the key.offset
- the offset in the byte array where the record starts.size
- the size of the record data in the byte array.flush()
public abstract void visitRecords(NameSpaceVisitor visitor) throws java.lang.Exception
visitor
- the visitorjava.lang.Exception
- if the visitor throws an exceptionpublic java.util.Iterator<java.lang.String> getKeyIterator()
public java.util.Iterator<java.lang.String> getReverseKeyIterator()
public java.util.Iterator<java.lang.String> getKeyIterator(java.lang.String prefix)
prefix
- the prefix of the wanted keys.public java.util.Iterator<java.lang.String> getReverseKeyIterator(java.lang.String prefix)
prefix
- the prefix of the wanted keys.public abstract java.util.Iterator<java.lang.String> getKeyIterator(java.lang.String prefix, boolean ignorecase)
For performance reasons, if ignorecase is true, this iterator will return the* first matching group of keys matching this prefix. for example if the keys are:
AAA, BBB, BBb, Bbb, Cxx, aaa, bBB, bbB
This iterator will have no more elements once the key prefix changes. getKeyIterator("bb", true), will return only 3 keys:
BBB, BBb, Bbb
prefix
- the prefix of the desired keys.ignorecase
- whether to ignore case.public abstract java.util.Iterator<java.lang.String> getReverseKeyIterator(java.lang.String prefix, boolean ignorecase)
For performance reasons, if ignorecase is true, this iterator will return the* first matching group of keys matching this prefix. for example if the keys are:
AAA, BBB, BBb, Bbb, Cxx, aaa, bBB, bbB
This iterator will have no more elements once the key prefix changes. getKeyIterator("bb", true), will return only 2 keys:
bbB, BBb, bBB
prefix
- the prefix of the desired keys.ignorecase
- whether to ignore case.public java.lang.String getName()