com.nitido.nim
Class Entity

java.lang.Object
  com.nitido.nim.Entity

All Implemented Interfaces:

NiMConstants, java.io.Serializable

Direct Known Subclasses:

ContainerEntity, User

public abstract class Entity
extends java.lang.Object
implements java.io.Serializable, NiMConstants

The Entity class is the abstraction of an entity in a NiM application for which requests take place. Entities in an application are always authenticated and can only be instantiated through the getEntity() method on NiM.

See Also:

NiM, Serialized Form

Field Summary

protected DataControl	_datacontrol Reference to the entities data control object.
protected Credential	_identifyingCred Reference to the identifying credential of the entity.
protected java.util.HashMap	_nuggets Reference to the list of nuggets currently attached to this entity.
protected boolean	_released
protected int	_requestCount

Fields inherited from interface com.nitido.nim.NiMConstants

ACTION_CREATE_NUGGET, ACTION_CREATE_NUGGET_BY_NAME, ACTION_CRED_SPACE_ADD, ACTION_CRED_SPACE_GET_KEYS, ACTION_CRED_SPACE_GET_KEYS_START_WITH, ACTION_CRED_SPACE_GET_VALUE, ACTION_CRED_SPACE_GET_VALUES, ACTION_CRED_SPACE_MODIFY, ACTION_CRED_SPACE_REMOVE_VALUE, ACTION_CRED_SPACE_REMOVE_VALUES, ACTION_CRED_SPACE_REPLACE, ACTION_DEPROVISION_ENTITY, ACTION_ENTITY_CHANGE_CRED, ACTION_LOG_EVENT, ACTION_PROVISION_ENTITY, ACTION_USER_SPACE_ADD, ACTION_USER_SPACE_GET_KEYS, ACTION_USER_SPACE_GET_KEYS_START_WITH, ACTION_USER_SPACE_GET_VALUE, ACTION_USER_SPACE_GET_VALUES, ACTION_USER_SPACE_MODIFY, ACTION_USER_SPACE_REMOVE_VALUE, ACTION_USER_SPACE_REMOVE_VALUES, ACTION_USER_SPACE_REPLACE, CONF_PREFIX_SECURITY_ACCESS, CONF_PREFIX_SECURITY_ALLOW, CONF_PREFIX_SECURITY_ASSIGN, CONF_PREFIX_SECURITY_RESOURCE, PARAM_CHANGE_CRED, PARAM_DEPROVISION_CREDENTIAL, PARAM_EVENT_NAME, PARAM_MODIFIER_CONTAINER, PARAM_NUGGET_CREATE_CRED, PARAM_NUGGET_NAME, PARAM_NUGGET_SETTINGS, PARAM_NUGGET_TYPE, PARAM_PROVISION_DESCRIPTOR, PARAM_SPACE_KEY, PARAM_SPACE_KEYS_START_WITH, PARAM_SPACE_VALUE, PREFIX_ACCESS_CLASS_IN_PACKAGE

Constructor Summary

protected

Entity(NiMKernelServiceVisa visa, Credential credential, DataControl datacontrol) This constructor is called by the EntityService of the NiMKernel to create a new instance of the class.

