com.nitido.nim
Class Nugget

java.lang.Object
  com.nitido.nim.Nugget

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

CachableNugget, JavaMailNugget, NonCachableNugget

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

The Nugget class is the base class for all Nugget objects. Nuggets provide entities access to authenticated or non-authenticated back-end services. It is important to remember that Nuggets can only be instantiated through the createNugget() method on Entity. This ensures the all nugget instances are associated to an entity in the system.

Nuggets are used to access different types of services and as such different Nugget classes may have very different programming interfaces. This class provides the base Nugget interface.

Starting from NiM 2.3, all Nugget implementation should extends from the classes CachableNugget and NonCachableNugget instead of this class.

A CachableNugget will instantiated and attached to the associated Entity object. It will not be instantiated again unless the invoker explicitly release the Nugget instance from the Entity.

On the other hand, a NonCachableNugget will be instantiated everytime that getEntity() is invoked. A NonCachableNugget is usually used by Nugget implementations that are not thread safe. For example, a Nugget that needs to manages transaction that involves multiple method calls.

See Also:

Serialized Form

Field Summary

protected Entity	_entity The entity this nugget is associated to.
protected NiM	_nim Reference to the NiM object
protected java.lang.String	_nuggetName The name associated with the Nugget.
protected java.util.Hashtable	_settings The settings used to initialize this nugget.

Constructor Summary

Nugget(NuggetVisa visa)
This constructor is called by the Nugget kernel service to instantiate a new Nugget instance of a concrete type.

Method Summary

protected void	activate() This method is called by the Entity object after that object has been deserialized.
protected void	deactivate() This method is called by the Entity object before that object is serialized.
protected void	destroy() This method is invoked by com.nitido.nim.Entity object when the Entity has been signaled as "dying".
protected void	destroyImpl() This method is invoked by the destroy() method when the associated Entity has been signaled as "dying".
abstract java.lang.String	getDescriptor() This method returns a reference to the Nugget Descriptor.
Entity	getEntity() This method returns the reference of the Entity object that owns this Nugget instance.
java.lang.String	getNuggetName() Returns the nugget name.
java.lang.String	getSetting(java.lang.String name) This method returns the first value that corresponds to the named setting.
java.util.Hashtable	getSettings() This method returns a copy of the settings used to initialize the Nugget.
void	init(java.lang.String nuggetName, Entity entity, java.util.Hashtable settings) This method is the base initialization method that should be called by NuggetService after a Nugget has been instantiated successfully.
protected abstract void	initImpl() This method is called by the init() method after the member variables _nuggetName, _entity and _settings are assigned.
abstract boolean	isCachable() This method indicates whether the Nugget implementation is a cachable nugget.
void	requestBegin() This method is used to inform the Nugget that new requests are about to start.
void	requestEnd() This method is used to inform the Nugget that requests are terminated.

Methods inherited from class java.lang.Object

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

Field Detail

_nuggetName

protected java.lang.String _nuggetName

The name associated with the Nugget.

_entity

protected Entity _entity

The entity this nugget is associated to.

_settings

protected java.util.Hashtable _settings

The settings used to initialize this nugget.

_nim

protected transient NiM _nim

Reference to the NiM object

Constructor Detail

Nugget

public Nugget(NuggetVisa visa)
       throws NiMRuntimeException

This constructor is called by the Nugget kernel service to instantiate a new Nugget instance of a concrete type.

Parameters:

visa - Reference to a NuggetVisa object. This parameter is required and can not be null.

Throws:

NiMRuntimeException - If the given visa object is null.

Method Detail

init

public final void init(java.lang.String nuggetName,
                       Entity entity,
                       java.util.Hashtable settings)
                throws InitializationFailedException,
                       InvalidSettingException

This method is the base initialization method that should be called by NuggetService after a Nugget has been instantiated successfully. It perform the following tasks sequentially:

1. Assigns the value to member variable _nuggetName.
2. Assigns the value to member variable _entity.
3. Assigns a clone of the settings Hashtable to member variable _settings.
4. Calls initImpl( settings ).

