com.nitido.nim
Class NiM

java.lang.Object
  com.nitido.nim.NiM

All Implemented Interfaces:

NiMConstants

public final class NiM
extends java.lang.Object
implements NiMConstants

The NiM class provides application developers with a centralized access to all of NiM services such as entity management, profile management, logging, event monitoring, nugget management, and configuration management. NiM is a singleton class such that a running JVM can instantiate at most one instance of NiM.

Field Summary

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

Method Summary

void	deprovisionEntity(Credential targetCred, Entity adminEntity) This method will de-provision the entity associated to the given target credential.
java.lang.String	generateUniqueId() This method is used to generate a unique string identifier for each method invocation.
java.lang.String	getApplicationId() This method returns the identifier associated to the running NiM applicaiton.
Brand	getBrand(NimletInput input, Entity user) Get a brand object.
Brand	getDomainBrand(java.lang.String domain) Get a brand object for a given domain without relying on input or an authenticated entity.
Entity	getEntity(Credential credential) This method returns an instance of an Entity for the given credential.
java.lang.String	getEnvironmentId() This method returns the identifier of the environment (production, lab, development, etc.) where the NiM application is running.
static NiM	getInstance() This method is used to get the referece to the NiM object.
Logger	getLogger(java.lang.Class clazz) This method returns a reference to the NiM Logger object for the given class.
Logger	getLogger(java.lang.String name) This method returns a reference to the NiM Logger object for the given class name.
java.lang.String	getMessage(java.lang.String domainID, java.lang.String brandID, java.lang.String msgID, java.lang.String locale, java.lang.Object... msgParams) Get a translated message for this brand.
java.lang.String	getNodeId() This method returns the node identifier where the instance of NiM is running.
NotificationStatus	getNotificationStatus(java.lang.String ticket) This method is used to retrieve the status of a message that was given to the notification service to be sent out.
java.util.Properties	getPropertiesByFilter(java.lang.String searchFilter) This method returns all the properties whose keys satisfy the given search filter.
java.util.Properties	getPropertiesByPrefix(java.lang.String prefix) This method returns all the properties whose keys start with the given prefix.
java.lang.String	getProperty(java.lang.String name) This method returns the configuration property associated to the given name.
java.lang.String	getPropertyWithDefault(java.lang.String name, java.lang.String defaultValue) This method returns the configuration property associated to the given name.
java.lang.String	getRevisionId() This method returns the current revision identifier of the NiM applicaiton.
Brand	getSystemDefaultBrand() Get the system default brand for this installation.
User	getUser(Credential credential) This method returns a reference to an authenticated User.
void	logEvent(java.lang.String eventName, java.lang.String msg, Credential credential) This method is used to log application level events.
boolean	needToLogEvent(java.lang.String eventName, Credential credential) This method indicates whether the given event needs to be logged.
void	provisionEntity(EntityProvisionDescriptor descriptor, Entity adminEntity) This method is used to provision a new entity.
void	releaseEntity(Entity entity) This method is used to signal to the NiM that the Entity is dying.
java.lang.String	sendNotification(NotificationMessage msg) This method allows the application to send out messages to users both internal and external to the system.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static final NiM getInstance()

This method is used to get the referece to the NiM object. If the JVM does not have an instance of the NiM object, a new NiM instance will be automatically created. Otherwise, this method returns the previously created instance.

NOTE: This method is thread safe even though it is not a "synchronized method". It is because the underlying NiM object was instantiated by the static initializer and cannot be modified after the class has been loaded. The NiM instance can be "read" only, and therefore, this method doesn't need to be "synchronized".

Returns:

The reference to the singleton instance of NiM.

sendNotification

public final java.lang.String sendNotification(NotificationMessage msg)
                                        throws NotificationServiceException

This method allows the application to send out messages to users both internal and external to the system. The recipient(s) are specified in message object itself. If a ticket is returned the service has accepted the message for delivery and the client application will be able to check the status using this ticket.

Parameters:

msg - the message to be sent out

Returns:

a ticket which the client application may use to retrieve status updated using the NiM.getNotificationStatus() method

Throws:

NotificationServiceException - thrown if the message was not valid or if the notification service could not accept the message for delivery

getNotificationStatus

public final NotificationStatus getNotificationStatus(java.lang.String ticket)
                                               throws StatusNotFoundException

This method is used to retrieve the status of a message that was given to the notification service to be sent out.

Parameters:

ticket - the ticket returned by sendNotification()

Returns:

a status object which contains the status for each of the recipients of the message

Throws:

StatusNotFoundException - thrown if the ticket did not match any of the status objects being stored in the service's cache. The ticket may be invalid or enough time has passed and the status object has been cleaned up by the service.

getBrand