Method Summary

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.
protected void	changeDataControlCredential(Credential newDCCred, boolean modBackend) Redirector that invokes the DataControl.changeDataControlCredential().
void	changeIdentifyingCredential(Credential newCred) This method is used to replace the identifying credentials associated with the entity.
Nugget	createNugget(java.lang.String nuggetName, java.lang.String nuggetType, java.util.Hashtable nuggetSettings) This method creates a new nugget instance for the given nugget type with the given settings and will attach the nugget to the entity.
protected void	finalize() The finalizer that is responsible for cleaning up the entity.
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.
java.util.Vector	getFromCredentialSpace(java.lang.String key) This method returns all the credentials associated with the given key.
java.util.Vector	getFromUserSpace(java.lang.String key) This method returns all the objects associated with the given key.
java.lang.String	getID() This method returns the identifier associated to this entity.
Credential	getIdentifyingCredential() This method returns a reference to the identifying credential of the entity.
NiM	getNiM() This method returns a reference to the NiM object that instantiated the entity.
Nugget	getNugget(java.lang.String nuggetName) This method returns a reference to the Nugget that is associated to the given nugget name.
java.lang.String[]	getNuggetNames() This method returns the names of the nugget that has been created and attached to this entity object.
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.
Credential	getValueFromCredentialSpace(java.lang.String key) This method returns the first instance of the credential object associated to the given key.
java.io.Serializable	getValueFromUserSpace(java.lang.String key) This method returns the first instance of the object associated with the given key.
void	modifyCredentialSpace(ModifierContainer container) This method is used to make batch modifications to the credential space of the entity.
void	modifyUserSpace(ModifierContainer container) This method makes batch modifications to user space of the entity.
protected void	releaseEntity()
void	releaseNugget(java.lang.String nuggetName) This method removes the nugget associated to the given name from this entity.
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.
void	requestBegin() This method is used to inform the entity that a request on the entity is about to start.
void	requestEnd() This method is used to inform the entity that a request on the entity has finished.
protected void	setIdentifyingCredential(Credential authCred) Change the identifying credential.
java.lang.String	toString() This method returns the entity identifier component of the identifying credential for this entity.

Methods inherited from class java.lang.Object

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

Field Detail

_identifyingCred

protected Credential _identifyingCred

Reference to the identifying credential of the entity.

_datacontrol

protected DataControl _datacontrol

Reference to the entities data control object.

_nuggets

protected final java.util.HashMap _nuggets

Reference to the list of nuggets currently attached to this entity.

_released

protected volatile boolean _released

_requestCount

protected transient int _requestCount

Constructor Detail

Entity

protected Entity(NiMKernelServiceVisa visa,
                 Credential credential,
                 DataControl datacontrol)
          throws NiMRuntimeException

This constructor is called by the EntityService of the NiMKernel to create a new instance of the class.

Parameters:

visa - The Visa object is used to ensure that only the Entity service of the NiMKernel can instantiate this class.

credential - The identifying credential of the user object.

datacontrol - A reference to the DataControl object that is binded to this user. This parameter can be null If this entity happens to have no DataControl.

Throws:

NiMRuntimeException - If the reference to the visa object is null.

Method Detail

getID

public java.lang.String getID()

This method returns the identifier associated to this entity.

Returns:

The identifier that unique identifies this entity

getIdentifyingCredential

public Credential getIdentifyingCredential()

This method returns a reference to the identifying credential of the entity.

Returns:

Reference to the Credential object used to authenticate the entity.

getNiM

public NiM getNiM()

This method returns a reference to the NiM object that instantiated the entity.

Returns:

Reference to the NiM object that instantiated the entity.

toString

public java.lang.String toString()

This method returns the entity identifier component of the identifying credential for this entity.

Overrides:

toString in class java.lang.Object

Returns:

The entity identifier.

getNugget

public Nugget getNugget(java.lang.String nuggetName)
                 throws NuggetNotAvailableException,
                        PermissionDeniedException,
                        InitializationFailedException,
                        InvalidSettingException

This method returns a reference to the Nugget that is associated to the given nugget name.

If a nugget has been created for the specified nuggetName, this method will return the existing nugget instance. Otherwise, it will ask the NuggetService to attempt creating a nugget instance based on the nuggetName. The configuration service must provide the NuggetService with enough information for the specified nuggetName so that it can create the nugget. If the NuggetService fails to create the specified nugget, this method will throw a NuggetNotAvailableException.

Parameters:

nuggetName - The name of the nugget that was passed when the nugget was created through the createNugget() method on Entity.

Returns:

Reference to the nugget associated to the given name.

Throws:

NuggetNotAvailableException - If no nugget has been created under the nuggetName and the NuggetService implementation cannot create an instance of the nugget due to the lack of nugget setting information in the ConfigurationService.

InitializationFailedException - If unable to initialize the new nugget with the nugget settings stored in the configuration service.

PermissionDeniedException - If the identifying credential of the entity does not have permission to create the requested nugget.

InvalidSettingException - If the nugget settings on the configuration service contains invalid configuration information.

getNuggetNames

public java.lang.String[] getNuggetNames()
                                  throws EntityReleasedException

This method returns the names of the nugget that has been created and attached to this entity object.

