com.nitido.nim
Class DataControl

java.lang.Object
  com.nitido.nim.DataControl

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

DataControlImpl, DataControlImpl, DataControlImpl, DataControlImpl

public abstract class DataControl
extends java.lang.Object
implements java.io.Serializable

A DataControl provides Entities with an abstraction for storing and retrieving profile data. The data control interface defines two types of data spaces for storing data:

• Credential Space: This space is used by the entity for storing and retrieving credential information.
• User Space: This space is used by the entity for storing profile information.

See Also:

Serialized Form

Constructor Summary

protected

DataControl(Credential credential, java.util.HashMap settings) This constructor returns an instance of the DataControl that is binded to the given credential.

Method Summary

protected abstract void	acquire() This method is used to establish a connection to the back-end data store.
protected abstract void	activate() This method is used to activates the DataControl after the Entity object containing this DataControl is deserialized.
void	addToCredentialSpace(java.lang.String key, Credential value) This method adds a new credential to the user space under the given key.
void	addToUserSpace(java.lang.String key, java.io.Serializable value) This method adds a new object to the user space of the entity.
abstract void	bind(Credential credential) This method is used to bind the given credential to the DataControl.
protected abstract void	changeDataControlCredential(Credential newCred, boolean modBackend) This method changes and rebinds the "login" credential of the DataControl.
protected abstract void	deactivate() This method is called to deactivate the DataControl.
protected abstract void	destroy() This method is invoked when the associated Entity has been signaled as dying.
java.lang.String[]	getCredentialSpaceKeys() This method returns all the keys currently available in the credential space.
java.lang.String[]	getCredentialSpaceKeys(java.lang.String startsWith) This method returns all the credential keys currenlty available in the credential space whose value starts with the given prefix.
protected abstract java.lang.String[]	getCredentialSpaceKeysImpl(java.lang.String startsWith) This method contains the actual implementation for the getCredentialSpaceKeys( startsWith ) method.
java.util.Vector	getFromCredentialSpace(java.lang.String key) This method returns all the credentials associated with the given key.
protected abstract java.util.Vector	getFromCredentialSpaceImpl(java.lang.String key) This method contains the actual implementation for the getFromCredentialSpace( key ) method.
java.util.Vector	getFromUserSpace(java.lang.String key) This method returns all the objects associated with the given key.
protected abstract java.util.Vector	getFromUserSpaceImpl(java.lang.String key) This method contains the actual implementation for the getFromUserSpace() method.
java.lang.String[]	getUserSpaceKeys() This method returns all the keys currently available in the user space.
java.lang.String[]	getUserSpaceKeys(java.lang.String startsWith) This method returns all the object keys currenlty available in the user space whose value starts with the given prefix.
protected abstract java.lang.String[]	getUserSpaceKeysImpl(java.lang.String startsWith) This method contains the actual implementation for the getUserSpaceKeys() method.
Credential	getValueFromCredentialSpace(java.lang.String key) This method returns the first instance of the credential object associated to the given key.
protected abstract Credential	getValueFromCredentialSpaceImpl(java.lang.String key) This method contains the actual implementation for the getValueFromCredentialSpace( key ) method.
java.io.Serializable	getValueFromUserSpace(java.lang.String key) This method returns the first instance of the object associated with the given key.
protected abstract java.io.Serializable	getValueFromUserSpaceImpl(java.lang.String key) This method contains the actual implementation for the getValueFromUserSpace() method.
protected abstract void	initialize(java.util.HashMap settings) This method is used to initialize the DataControl with the given settings.
void	modifyCredentialSpace(ModifierContainer container) This method is used to make batch modifications to the credential space of the entity.
protected abstract void	modifyCredentialSpaceImpl(ModifierContainer container) This method provides the actual implementation to the modifyCredentialSpace() method.
void	modifyUserSpace(ModifierContainer container) This method makes batch modifications to user space of the entity.
protected abstract void	modifyUserSpaceImpl(ModifierContainer container) This method contains the actual implementation for the modifyUserSpace( container ) method.
protected abstract void	release() This method is used to release a connection to the back-end data store.
void	removeFromCredentialSpace(java.lang.String key) This method removes all the credentials that are associated to the given key from the credential space.
void	removeFromCredentialSpace(java.lang.String key, Credential value) This method removes the given key/credential pair from the credential space of the entity.
void	removeFromUserSpace(java.lang.String key) This method removes all the objects that are associated to the given key from the user space.
void	removeFromUserSpace(java.lang.String key, java.io.Serializable value) This method removes the given key/value pair from the user space of the entity.
void	replaceInCredentialSpace(java.lang.String key, Credential value) This method is used to store the given credential into the credential space under the given key.
void	replaceInUserSpace(java.lang.String key, java.io.Serializable value) This method is used to store the given object into the user space under the given key.

