Context (Registry) - NetBeans API Javadoc (Current Development Version)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

org.netbeans.modules.registry/1 1.8

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.netbeans.api.registry
Class Context

java.lang.Object
  org.netbeans.api.registry.Context

public final class Context
extends Object
extends Object

This API class is representing a context which consists of a set of name-to-object bindings. It contains methods for examining and updating these bindings. The contexts are composed into hierarchical collection which form configuration system. The configuration system allows applicatioRootns to store and retrieve data. How data are stored is not specified by the Registry API. It is up to provided implementation of Registry SPI to properly document it and that documentation must be consulted.

The hierarchical collection of contexts is similar to folders in a hierarchical file system. There exist a root context containing all the contexts. The name of this context is "/" and it is also absolute name of the context. The names of individual contexts cannot be empty, but does not have to be unique. However, absolute name of the context must be unique. Children of the root context have absolute names of "/" + context name. All other contexts have absolute names of parent's context absolute name + "/" + context name.

The context can contain the subcontext and binding with the same name and they will coexist.

The context has getters and setters for all primitive data types, for a few basic object types (eg. Color, URL, etc.) and for Object. As was said above the storage format is specific per Registry SPI implementation, but following is valid for all backends:

primitive data types: the primitive data type is converted into corresponding object counterpart and the object is stored. Retrieval of the primitive value does the opposite: the object is retrieved and converted to primitive data type. Each context implementation must support storage of these data types.
supported basic object types: these object types in addition to basic data types must be persistable by all context implementations.
any other Object: it is up to specific Registry SPI implementation to document what is supported and how in this area.

Getters do not throw exceptions. They accept default value parameter which is returned if value does not exist or it could not be read. The exceptions are logged.

Putting null value removes the binding.

Rename of binding is not supported because no useful usecase was found.

All methods are properly synchronized and can be accessed from multiple threads without any synchronization on the client side. During the modification is whole hierarchy of contexts exclusively locked.

TBD: Names restrictions: length, valid characters, etc. The context name nor binding name cannot contain "/" character.

Method Summary

void addContextListener(ContextListener l)
          Add listener for receiving events about context and all its descendant subcontexts changes.

Context createSubcontext(String subcontextName)
          Create subcontext of the given name.

void destroySubcontext(String subcontextName)
          Destroy subcontext of the given name.

String getAbsoluteContextName()
          Getter for the absolute name of the context, eg.

String getAttribute(String bindingName, String attributeName, String defaultValue)
          Retrieve value of the attribute.

Collection getAttributeNames(String bindingName)
          Retrieve names of all attributes in this context.

Collection getBindingNames()
          Retrieve names of all bindings in this context.

boolean getBoolean(String bindingName, boolean defaultValue)
          Retrieve boolean value.

Color getColor(String bindingName, Color defaultValue)
          Retrieve color value.

String getContextName()
          Name of the context.

static Context getDefault()
          Getter for default instance of registry.

double getDouble(String bindingName, double defaultValue)
          Retrieve double value.

float getFloat(String bindingName, float defaultValue)
          Retrieve float value.

Font getFont(String bindingName, Font defaultValue)
          Retrieve font value.

int getInt(String bindingName, int defaultValue)
          Retrieve integer value.

long getLong(String bindingName, long defaultValue)
          Retrieve long value.

static Mutex getMutex()
          Shared Mutex on which all contexts are synchronized.

Object getObject(String bindingName, Object defaultValue)
          Retrieve named object from the context.

List getOrderedNames()
          Method listing ordered names of the context items.

List getOrderedObjects()
          Method for listing items of the context ordered.

Context getParentContext()
          Retrieve parent context.

ObjectRef getRef(String bindingName)
          Retrieve directly the bounded ObjectRef instance.

Context getRootContext()
          Gets root context.

String getString(String bindingName, String defaultValue)
          Retrieve String value.

String[] getStringArray(String bindingName, char separator, String[] defaultValue)
          Retrieve string array by reading stored string and splitting it by the given separator into array of Strings.

Context getSubcontext(String subcontextName)
          Retrieve subcontext of the given name.

Collection getSubcontextNames()
          Retrieve names of all subcontexts of this context.

URL getURL(String bindingName, URL defaultValue)
          Retrieve URL value.

boolean hasDefault(String bindingName)
          Exist a default value for this binding or context?

boolean isModified(String bindingName)
          Check whether the value of this binding or context is modified.

static Context merge(Context[] delegates)
          Returns context, that merges all its delegates.

void orderContext(List names)
          Store full order of the context content.

void putBoolean(String bindingName, boolean value)
          This method converts the passed boolean to Boolean object and binds it into context.