public final Brand getBrand(NimletInput input,
                            Entity user)

Get a brand object. If the BrandService is valid and running, this method will always return a valid Brand object. The underlying BrandService is responsible for performing the required fail over logic. (i.e. even if the user doesn't has a brand, or the specified brand is invalid, the BrandService will automatically fail over to the system brand's value).

Parameters:

input - the nimlet input from the current request

user - the currently logged in entity. If this brand object is required for an unauthenticated entity it may be left null.

Returns:

brand object for the given arguments.

Throws:

NiMRuntimException - if the BrandService is not specified or failed to be initialized.

getDomainBrand

public final Brand getDomainBrand(java.lang.String domain)

Get a brand object for a given domain without relying on input or an authenticated entity. If the BrandService is valid and running, this method will always return a valid Brand object. The underlying BrandService is responsible for performing the required fail over logic. (i.e. even if the domain doesn't has a brand, or the specified brand is invalid, the BrandService will automatically fail over to the system brand's value).

Parameters:

domain - domain whose default brand is to be retrieved

Returns:

the default brand for a given domain, or the system default brand if the domain was not found

Throws:

NiMRuntimException - if the BrandService is not specified or failed to be initialized.

getSystemDefaultBrand

public final Brand getSystemDefaultBrand()

Get the system default brand for this installation. If the BrandService is valid and running, this method will always return a valid Brand object. (If the nim configuration doesn't specified all the system default, the BrandService will not start at all.)

Returns:

Brand object for the system default brand

Throws:

NiMRuntimException - if the BrandService is not specified or failed to be initialized.

getMessage

public final java.lang.String getMessage(java.lang.String domainID,
                                         java.lang.String brandID,
                                         java.lang.String msgID,
                                         java.lang.String locale,
                                         java.lang.Object... msgParams)

Get a translated message for this brand. If the BrandService is valid and running, this method will always return a valid message string (as long as it is defined in the system default's language resource bundle). The underlying BrandService is responsible for performing the required fail over logic. (i.e. even if the user's brand didn't have the message, or the specified brand is invalid, the BrandService will automatically fail over to the domain default brand's and then system brand's value).

Parameters:

domainID - the domain ID

brandID - the brand ID

msgID - the message ID

locale - the locale to translate to

msgParams - the parameters (this arguments is optional, it may be an array of Objects or any number of arguments) to format the variables within the message

Returns:

translated and formatted string for the given message ID

Throws:

NiMRuntimException - if the BrandService is not specified or failed to be initialized.

generateUniqueId

public final java.lang.String generateUniqueId()

This method is used to generate a unique string identifier for each method invocation. The format of the uid and the scope of its uniqueness depend on the NiMUidGenerator implementation that was specified in the NiMDescriptor.xml file.

Returns:

a unique identifier

getLogger

public final Logger getLogger(java.lang.String name)

This method returns a reference to the NiM Logger object for the given class name. The logger object is used by application developers to log any error or debugging information.

Parameters:

name - The name of the class of the object requesting the logger.

Returns:

The reference to the Logger object.

getLogger

public final Logger getLogger(java.lang.Class clazz)

This method returns a reference to the NiM Logger object for the given class. The logger object is used by application developers to log any error or debugging information.

Parameters:

clazz - The class reference of the object that is requesting the logger.

Returns:

The reference to the Logger object

getPropertiesByPrefix

public final java.util.Properties getPropertiesByPrefix(java.lang.String prefix)

This method returns all the properties whose keys start with the given prefix. If no property matches the given prefix the method returns an empty Properties object.

Parameters:

prefix - The prefix used to search the configuration properties.

Returns:

The Properties object with all the properties whose keys start with the given prefix.

See Also:

Properties

getPropertiesByFilter

public final java.util.Properties getPropertiesByFilter(java.lang.String searchFilter)

This method returns all the properties whose keys satisfy the given search filter. If no property matches the search filter, the method returns an empty Properties object.

Parameters:

searchFilter - The search filter used to retrieve a set of configuration properties. The filter can be the full key name or a substring with the wildcard character "*". However, this substring CAN NOT contain other special characters such as "(", ")" or "/".

Returns:

The Properties object with all the configuration properties that matches the given search filter.

getProperty

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

This method returns the configuration property associated to the given name.

Parameters:

name - The name of the configuration property.

Returns:

The value of the requested configuration property.

getPropertyWithDefault

public final java.lang.String getPropertyWithDefault(java.lang.String name,
                                                     java.lang.String defaultValue)

This method returns the configuration property associated to the given name. If no property matches the given name, the method returns the given default value.

Parameters:

name - The name of the configuration property.

defaultValue - The return value if the given property name does not exist.

Returns:

The value of the requested configuration property.

getEntity

public final Entity getEntity(Credential credential)
                       throws IllegalCredentialException,
                              AuthenticationFailedException,
                              NiMException

This method returns an instance of an Entity for the given credential. This method can return different types of Entities. You can use the getUser() method to get an entity of type User.

Parameters:

credential - The credential that uniquely identifies the requested Entity.

Returns:

The reference to the authenticated entity associated to the given credential.

Throws:

IllegalCredentialException - If the given credential is null or invalid.

AuthenticationFailedException - If unable to authenticate the given entity credentials.

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

See Also:

Entity, User, getUser( Credential )

releaseEntity

public final void releaseEntity(Entity entity)

This method is used to signal to the NiM that the Entity is dying. This should be invoked before the application drops the reference to an Entity object.

NOTE: An Entity object is regarded as "destroyed" after this method is invoked, even if an exception is thrown by this method. No operation should be performed on the object afterward.

Parameters:

entity - The Entity object that is "dying".

getUser

public final User getUser(Credential credential)
                   throws java.lang.IllegalArgumentException,
                          AuthenticationFailedException,
                          NiMException

This method returns a reference to an authenticated User.

Parameters:

credential - The credential that uniquely identifies the requested User

Returns:

The reference to the requested user object.

Throws:

java.lang.IllegalArgumentException - If the given credential is null or the entity type parameter of the is invalid.

AuthenticationFailedException - If unable to authenticate the user with the given credential.

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

See Also:

getEntity( Credential )

provisionEntity

public final void provisionEntity(EntityProvisionDescriptor descriptor,
                                  Entity adminEntity)
                           throws java.lang.IllegalArgumentException,
                                  EntityProvisionException,
                                  PermissionDeniedException,
                                  NiMException

This method is used to provision a new entity. The actual provisioning of an entity is dependant on the implementation of the provisioning service module of NiM.

Parameters:

descriptor - The entity descriptor is data container that holds all the information necessary to provision the required Entity

adminEntity - The entity object of the administrator. The identifying credential of this administrator entity object should have enough privilege for provisioning a new entity

Throws:

java.lang.IllegalArgumentException - If any of the given arguments are null.

EntityProvisionException - If unable to cprovision the entity due to inconsistencies on the data in the EntityProvisionDescriptor and the back-end requirements.

PermissionDeniedException - If given Credential does not have permission to perform the required action.

NiMException - If unable to establish a connection with the back-end provisioning service.

deprovisionEntity

public final void deprovisionEntity(Credential targetCred,
                                    Entity adminEntity)
                             throws java.lang.IllegalArgumentException,
                                    PermissionDeniedException,
                                    NiMException

This method will de-provision the entity associated to the given target credential. The actual de-provisioning of an entity is dependant on the implementation of the de-provisioning service module of NiM.

Parameters:

targetCred - The identifying credential of the entity being de-provisioned.

adminEntity - The entity object of the administrator. The identifying credential of this administrator entity object should have enough privilege for deprovisioning an entity

Throws:

PermissionDeniedException - If the given credential does not have permission for the action.

NiMException - If unable to establish a connection with the back-end de-provisioning service.

java.lang.IllegalArgumentException

logEvent

public final void logEvent(java.lang.String eventName,
                           java.lang.String msg,
                           Credential credential)

This method is used to log application level events.

Parameters:

eventName - The name that uniquely identifies the event being logged.

msg - The log message associated to the event.

credential - The credential of the user logging the event.

needToLogEvent

public final boolean needToLogEvent(java.lang.String eventName,
                                    Credential credential)

This method indicates whether the given event needs to be logged.

The creation of the log message can consume a significant amount of time, a developer can first call this method to determine whether the corresponding log message is to be logged.

Parameters:

eventName - The name that uniquely identifies the event to be logged.

credential - The credential of the user logging the event

Returns:

True if the event needs to be "logged" otherwise it returns false.

getApplicationId

public final java.lang.String getApplicationId()

This method returns the identifier associated to the running NiM applicaiton. The application id is specified in the NiMDescriptor.xml file.

Returns:

The identifier of the NiM application.

getEnvironmentId

public final java.lang.String getEnvironmentId()

This method returns the identifier of the environment (production, lab, development, etc.) where the NiM application is running. The environment id is specified in the NiMDescriptor.xml file.

Returns:

The environment identifier where the NiM application is running.

getNodeId

public final java.lang.String getNodeId()

This method returns the node identifier where the instance of NiM is running.

Returns:

The node identifier where the instance of NiM is running.

getRevisionId

public final java.lang.String getRevisionId()

This method returns the current revision identifier of the NiM applicaiton. The revision id is specified in the NiMDescriptor.xml file.

Returns:

The revision identifier of the running NiM application.