Oracle Fusion Middleware Java API Reference for Oracle Extension SDK Reference
11g Release 1 (11.1.1)

E13403-03

oracle.ide.persistence
Class NameSpace

java.lang.Object
  extended by oracle.ide.persistence.NameSpace

public abstract class NameSpace
extends java.lang.Object

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


Field Summary
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 Summary
NameSpace(java.lang.String name)
           
 
Method Summary
abstract  void cancelAutoFlush()
          Cancel auto-flushing for this NameSpace.
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 deleteNameSpace(java.lang.String name)
          Permanently delete the NameSpace with the given name, and all records contained within it.
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  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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NSTYPE_NORMAL

public static final int NSTYPE_NORMAL
Type constant for a normal namespace.

See Also:
Constant Field Values

NSTYPE_PACKED

public static final int NSTYPE_PACKED
Type constant for a packed namespace.

See Also:
Constant Field Values

_name

protected final java.lang.String _name
The name of this namespace.

Constructor Detail

NameSpace

public NameSpace(java.lang.String name)
Method Detail

setNameSpaceFactory

public static void setNameSpaceFactory(NameSpaceFactory factory)
Set the factory used to create NameSpace instances.

Parameters:
factory - the NameSpace factory

getNameSpaceFactory

public static NameSpaceFactory getNameSpaceFactory()
Get the namespace factory.

Returns:
the namespace factory

getNameSpaceIterator

public static java.util.Iterator<java.lang.String> getNameSpaceIterator()
Returns an iterator over all namespace names in the default storage file.

Returns:
an iterator over all namespace names in the default storage file.

getReverseNameSpaceIterator

public static java.util.Iterator<java.lang.String> getReverseNameSpaceIterator()
Returns an iterator over all namespace names in the default storage file, in reverse order.

Returns:
an iterator over all namespace names in the default storage file, in reverse order.

getNameSpaceIterator

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

Parameters:
prefix - the prefix
Returns:
an iterator over all namespace names in the default storage file that start with the given prefix.

getReverseNameSpaceIterator

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

Parameters:
prefix - the prefix
Returns:
an iterator over all namespace names in the default storage file that start with the given prefix, in reverse order.

getNameSpaceIterator

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

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

Parameters:
prefix - the prefix
ignorecase - whether to ignore case
Returns:
an iterator over all namespace names in the default storage file that start with the given prefix.

getReverseNameSpaceIterator

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

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

Parameters:
prefix - the prefix
ignorecase - whether to ignore case
Returns:
an iterator over all namespace names in the default storage file that start with the given prefix, in reverse order.

getLocalNameSpaceIterator

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

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

Parameters:
location - the storage file location
prefix - the prefix
ignorecase - whether to ignore case
Returns:
an iterator over all namespace names in the default storage file that start with the given prefix.

getLocalReverseNameSpaceIterator

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

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

Parameters:
location - the storage file location
prefix - the prefix
ignorecase - whether to ignore case
Returns:
an iterator over all namespace names in the default storage file that start with the given prefix, in reverse order.

getNameSpace

public static NameSpace getNameSpace(java.lang.String name)
Get a NameSpace instance with the given name. If the NameSpace does not exist, it will be created.

If multiple threads access the same NameSpace, they should each have their own NameSpace instance to access it.

Parameters:
name - the name of the NameSpace.
Returns:
the NameSpace instance.

getNameSpace

public static NameSpace getNameSpace(java.lang.String name,
                                     int type)
Get a NameSpace instance with the given name and type. If the NameSpace does not exist, it will be created.

If multiple threads access the same NameSpace, they should each have their own NameSpace instance to access it.

Parameters:
name - the name of the NameSpace.
type - the type of namespace, either NSTYPE_NORMAL or NSTYPE_PACKED.
Returns:
the NameSpace instance.

getNameSpace

public static NameSpace getNameSpace(java.lang.String name,
                                     SecondaryKeyProvider provider)
Get a NameSpace instance that uses secondary keys. The same SecondaryKeyProvider must be used every time this NameSpace is used to ensure data integrity.

Parameters:
name - the name of the NameSpace
provider - the secondary key provider
Returns:
the NameSpace instance

getLocalNameSpace

public static NameSpace getLocalNameSpace(java.lang.String location,
                                          java.lang.String name)
Get a NameSpace instance with the given name, at the given location. If the NameSpace does not exist, it will be created.

If multiple threads access the same NameSpace, they should each have their own NameSpace instance to access it.

Parameters:
location - the location of the storage file
name - the name of the NameSpace.
Returns:
the NameSpace instance.

getLocalNameSpace

public 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. If the NameSpace does not exist, it will be created.

If multiple threads access the same NameSpace, they should each have their own NameSpace instance to access it.

Parameters:
location - the location of the storage file
name - the name of the NameSpace.
type - the type of namespace, either NSTYPE_NORMAL or NSTYPE_PACKED.
Returns:
the NameSpace instance.

getLocalNameSpace

public static NameSpace getLocalNameSpace(java.lang.String location,
                                          java.lang.String name,
                                          SecondaryKeyProvider provider)
Get a local namespace that uses secondary keys. The same SecondaryKeyProvider must be used every time this NameSpace is used to ensure data integrity.

Parameters:
location - the location of the storage files
name - the name of the NameSpace
provider - the secondary key provider
Returns:
the NameSpace instance

getLocalNameSpace

public static NameSpace getLocalNameSpace(java.lang.String location,
                                          java.lang.String name,
                                          int type,
                                          SecondaryKeyProvider provider)
Get a local namespace that uses secondary keys. The same SecondaryKeyProvider must be used every time this NameSpace is used to ensure data integrity.