void putColor(String bindingName, Color value)
          This is just convenient method.

void putDouble(String bindingName, double value)
          This method converts the passed double to Double object and binds it into context.

void putFloat(String bindingName, float value)
          This method converts the passed float to Float object and binds it into context.

void putFont(String bindingName, Font value)
          This is just convenient method.

void putInt(String bindingName, int value)
          This method converts the passed integer to Integer object and binds it into context.

void putLong(String bindingName, long value)
          This method converts the passed long to Long object and binds it into context.

void putObject(String bindingName, Object value)
          Binds a name to an object and store the object in context.

void putString(String bindingName, String value)
          Binds a name to the String and store it in the context.

void putStringArray(String bindingName, char separator, String[] value)
          Store array of strings.

void putURL(String bindingName, URL value)
          This is just convenient method.

void removeContextListener(ContextListener l)
          Remove listener for receiving events about context and all its descendant subcontexts changes.

void revert(String bindingName)
          Revert modification of this binding or context.

void setAttribute(String bindingName, String attributeName, String value)
          Modify value of the attribute.

String toString()


Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Summary
`void`	`addContextListener(ContextListener l)` Add listener for receiving events about context and all its descendant subcontexts changes.
`Context`	`createSubcontext(String subcontextName)` Create subcontext of the given name.
`void`	`destroySubcontext(String subcontextName)` Destroy subcontext of the given name.
`String`	`getAbsoluteContextName()` Getter for the absolute name of the context, eg.
`String`	`getAttribute(String bindingName, String attributeName, String defaultValue)` Retrieve value of the attribute.
`Collection`	`getAttributeNames(String bindingName)` Retrieve names of all attributes in this context.
`Collection`	`getBindingNames()` Retrieve names of all bindings in this context.
`boolean`	`getBoolean(String bindingName, boolean defaultValue)` Retrieve boolean value.
`Color`	`getColor(String bindingName, Color defaultValue)` Retrieve color value.
`String`	`getContextName()` Name of the context.
`static Context`	`getDefault()` Getter for default instance of registry.
`double`	`getDouble(String bindingName, double defaultValue)` Retrieve double value.
`float`	`getFloat(String bindingName, float defaultValue)` Retrieve float value.
`Font`	`getFont(String bindingName, Font defaultValue)` Retrieve font value.
`int`	`getInt(String bindingName, int defaultValue)` Retrieve integer value.
`long`	`getLong(String bindingName, long defaultValue)` Retrieve long value.
`static Mutex`	`getMutex()` Shared Mutex on which all contexts are synchronized.
`Object`	`getObject(String bindingName, Object defaultValue)` Retrieve named object from the context.
`List`	`getOrderedNames()` Method listing ordered names of the context items.
`List`	`getOrderedObjects()` Method for listing items of the context ordered.
`Context`	`getParentContext()` Retrieve parent context.
`ObjectRef`	`getRef(String bindingName)` Retrieve directly the bounded ObjectRef instance.
`Context`	`getRootContext()` Gets root context.
`String`	`getString(String bindingName, String defaultValue)` Retrieve String value.
`String[]`	`getStringArray(String bindingName, char separator, String[] defaultValue)` Retrieve string array by reading stored string and splitting it by the given separator into array of Strings.
`Context`	`getSubcontext(String subcontextName)` Retrieve subcontext of the given name.
`Collection`	`getSubcontextNames()` Retrieve names of all subcontexts of this context.
`URL`	`getURL(String bindingName, URL defaultValue)` Retrieve URL value.
`boolean`	`hasDefault(String bindingName)` Exist a default value for this binding or context?
`boolean`	`isModified(String bindingName)` Check whether the value of this binding or context is modified.
`static Context`	`merge(Context[] delegates)` Returns context, that merges all its delegates.
`void`	`orderContext(List names)` Store full order of the context content.
`void`	`putBoolean(String bindingName, boolean value)` This method converts the passed boolean to Boolean object and binds it into context.
`void`	`putColor(String bindingName, Color value)` This is just convenient method.
`void`	`putDouble(String bindingName, double value)` This method converts the passed double to Double object and binds it into context.
`void`	`putFloat(String bindingName, float value)` This method converts the passed float to Float object and binds it into context.
`void`	`putFont(String bindingName, Font value)` This is just convenient method.
`void`	`putInt(String bindingName, int value)` This method converts the passed integer to Integer object and binds it into context.
`void`	`putLong(String bindingName, long value)` This method converts the passed long to Long object and binds it into context.
`void`	`putObject(String bindingName, Object value)` Binds a name to an object and store the object in context.
`void`	`putString(String bindingName, String value)` Binds a name to the String and store it in the context.
`void`	`putStringArray(String bindingName, char separator, String[] value)` Store array of strings.
`void`	`putURL(String bindingName, URL value)` This is just convenient method.
`void`	`removeContextListener(ContextListener l)` Remove listener for receiving events about context and all its descendant subcontexts changes.
`void`	`revert(String bindingName)` Revert modification of this binding or context.
`void`	`setAttribute(String bindingName, String attributeName, String value)` Modify value of the attribute.
`String`	`toString()`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Method Detail