Methods inherited from class java.lang.Object

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

Constructor Detail

DataControl

protected DataControl(Credential credential,
                      java.util.HashMap settings)
               throws IllegalCredentialException,
                      DataControlException

This constructor returns an instance of the DataControl that is binded to the given credential. The default implementation of this constructor will first initialize the datacontrol settings and then it will try to bind the given credential to this DataControl.

Parameters:

credential - Reference to the Credential object used to authenticate against the back-end data store.

settings - A reference to the HashMap object that contains the parameters used to initialize the DataControl. The contents of this container are specific to each DataControl implementation.

Throws:

IllegalCredentialException - If the given credentials are not supported by the concrete DataControl implementation.

DataControlException - If unable to instantiate the DataControl object

Method Detail

initialize

protected abstract void initialize(java.util.HashMap settings)
                            throws DataControlException

This method is used to initialize the DataControl with the given settings. The contents of the settings container are specific to the concrete implementation of the class.

Parameters:

settings - Reference to the HashMap object that contains the parameters used to initialize the DataControl. The contents of this container are specific to the implementation of the class.

Throws:

DataControlException - If unable to initialize the DataControl

destroy

protected abstract void destroy()

This method is invoked when the associated Entity has been signaled as dying. This method should cleaned up all the resources associated to the DataControl that cannot be removed by the garbage collector.

bind

public abstract void bind(Credential credential)
                   throws IllegalCredentialException,
                          DataControlException

This method is used to bind the given credential to the DataControl. All DataControl constructors must call this method.

Parameters:

credential - Reference to the credential object used to authenticate the entity to the DataControl back-end data store.

Throws:

IllegalCredentialException - If the given credentials is not supported by the concrete DataControl implementation.

DataControlException - If unable to bind the credential to the back-end data store

acquire

protected abstract void acquire()
                         throws DataControlException

This method is used to establish a connection to the back-end data store. The method is called by each of the methods that access the data store.

Throws:

DataControlException - If unable to establish connection to the back-end data store.

release

protected abstract void release()
                         throws DataControlException

This method is used to release a connection to the back-end data store. The method is called by each of the methods that access the data store.

Throws:

DataControlException - If unable to close the connection to the back-end data store.

activate

protected abstract void activate()
                          throws ActivationException

This method is used to activates the DataControl after the Entity object containing this DataControl is deserialized.

Throws:

ActivationException - If unable to activate the DataControl

deactivate

protected abstract void deactivate()
                            throws ActivationException

This method is called to deactivate the DataControl. This method is called by the Entity object that contains this DataControl when the Entity is being serialized.

Throws:

ActivationException - If unable to de-activate the DataControl.

modifyCredentialSpace

public final void modifyCredentialSpace(ModifierContainer container)
                                 throws DataControlException

This method is used to make batch modifications to the credential space of the entity. Batch operations are done in the order specified in the modify container.

A ModifierContainer object encapsulate a series of actions to be performed such as: ADD, REPLACE, or REMOVE. Each action is performed on a key/value pair.

Parameters:

container - Encapsulates the list of modifications to be executed on the Credential space.

Throws:

DataControlException - This exception is thrown if unable to perform the requested modifications.

modifyCredentialSpaceImpl

protected abstract void modifyCredentialSpaceImpl(ModifierContainer container)
                                           throws DataControlException