NOTE: this method is not supposed to be invoked by the application code at all. It is declared as a public method only because it can be invoked by the NuggetService implementations.

Parameters:

nuggetName - The name associated to this nugget.

entity - Reference to the entity object the nugget is associated with.

settings - Reference to the settings used to initialize the nugget.

Throws:

InitializationFailedException

InvalidSettingException

destroy

protected final void destroy()

This method is invoked by com.nitido.nim.Entity object when the Entity has been signaled as "dying". This method will redirect the call to the underlying implementation's destroyImpl() before setting the protected member variables to null.

initImpl

protected abstract void initImpl()
                          throws InitializationFailedException,
                                 InvalidSettingException

This method is called by the init() method after the member variables _nuggetName, _entity and _settings are assigned. This method allows nugget implementations to put in code for initializing itself.

Throws:

InitializationFailedException - If unable to initialize the nugget with the given parameters.

InvalidSettingException - If any of the expected initialization settings are null.

destroyImpl

protected void destroyImpl()

This method is invoked by the destroy() method when the associated Entity has been signaled as "dying". This method provides implementation specific clean up operation before the operation dies. It is different from the deactivate() method in the sense that a Nugget that has been deactivate() may be resurrect at a later time, but an destroy() Nugget will never been invoked again.

For example, the WcapNugget will need to login to a backend Calendar server. The Calendar server will return a session ID that will be used by the Nugget for later operations. So, when the Nugget is "deactivate()", it does not need to logout from the Calendar Server and keep the session ID as the Nugget's persistent member. However, when the Nugget is "destroy()", the Nugget should logout the user from the backend Calendar server.

The base implementation of this method does nothing.

getSettings

public final java.util.Hashtable getSettings()

This method returns a copy of the settings used to initialize the Nugget.

Returns:

A copy of the Hashtable object containing name/value pairs with the Nugget settings.

getSetting

public final java.lang.String getSetting(java.lang.String name)

This method returns the first value that corresponds to the named setting.

Parameters:

name - The name of the Setting to retrieve.

Returns:

The first value corresponding to the named setting.

activate

protected void activate()
                 throws ActivationException

This method is called by the Entity object after that object has been deserialized. Extenders of this class should implement this method to re-establish any connections that were terminated when the Entity was serialized and should always call back the activate() method of the parent class.

Throws:

ActivationException - If unable to activate the Nugget

deactivate

protected void deactivate()
                   throws ActivationException

This method is called by the Entity object before that object is serialized. Extenders of this class should should implement this method to take down any active connections used by the Nugget as they can not be serialized. In addition nugget implementations of this method should call back the deactivate() method of the parent class.

Throws:

ActivationException - If unable to deactivate the Nugget

getNuggetName

public java.lang.String getNuggetName()

Returns the nugget name.

Returns:

The nugget name.

getDescriptor

public abstract java.lang.String getDescriptor()

This method returns a reference to the Nugget Descriptor.

Returns:

The string with the description of the Nugget.

requestBegin

public void requestBegin()

This method is used to inform the Nugget that new requests are about to start. This method can be used by the Nugget developer to manage/optimize access to the nugget back-end services. The default implementation performs no action.

requestEnd

public void requestEnd()

This method is used to inform the Nugget that requests are terminated. This method can be used by the Nugget developer to manage/optimize access to the nugget back-end services. The default implementation of this method performs no action.

isCachable

public abstract boolean isCachable()

This method indicates whether the Nugget implementation is a cachable nugget. A cachable nugget will be instantiate only once during the lifetime of the associated Entity. The nugget instance will be reused for future requests. On the other hand, a non-cachable nugget will be instantiated every time that the getNugget() method is invoked. A Nugget implementation can be cachable only if every method is thread safe and atomic. Namely, if there are multiple threads access it at the same time, they will not interfere each other.

Returns:

true if the Nugget implementation is cachable, false otherwise.

getEntity

public final Entity getEntity()

This method returns the reference of the Entity object that owns this Nugget instance.

Returns:

The Entity object that owns this nugget. It will never be null.