getDefault

public static Context getDefault()

Getter for default instance of registry.

Application specific documentation must be consulted to learn which exact implementation will be returned by this method. For example for NetBeans it can be implementation working on top of the root of SystemFileSystem.

Returns:: default root context

merge

public static Context merge(Context[] delegates)

Returns context, that merges all its delegates. See JavaDoc overview for more details.

Parameters:: delegates - array of contexts that should be merged
Returns:: merged context
Since:: 1.6

getContextName

public String getContextName()

Name of the context.

Returns:: name of the context; cannot be null

getRootContext

public Context getRootContext()

Gets root context.

Returns:: root context

getAbsoluteContextName

public String getAbsoluteContextName()

Getter for the absolute name of the context, eg. "/mymodule/mysettings". It is full path from the root context.

Returns:: absolute name of this context; cannot be null

getSubcontext

public Context getSubcontext(String subcontextName)

Retrieve subcontext of the given name. The multi-level path is accepted as subcontext name (eg. "sub1/sub2/mysub").

Parameters:: subcontextName - multi-level subcontext name to retrieve
Returns:: Context or null if subcontext does not exist

getParentContext

public Context getParentContext()

Retrieve parent context.

Returns:: parent context or null in case of root context

createSubcontext

public Context createSubcontext(String subcontextName)
                         throws ContextException

Create subcontext of the given name. The multi-level path is accepted as subcontext name (eg. "sub1/sub2/mysub"). All intermediate subcontexts which do not exist will be created. If subcontext already exist it is just retrieved.

Parameters:: subcontextName - multi-level subcontext name to create
Returns:: created or retrieved context
Throws:: ContextException - thrown when subcontext cannot be created

destroySubcontext

public void destroySubcontext(String subcontextName)
                       throws ContextException

Destroy subcontext of the given name. Destroying context deletes also all its data recursively, ie. all bindings, attributes and its subcontexts. The multi-level path is accepted (eg. "sub1/sub2/mysub").

Parameters:: subcontextName - multi-level name of existing subcontext
Throws:: ContextException - thrown when subcontext cannot be deleted

getSubcontextNames

public Collection getSubcontextNames()

Retrieve names of all subcontexts of this context.

Returns:: collection of Strings, ie. names of all subcontexts in the context; cannot be null

getBindingNames

public Collection getBindingNames()

Retrieve names of all bindings in this context.

Returns:: collection of Strings, ie. names of all bindings in the context; cannot be null

getAttributeNames

public Collection getAttributeNames(String bindingName)

Retrieve names of all attributes in this context.

Returns:: collection of Strings, ie. names of all attribute in the context; cannot be null

orderContext

public void orderContext(List names)

Store full order of the context content. The passed list can contain only String instances which are names of a context's binding or context's subcontext. The context's subcontext name must be appended with "/" character to distinguish subcontext name from binding name. For any other value the IllegalArgumentException will be thrown.

Parameters:: names - full order of the objects in the context; see above for expected values in the list

getOrderedObjects

public List getOrderedObjects()

Method for listing items of the context ordered. The returned list will contain instances of all direct subcontexts and all bound objects in this context.

See Javadoc overview for how the context items are sorted. If context content was ordered by orderContext(java.util.List) method then the items will be listed in this order (order of items which were not specified in the full order is undefined).

Returns:: collection of ordered Objects, ie. both instances of bound Objects and Contexts representing subcontexts are returned.

getOrderedNames

public List getOrderedNames()

Method listing ordered names of the context items. The returned list will contain names of all direct subcontexts and all bound objects in this context. The subcontext names are appended with "/" character. It can be used to distinguish subcontext name and binding name when they are the same.

See the JavaDoc for getOrderedObjects() method for more details about ordering itself.

Returns:: collection of Strings; contains binding names and subcontext names appended with "/" character
Since:: 1.4

getObject

public Object getObject(String bindingName,
                        Object defaultValue)

Retrieve named object from the context.

If retrieved object is instance of ObjectRef it is recursively dereferenced and the value of ObjectRef instance if returned instead. If dereferenced value is null or ObjectRef is invalid then the ObjectRef instance is returned. See getRef(java.lang.String) if you need to retrieve ObjectRef directly.

