BasicContext (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.spi.registry
Interface BasicContext

All Known Subinterfaces:: ResettableContext

public interface BasicContext

This interface represents a basic 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 applications to store and retrieve data.

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.

All of the methods that modify context data are permitted to store changes asynchronously; they may fire change events and return immediatelly and propagate changes to backing store lazily.

At minimum the implementation must support persistence of all primitive data types and basic object types for which there are getters and setters in Context class. It is also recommended to provide a way for storage of other Object types (for example by using Java Serialization or other mechanism for persistence of objects). If provided it must be properly documented and explained to clients.

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

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

See also ResettableContext which is extensions of the basic context and Context which is API for bindings manipulation.

Method Summary

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

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

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

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

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

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

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

String getContextName()
          Name of the context.

BasicContext getParentContext()
          Retrieve parent context.

BasicContext getRootContext()
          Gets root context.

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

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

Object lookupObject(String bindingName)
          Retrieve named object from the context.

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

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

Method Summary
`void`	`addContextListener(ContextListener listener)` Add listener for receiving events about context and all its descendant subcontext changes.
`void`	`bindObject(String bindingName, Object object)` Binds a name to an object and store the object in context.
`BasicContext`	`createSubcontext(String subcontextName)` Create subcontext of the given name.
`void`	`destroySubcontext(String subcontextName)` Destroy subcontext of the given name.
`String`	`getAttribute(String bindingName, String attributeName)` Retrieve value of the attribute.
`Collection`	`getAttributeNames(String bindingName)` Get names of all attributes in this context.
`Collection`	`getBindingNames()` Get names of all bindings in this context.
`String`	`getContextName()` Name of the context.
`BasicContext`	`getParentContext()` Retrieve parent context.
`BasicContext`	`getRootContext()` Gets root context.
`BasicContext`	`getSubcontext(String subcontextName)` Retrieve direct subcontext of the given name.
`Collection`	`getSubcontextNames()` Retrieve names of all subcontexts of this context.
`Object`	`lookupObject(String bindingName)` Retrieve named object from the context.
`void`	`removeContextListener(ContextListener listener)` Remove listener for receiving events about context and all its descedndant subcontexts changes.
`void`	`setAttribute(String bindingName, String attributeName, String value)` Modify value of the attribute.

Method Detail

getRootContext

BasicContext getRootContext()

Gets root context. Method #

Returns:: root context
Since:: 1.7

getContextName

String getContextName()

Name of the context.

Returns:: name of the context

getSubcontext

BasicContext getSubcontext(String subcontextName)

Retrieve direct subcontext of the given name.

Parameters:: subcontextName - subcontext name to retrieve; cannot be null
Returns:: Context or null if subcontext does not exist

getParentContext

BasicContext getParentContext()

Retrieve parent context.

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

createSubcontext

BasicContext createSubcontext(String subcontextName)
                              throws ContextException

Create subcontext of the given name.

Parameters:: subcontextName - valid name of nonexisting subcontext
Returns:: created context
Throws:: ContextException - thrown when subcontext cannot be create or context with this name already exist

destroySubcontext

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.

Parameters:: subcontextName - name of existing subcontext
Throws:: ContextException - thrown when subcontext cannot be deleted or context with this name does not exist

getSubcontextNames

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

Collection getBindingNames()

Get names of all bindings in this context.

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

getAttributeNames

Collection getAttributeNames(String bindingName)

Get names of all attributes in this context.

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

lookupObject

Object lookupObject(String bindingName)
                    throws ContextException

Retrieve named object from the context.

Parameters:: bindingName - the name of the object to lookup; cannot be empty
Returns:: found object or null when no binding exist
Throws:: ContextException - thrown when object cannot be recreated

bindObject

void bindObject(String bindingName,
                Object object)
                throws ContextException

Binds a name to an object and store the object in context. Binding is deleted by passing null as object value.

Parameters:: bindingName - the name to bind; cannot be empty; object - the object to bind; null is allowed and means deletion of the binding
Throws:: ContextException - thrown when object cannot be bound

getAttribute

String getAttribute(String bindingName,
                    String attributeName)
                    throws ContextException

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
Returns:: value of the attribute or null if attribute does not exist
Throws:: ContextException - thrown when attribute cannot be read

setAttribute

void setAttribute(String bindingName,
                  String attributeName,
                  String value)
                  throws ContextException

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
Throws:: ContextException - thrown when object cannot be stored

addContextListener

void addContextListener(ContextListener listener)

Add listener for receiving events about context and all its descendant subcontext changes. The listener must 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.

Parameters:: listener - listener to add

removeContextListener

void removeContextListener(ContextListener listener)

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

Parameters:: listener - listener to remove