This method provides the actual implementation to the modifyCredentialSpace() method.

Since the modifyCredentialSpace() method has already called the acquire() and release() methods, implementations of this method only need to handle the core modification logic. It does not need to worry about connection and other low level system resource management.

Parameters:

container - Encapsulates the list of modifications to be executed on the Credential space.

Throws:

DataControlException - This exception is thrown if unable to perform the requested modifications.

addToCredentialSpace

public final void addToCredentialSpace(java.lang.String key,
                                       Credential value)
                                throws DataControlException

This method adds a new credential to the user space under the given key. If the given key already exists in the credential space, the given credential will be added to any existing credential stored under that key.

Parameters:

key - The key used to identify the given credential

value - The credential to be added to the credential space of the entity.

Throws:

DataControlException - If unable to add the credential to the credential space.

replaceInCredentialSpace

public final void replaceInCredentialSpace(java.lang.String key,
                                           Credential value)
                                    throws DataControlException

This method is used to store the given credential into the credential space under the given key. If the given key already exists in the credential space, the given credential will replace all existing credentials with the new one.

Parameters:

key - The key used to identify the given credential

value - The credential to be added to the credential space of the entity.

Throws:

DataControlException - If unable to add the credential to the credential space.

removeFromCredentialSpace

public final void removeFromCredentialSpace(java.lang.String key,
                                            Credential value)
                                     throws DataControlException

This method removes the given key/credential pair from the credential space of the entity. If the given credential is null, then all credentials associated with the given key will be removed.

Parameters:

key - The key used to identify the credential to be removed.

value - The credential object to be removed from the credential space.

Throws:

DataControlException - If unable to remove the credential from the credential space of the entity.

removeFromCredentialSpace

public final void removeFromCredentialSpace(java.lang.String key)
                                     throws DataControlException

This method removes all the credentials that are associated to the given key from the credential space.

Parameters:

key - The key used to identify the credentials to be removed.

Throws:

DataControlException - If unable to remove the credentials from the credential space of the entity

getValueFromCredentialSpace

public final Credential getValueFromCredentialSpace(java.lang.String key)
                                             throws DataControlException

This method returns the first instance of the credential object associated to the given key.

Parameters:

key - The key that uniquely identifies a set of credentials.

Returns:

The reference to the first credential instance that was previously associated to the given key. If the given key is not found, the method returns null.

Throws:

DataControlException - If unable to retrieve a credential from the credential store.

getValueFromCredentialSpaceImpl

protected abstract Credential getValueFromCredentialSpaceImpl(java.lang.String key)
                                                       throws DataControlException

This method contains the actual implementation for the getValueFromCredentialSpace( key ) method. This method is used to separate the logic for opening/closing connections from the actual operation logic.

Parameters:

key - The key that uniquely identifies a set of credentials.

Returns:

The reference to the first credential instance that was previously associated to the given key. If the given key is not found, the method returns null.

Throws:

DataControlException - If unable to retrieve a credential from the credential store.

getFromCredentialSpace

public final java.util.Vector getFromCredentialSpace(java.lang.String key)
                                              throws DataControlException

This method returns all the credentials associated with the given key.

Parameters:

key - The key used to identify the requested credentials.

Returns:

A Vector with all the credentials associated with the given key. If no credential is found with the given key then this method returns an empty vector.

Throws:

DataControlException - If unable to retrieve the credentials from the credential store.

getFromCredentialSpaceImpl

protected abstract java.util.Vector getFromCredentialSpaceImpl(java.lang.String key)
                                                        throws DataControlException

This method contains the actual implementation for the getFromCredentialSpace( key ) method. This method is used to separate the logic for opening/closing connections from the actual logic to perform the operation

Parameters:

key - The key used to identify the requested credentials.

Returns:

A Vector with all the credentials associated with the given key. If no credential is found with the given key then this method returns an empty vector.

Throws:

DataControlException - If unable to retrieve the credentials from the credential store.

getCredentialSpaceKeys