Parameters:: bindingName - the name of the object to retrieve; cannot be empty; defaultValue - default value returned in case the binding does not exist.
Returns:: retrieved value or defaultValue if this binding does not exist

getRef

public ObjectRef getRef(String bindingName)

Retrieve directly the bounded ObjectRef instance. The getObject(java.lang.String, java.lang.Object) does recursive traversal of ObjectRef and returns directly the referenced value.

Parameters:: bindingName - the name of the object to retrieve; cannot be empty
Returns:: instance of the ObjectRef or null if bound object is not ObjectRef

putObject

public void putObject(String bindingName,
                      Object value)

Binds a name to an object and store the object in context. Use null value to remove binding.

See class overview JavaDoc for more details about how the objects are stored and which object types are supported.

Parameters:: bindingName - the name to bind; cannot be empty; value - the object to bind; null is allowed and means deletion of the binding

getString

public String getString(String bindingName,
                        String defaultValue)

Retrieve String value.

Parameters:: bindingName - binding name; defaultValue - default value returned if this binding does not exist
Returns:: retrieved value or defaultValue if this binding does not exist

putString

public void putString(String bindingName,
                      String value)

Binds a name to the String and store it in the context. Use null value to remove binding.

Parameters:: bindingName - binding name; value - value

getInt

public int getInt(String bindingName,
                  int defaultValue)

Retrieve integer value.

Parameters:: bindingName - binding name; defaultValue - default value returned if this binding does not exist
Returns:: retrieved value or defaultValue if this binding does not exist

putInt

public void putInt(String bindingName,
                   int value)

This method converts the passed integer to Integer object and binds it into context. Use putObject(java.lang.String, java.lang.Object) with null value to remove binding.

Parameters:: bindingName - binding name; value - value

getLong

public long getLong(String bindingName,
                    long defaultValue)

Retrieve long value.

Parameters:: bindingName - binding name; defaultValue - default value returned if this binding does not exist
Returns:: retrieved value or defaultValue if this binding does not exist

putLong

public void putLong(String bindingName,
                    long value)

This method converts the passed long to Long object and binds it into context. Use putObject(java.lang.String, java.lang.Object) with null value to remove binding.

Parameters:: bindingName - binding name; value - value

getBoolean

public boolean getBoolean(String bindingName,
                          boolean defaultValue)

Retrieve boolean value.

Parameters:: bindingName - binding name; defaultValue - default value returned if this binding does not exist
Returns:: retrieved value or defaultValue if this binding does not exist

putBoolean

public void putBoolean(String bindingName,
                       boolean value)

This method converts the passed boolean to Boolean object and binds it into context. Use putObject(java.lang.String, java.lang.Object) with null value to remove binding.

Parameters:: bindingName - binding name; value - value

getFloat

public float getFloat(String bindingName,
                      float defaultValue)

Retrieve float value.

Parameters:: bindingName - binding name; defaultValue - default value returned if this binding does not exist
Returns:: retrieved value or defaultValue if this binding does not exist

putFloat

public void putFloat(String bindingName,
                     float value)

This method converts the passed float to Float object and binds it into context. Use putObject(java.lang.String, java.lang.Object) with null value to remove binding.

Parameters:: bindingName - binding name; value - value

getDouble

public double getDouble(String bindingName,
                        double defaultValue)

Retrieve double value.

Parameters:: bindingName - binding name; defaultValue - default value returned if this binding does not exist
Returns:: retrieved value or defaultValue if this binding does not exist

putDouble

public void putDouble(String bindingName,
                      double value)

This method converts the passed double to Double object and binds it into context. Use putObject(java.lang.String, java.lang.Object) with null value to remove binding.

Parameters:: bindingName - binding name; value - value

getFont

public Font getFont(String bindingName,
                    Font defaultValue)

Retrieve font value.

Parameters:: bindingName - binding name; defaultValue - default value returned if this binding does not exist
Returns:: retrieved value or defaultValue if this binding does not exist

putFont

public void putFont(String bindingName,
                    Font value)

This is just convenient method. Its functionality is equal to putObject(java.lang.String, java.lang.Object). Use null value to remove binding.

Parameters:: bindingName - binding name; value - value

getColor

public Color getColor(String bindingName,
                      Color defaultValue)

Retrieve color value.

Parameters:: bindingName - binding name; defaultValue - default value returned if this binding does not exist
Returns:: retrieved value or defaultValue if this binding does not exist

putColor

public void putColor(String bindingName,
                     Color value)