Returns:

String array with the names of all the nuggets currently attached to this entity.

Throws:

EntityReleasedException

releaseNugget

public void releaseNugget(java.lang.String nuggetName)

This method removes the nugget associated to the given name from this entity.

Parameters:

nuggetName - The name of the nugget to be release from this entity

createNugget

public Nugget createNugget(java.lang.String nuggetName,
                           java.lang.String nuggetType,
                           java.util.Hashtable nuggetSettings)
                    throws PermissionDeniedException,
                           InitializationFailedException,
                           InvalidSettingException

This method creates a new nugget instance for the given nugget type with the given settings and will attach the nugget to the entity.

The identifying credential of the current entity is used as the authority for creating the Nugget.

Parameters:

nuggetName - The unique name for the nugget within the entity.

nuggetType - The type of the nugget to be instantiated.

nuggetSettings - The set of name/value pairs that specify the settings of the Nugget being created.

Returns:

Reference to the newly created Nugget.

Throws:

InitializationFailedException - If unable to initialize the new nugget with the given settings. This Exception will contain more details explaining the reasons that caused the exception.

PermissionDeniedException - If the identifying credential of the entity does not have permission to create the requested nugget.

InvalidSettingException - If the given settings contains invalid information.

modifyCredentialSpace

public void modifyCredentialSpace(ModifierContainer container)
                           throws DataControlException,
                                  PermissionDeniedException

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the operations described by the given container.

addToCredentialSpace

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

replaceInCredentialSpace

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

removeFromCredentialSpace

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

removeFromCredentialSpace

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

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

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

getValueFromCredentialSpace

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

getFromCredentialSpace

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

getCredentialSpaceKeys

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

getCredentialSpaceKeys

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

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

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

modifyUserSpace

public void modifyUserSpace(ModifierContainer container)
                     throws DataControlException,
                            PermissionDeniedException

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the operations described by the given container.

addToUserSpace

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

replaceInUserSpace

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

removeFromUserSpace

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

removeFromUserSpace

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

getValueFromUserSpace

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

getFromUserSpace

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

getUserSpaceKeys

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

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.

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

getUserSpaceKeys

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

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

PermissionDeniedException - This exception is thrown if the Entity is not entitled to perform the requested action.

releaseEntity

protected void releaseEntity()
                      throws NiMException

Throws:

NiMException

finalize

protected void finalize()

The finalizer that is responsible for cleaning up the entity.

Overrides:

finalize in class java.lang.Object

requestBegin

public void requestBegin()

This method is used to inform the entity that a request on the entity is about to start.

requestEnd

public void requestEnd()

This method is used to inform the entity that a request on the entity has finished.

changeIdentifyingCredential

public void changeIdentifyingCredential(Credential newCred)
                                 throws AuthenticationFailedException,
                                        IllegalCredentialException,
                                        DataControlException,
                                        PermissionDeniedException,
                                        NiMException

This method is used to replace the identifying credentials associated with the entity.

Parameters:

newCred - The new identifying credential of the entity.

Throws:

AuthenticationFailedException - If unable to authenticate the given entity credentials.

IllegalCredentialException - If the given credential is null or invalid.

DataControlException - If the Entity's DataControl is unable to establish a connection to its back-end

PermissionDeniedException - If the Entity does not have permission to perform this operation

NiMException - If unable to establish a connection to the authentication service on the back-end.

setIdentifyingCredential

protected final void setIdentifyingCredential(Credential authCred)

Change the identifying credential. This method should be called by the redirector in EntityService only.

Parameters:

authCred - The new identifying credential for the Entity.

changeDataControlCredential

protected final void changeDataControlCredential(Credential newDCCred,
                                                 boolean modBackend)
                                          throws IllegalCredentialException,
                                                 DataControlException

Redirector that invokes the DataControl.changeDataControlCredential(). This method should be called by the redirector in EntityService only.

Parameters:

newDCCred - The new DataControl Credential

modBackend - Flag indicating the Entity's DataControl to modify the back-end with the new credential.

Throws:

IllegalCredentialException - If the given credential is null or invalid.

DataControlException - If the Entity's DataControl is unable to establish a connection to its back-end