public final java.lang.String[] getCredentialSpaceKeys()
                                                throws DataControlException

This method returns all the keys currently available in the credential space.

Returns:

A string array will all the keys currently available in the credential space.

Throws:

DataControlException - If unable to retrive the requested information.

getCredentialSpaceKeys

public final java.lang.String[] getCredentialSpaceKeys(java.lang.String startsWith)
                                                throws DataControlException

This method returns all the credential keys currenlty available in the credential space whose value starts with the given prefix.

Parameters:

startsWith - The prefix string used to search for the currently available credential keys. If no key matches the given prefix, this method returns an empty array

Returns:

A String array with the credential keys that matches the given prefix. If no match is found, the method returns an empty array.

Throws:

DataControlException - If unable to retrieve the requested information from the credential space

getCredentialSpaceKeysImpl

protected abstract java.lang.String[] getCredentialSpaceKeysImpl(java.lang.String startsWith)
                                                          throws DataControlException

This method contains the actual implementation for the getCredentialSpaceKeys( startsWith ) method. This method is used to separate the logic for opening/closing connections from the actual logic to perform the operation

Parameters:

startsWith - The prefix of the requested credential keys.

Returns:

A String array with the keys that start with the given prefix. If the given prefix is null, this method returns all the available keys. Finally if no keys are found with the given key, this method returns an empty array.

Throws:

DataControlException - If unable to fetch the credential space.

modifyUserSpace

public final void modifyUserSpace(ModifierContainer container)
                           throws DataControlException

This method makes batch modifications to user space of the entity. Batch operation are performed in the order specified in the modify container parameter.

A ModifierContainer object encapsulate a series of actions to be performed, such as: ADD, REPLACE, or REMOVE. Each action is performed on a key/value pair.

Parameters:

container - Encapsulates the list of modifications to be executed on the user space of the entity.

Throws:

DataControlException - If unable to perform any of the requested modifications.

modifyUserSpaceImpl

protected abstract void modifyUserSpaceImpl(ModifierContainer container)
                                     throws DataControlException

This method contains the actual implementation for the modifyUserSpace( container ) method. This method is used to separate the logic for opening/closing connections from the actual logic to perform the operation.

Parameters:

container - Encapsulates the list of modifications to be executed on the user space of the entity.

Throws:

DataControlException - If unable to perform any of the requested modifications.

addToUserSpace

public final void addToUserSpace(java.lang.String key,
                                 java.io.Serializable value)
                          throws DataControlException

This method adds a new object to the user space of the entity. If the given key already exists in the user space, the given object will be added to any existing object stored under that key.

Parameters:

key - The key used to identify object being added to the user space.

value - The object being added to the user space.

Throws:

DataControlException - If unable to add the given object to the user space of the entity.

replaceInUserSpace

public final void replaceInUserSpace(java.lang.String key,
                                     java.io.Serializable value)
                              throws DataControlException

This method is used to store the given object into the user space under the given key. If the given key already exists in the user space, the given object will replace all existing objects associated with the key.

Parameters:

key - The key used to identify the object being stored.

value - The object to be stored in the user space.

Throws:

DataControlException - If unable to add the object to the user space.

removeFromUserSpace

public final void removeFromUserSpace(java.lang.String key,
                                      java.io.Serializable value)
                               throws DataControlException

This method removes the given key/value pair from the user space of the entity. If the given credential is null, then all credentials associated with the given key will be removed.

Parameters:

key - The key used to identify the credential to be removed.

value - The object to be removed.

Throws:

DataControlException - If unable to remove the object from the user space.

removeFromUserSpace

public final void removeFromUserSpace(java.lang.String key)
                               throws DataControlException

This method removes all the objects that are associated to the given key from the user space.

Parameters:

key - The key used to identify the objects being removed.

Throws:

DataControlException - If unable to remove the objects associated with the given key from the user space.

getValueFromUserSpace

public final java.io.Serializable getValueFromUserSpace(java.lang.String key)
                                                 throws DataControlException

This method returns the first instance of the object associated with the given key.

Parameters:

key - The key that uniquely idenfifies a set of objects in the user space.

Returns:

The first object reference that matches the given key.

Throws:

DataControlException - If unable to retrieve the requested object from the user space.

getValueFromUserSpaceImpl

protected abstract java.io.Serializable getValueFromUserSpaceImpl(java.lang.String key)
                                                           throws DataControlException

This method contains the actual implementation for the getValueFromUserSpace() method. This method is used to separate the logic for opening/closing connections from the actual logic to perform the operation.

Parameters:

key - The key that uniquely idenfifies a set of objects in the user space.

Returns:

The first object reference that matches the given key.

Throws:

DataControlException - If unable to retrieve the requested object from the user space.

getFromUserSpace

public final java.util.Vector getFromUserSpace(java.lang.String key)
                                        throws DataControlException

This method returns all the objects associated with the given key.

Parameters:

key - The key used to identify the set of objects in the user space.

Returns:

A Vector with all the objects associated with the given key. If the given key is not found, this method returns an empty vector.

Throws:

DataControlException - If Unable to retrieve requested information from the user space.

getFromUserSpaceImpl

protected abstract java.util.Vector getFromUserSpaceImpl(java.lang.String key)
                                                  throws DataControlException

This method contains the actual implementation for the getFromUserSpace() method. This method is used to separate the logic for opening/closing connections from the actual logic to perform the operation.

Parameters:

key - The key used to identify the set of objects in the user space.

Returns:

A Vector with all the objects associated with the given key. If the given key is not found, this method returns an empty vector.

Throws:

DataControlException - If Unable to retrieve requested information from the user space.

getUserSpaceKeys

public final java.lang.String[] getUserSpaceKeys()
                                          throws DataControlException

This method returns all the keys currently available in the user space.

Returns:

A String array with all the keys currently available in the user space.

Throws:

DataControlException - If unable to retrieve the requested information from the user space.

getUserSpaceKeys

public final java.lang.String[] getUserSpaceKeys(java.lang.String startsWith)
                                          throws DataControlException

This method returns all the object keys currenlty available in the user space whose value starts with the given prefix.

Parameters:

startsWith - The prefix string used to search for the currently available user space keys. If no key matches the given prefix, this method returns an empty array

Returns:

A String array with the user space keys that matches the given prefix. If no match is found, the method returns an empty array.

Throws:

DataControlException - If unable to retrieve the requested information from the user space

getUserSpaceKeysImpl

protected abstract java.lang.String[] getUserSpaceKeysImpl(java.lang.String startsWith)
                                                    throws DataControlException

This method contains the actual implementation for the getUserSpaceKeys() method. This method is used to separate the logic for opening/closing connections from the actual logic to perform the operation.

Parameters:

startsWith - The prefix string used to search for the currently available user space keys. If no key matches the given prefix, this method returns an empty array

Returns:

A String array with the user space keys that matches the given prefix. If no match is found, the method returns an empty array.

Throws:

DataControlException - If unable to retrieve the requested information from the user space

changeDataControlCredential

protected abstract void changeDataControlCredential(Credential newCred,
                                                    boolean modBackend)
                                             throws IllegalCredentialException,
                                                    DataControlException

This method changes and rebinds the "login" credential of the DataControl. This method should change the last previous binded user's token to the credential specified by the newCred parameter. It is usually used for changing user pasword. If all you want to do is switching to another user or "super user", you should call the bind() method instead. Service Developer NOTE: Unlike other member methods, this method does not have a base class method that automatically called the "acquire() and release()" method. The implementation of this method must remember to make the backend connection themselves. We do not call the acquire() and release() automatically because the underlying implementation may not need to login as the current user (e.g. it may need to connect as the super user first).

Parameters:

newCred - The new credential to be changed for the currently binded user.

modBackend - If this flag is set to true, this method should change the login credential in the backend server as specified. Otherwise, this method only need to change how this DataControl establish the connection to the backend.

Throws:

IllegalCredentialException - If the given credentials is not supported by the DataControl.

DataControlException - If unable to bind the credential to the DataControl.