This is just convenient method. Its functionality is equal to putObject(java.lang.String, java.lang.Object). Use null value to remove binding.

Parameters:: bindingName - binding name; value - value

getURL

public URL getURL(String bindingName,
                  URL defaultValue)

Retrieve URL value.

Parameters:: bindingName - binding name; defaultValue - default value returned if this binding does not exist
Returns:: retrieved value or defaultValue if this binding does not exist

putURL

public void putURL(String bindingName,
                   URL value)

This is just convenient method. Its functionality is equal to putObject(java.lang.String, java.lang.Object). Use null value to remove binding.

Parameters:: bindingName - binding name; value - value

getStringArray

public String[] getStringArray(String bindingName,
                               char separator,
                               String[] defaultValue)

Retrieve string array by reading stored string and splitting it by the given separator into array of Strings.

Parameters:: bindingName - binding name; separator - separtor character; defaultValue - default value returned if this binding does not exist
Returns:: retrieved value or defaultValue if this binding does not exist

putStringArray

public void putStringArray(String bindingName,
                           char separator,
                           String[] value)

Store array of strings. The strings are compound into one String and separated by separator. The rest is same as in putString() method. Use null value to remove binding.

Parameters:: bindingName - binding name; value - value; separator - separator character

getAttribute

public String getAttribute(String bindingName,
                           String attributeName,
                           String defaultValue)

Retrieve value of the attribute. Attributes can be specified on binding or context.

Parameters:: bindingName - name of the binding for binding attribute or null for context attribute; attributeName - name of the attribute to retrieve; cannot be null; defaultValue - default value returned when attribute does not exist
Returns:: retrieved value or defaultValue if this attribute does not exist

setAttribute

public void setAttribute(String bindingName,
                         String attributeName,
                         String value)

Modify value of the attribute. Attributes can be specified on binding or context. Attribute is deleted by passing null as attribute value.

Parameters:: bindingName - name of the binding for binding attribute or null for context attribute; attributeName - name of the attribute to modify; cannot be null; value - new value of the attribute; null is allowed and means deletion of attribute

addContextListener

public void addContextListener(ContextListener l)

Add listener for receiving events about context and all its descendant subcontexts changes. This listener will be notified about added/removed subcontext, added/modified/removed binding and added/modified/removed context or binding attribute in this context and all its subcontexts. The ContextEvent.getContext() must be consulted to learn in which context the change really happened.

Parameters:: l - listener to add

removeContextListener

public void removeContextListener(ContextListener l)

Remove listener for receiving events about context and all its descendant subcontexts changes.

Parameters:: l - listener to remove

hasDefault

public boolean hasDefault(String bindingName)

Exist a default value for this binding or context?

Parameters:: bindingName - the binding name or null for the context examination
Returns:: true if there is a default; false in opposite case or when backend does not support defaults at all.

isModified

public boolean isModified(String bindingName)

Check whether the value of this binding or context is modified. The return value is always true in case default value does not exist, ie. hasDefault(java.lang.String) is false.

Parameters:: bindingName - the binding name or null for the context
Returns:: true if default value is modified; always returns true if default value does not exist

revert

public void revert(String bindingName)
            throws ContextException

Revert modification of this binding or context. Will do something only if value is modified (ie. isModified(java.lang.String) returns true). If there is no default value (ie. hasDefault(java.lang.String) returns false) the revert operation is identical to unbinding of object or destroying of content of context.

Parameters:: bindingName - the binding name or null for the context
Throws:: ContextException - can throw exception if there were problems during removal of modified values

getMutex

public static Mutex getMutex()

Shared Mutex on which all contexts are synchronized. The API clients does not need to synchronize access to context. But it can be convenient for example to do several changes under one lock.

Returns:: mutex instance

toString

public String toString()

Overrides:: toString in class Object

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

org.netbeans.modules.registry/1 1.8

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Context (Registry) - NetBeans API Javadoc (Current Development Version)

org.netbeans.api.registry Class Context

getDefault

merge

getContextName

getRootContext

getAbsoluteContextName

getSubcontext

getParentContext

createSubcontext

destroySubcontext

getSubcontextNames

getBindingNames

getAttributeNames

orderContext

getOrderedObjects

getOrderedNames

getObject

getRef

putObject

getString

putString

getInt

putInt

getLong

putLong

getBoolean

putBoolean

getFloat

putFloat

getDouble

putDouble

getFont

putFont

getColor

putColor

getURL

putURL

getStringArray

putStringArray

getAttribute

setAttribute

addContextListener

removeContextListener

hasDefault

isModified

revert

getMutex

toString

org.netbeans.api.registry
Class Context