Parameters:
location - the location of the storage files
name - the name of the NameSpace
type - the type of namespace, either NSTYPE_NORMAL or NSTYPE_PACKED
provider - the secondary key provider
Returns:
the NameSpace instance

clearStorage

@Deprecated
public static void clearStorage(java.lang.String location)
Deprecated. Replaced by closeStorage(java.lang.String)


closeStorage

public static void closeStorage(java.lang.String location)
Close the storage file at the given location. It is the callers responsibility to ensure that no NameSpace instances from that location are in use before calling this method.

Parameters:
location - the storage file location

deleteNameSpace

public static void deleteNameSpace(java.lang.String name)
Permanently delete the NameSpace with the given name, and all records contained within it.

Parameters:
name - the name of the NameSpace to be deleted.

deleteLocalNameSpace

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

Parameters:
location - the location of the storage file
name - the name of the NameSpace to be deleted.

getRecordStream

public abstract java.io.InputStream getRecordStream(java.lang.String key)
Returns a stream for reading the data associated with a key.

Parameters:
key - key of the record.
Returns:
An opened InputStream on the data record, or null if there is no record with that key.

setAutoFlush

public abstract void setAutoFlush(long delay)
Sets the auto-flush delay for this NameSpace. This controls how frequently the NameSpace is automatically flushed to disk.

Parameters:
delay - the new auto-flush delay.
See Also:
flush()

cancelAutoFlush

public abstract void cancelAutoFlush()
Cancel auto-flushing for this NameSpace.

See Also:
setAutoFlush(long), flush()

getRecord

public abstract byte[] getRecord(java.lang.String key)
Get the data associated with the given key.

Parameters:
key - the key of the record.
Returns:
a byte[] containing the record data, or null if there is no record with that key.

getRecord

public abstract byte[] getRecord(java.lang.String secondaryKeyName,
                                 java.lang.String secondaryKey)
Get the record associated with a secondary key. If more than one record is associated with the key, the first one is returned.

Parameters:
secondaryKeyName - the secondary key name
secondaryKey - the secondary key
Returns:
the record data, or null if there is no record with that key

getRecords

public abstract java.util.Collection<byte[]> getRecords(java.lang.String secondaryKeyName,
                                                        java.lang.String secondaryKey)
Get all records associated with a secondary key.

Parameters:
secondaryKeyName - the secondary key name
secondaryKey - the secondary key
Returns:
the record data, or an empty collection if no primary keys match the secondary key

getPrimaryKey

public abstract java.lang.String getPrimaryKey(java.lang.String secondaryKeyName,
                                               java.lang.String secondaryKey)
Get the primary key associated with a secondary key. If more than one primary key is associated with the secondary key, the first one is returned.

Parameters:
secondaryKeyName - the secondary key name
secondaryKey - the secondary key
Returns:
the primary key, or null if there is no primary key

getPrimaryKeys

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

Parameters:
secondaryKeyName - the secondary key name
secondaryKey - the secondary key
Returns:
the primary keys matching the secondary key, or an empty collection if no primary keys match the secondary key

flush

public abstract void flush()
Saves all pending operations to disk, and marks the NameSpace 'clean'. If multiple threads are using the same NameSpace (using their own NameSpace instance), only the last flush will mark the NameSpace clean.


close

public void close()
Close this NameSpace instance.


delRecord

public abstract void delRecord(java.lang.String key)
Delete the record associated with the key, and remove the key itself. After this operation the NameSpace will be marked 'dirty'. The flush() method must be used to save the changes.

Parameters:
key - key name of the record.
See Also:
flush()

putRecordStream

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

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.

Parameters:
key - key name of the record.
Returns:
OutputStream on the datas associated with the key (use close to finalize the add / update).
See Also:
flush()

checkRecord

public abstract boolean checkRecord(java.lang.String key)
Check if a key is present in the current namespace

Parameters:
key - key name of the record.
Returns:
true if the key is conatined in the namespace, false otherwise

putRecord

public abstract void putRecord(java.lang.String key,
                               byte[] data)
Add or update the record associated with the key.

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.

Parameters:
key - key name of the record.
data - byte[] containing the data associated with the key.
See Also:
flush()

getKeyIterator

public java.util.Iterator<java.lang.String> getKeyIterator()
Get an iterator over all keys contained in this NameSpace.

Returns:
an iterator over all keys contained in this NameSpace.

getReverseKeyIterator

public java.util.Iterator<java.lang.String> getReverseKeyIterator()
Get an iterator over all keys contained in this NameSpace, in reverse order.

Returns:
an iterator over all keys contained in this NameSpace, in reverse order.

getKeyIterator

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

Parameters:
prefix - the prefix of the wanted keys.
Returns:
an iterator over all keys contained in this NameSpace with the given prefix.

getReverseKeyIterator

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

Parameters:
prefix - the prefix of the wanted keys.
Returns:
an iterator over all keys contained in this NameSpace, with the given prefix, in reverse order.

getKeyIterator

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

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

Parameters:
prefix - the prefix of the desired keys.
ignorecase - whether to ignore case.
Returns:
an iterator over all keys contained in this NameSpace with the given prefix.

getReverseKeyIterator

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

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

Parameters:
prefix - the prefix of the desired keys.
ignorecase - whether to ignore case.
Returns:
an iterator over all keys contained in this NameSpace with the given prefix.

getName

public java.lang.String getName()
Get the name of this NameSpace.

Returns:
the name of this NameSpace.

Oracle Fusion Middleware Java API Reference for Oracle Extension SDK Reference
11g Release 1 (11.1.1)

E13403-03

Copyright © 1997, 2009, Oracle. All rights reserved.