com.caplin.permissioning

Class PermissioningDataSource

java.lang.Object

com.caplin.permissioning.PermissioningDataSource

public class PermissioningDataSource
extends java.lang.Object

When a PermissioningDataSource is constructed it must be supplied with a DataSource object. The DataSource object allows the PermissioningDataSource to communicate with Liberator using the DataSource protocol.

Constructor Summary

Constructors

Constructor and Description
PermissioningDataSource(DataSource dataSource, Role role) Creates a new PermissioningDataSource having a given role (master or slave) and an associated DataSource instance that allows the PermissioningDataSource to communicate with Liberator.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	actionExists(java.lang.String action) A convenience method that will tell you if a rule for an action has been sent to Liberator.
void	commitTransaction() Finishes a transaction and sends the data for that transaction to the remote Liberator.
void	createActionRefRule(java.lang.String subjectNameMatch, java.util.Map<java.lang.String,java.lang.String> fieldMatchCriteria, java.lang.String permissionNameSpace, java.lang.String actionRef, java.lang.String productRef) Creates a new Rule for an action on a product.
void	createActionRefRule(java.lang.String subjectNameMatch, java.lang.String permissionNameSpace, java.lang.String actionRef, java.lang.String productRef) Creates a new Rule for an action on a product.
void	createActionRule(java.lang.String subjectNameMatch, java.util.Map<java.lang.String,java.lang.String> fieldMatchCriteria, java.lang.String permissionNameSpace, java.lang.String action, java.lang.String productRef) Creates a new Rule for an action on a product.
void	createActionRule(java.lang.String subjectNameMatch, java.lang.String permissionNameSpace, java.lang.String action, java.lang.String productRef) Creates a new Rule for an action on a product.
Group	createGroup(java.lang.String name) Creates a new Group in this PermissioningDataSource.
User	createUser(java.lang.String name) Creates a new, KeyMaster authenticated User that is known to this PermissioningDataSource.
User	createUser(java.lang.String name, java.lang.String password) Creates a new, text password authenticated User that is known to this PermissioningDataSource.
java.lang.String	dump() Prints structure of cached permission data, used for debugging
Group	getGroup(java.lang.String groupName) Retrieve an existing Group that is already known to this PermissioningDataSource.
java.lang.String	getName() Gets the name of the PermissioningDataSource.
User	getUser(java.lang.String userName) Retrieve an existing User that is already known to this PermissioningDataSource.
boolean	isMaster() Indicates the role of the PermissioningDataSource.
boolean	isTransactionInProgress() Determine whether an underlying transaction is already in progress - use before invoking startTransaction to guard against a TransactionInProgressException
void	removeGlobalContextData(java.lang.String identifier) Removes from the GlobalContext, the data identified by identifier.
void	removeGroup(Group group) Removes a given group and implicitly removes the group from all groups of which it is a member.
void	removeUser(User user) Removes a given User and implicitly removes the User from any Groups of which it is a member.
void	rollbackTransaction() Reverts the PermissioningDataSource data to its state before the current transaction was started.
void	startImageTransaction() Starts an image transaction, which should be used to set the permissioning data.
void	startImageTransaction(boolean rollbackSupported) Starts an image transaction, which should be used to set the permissioning data.
void	startUpdateTransaction() Starts an update transaction, which should be used to make changes to the existing permissioning data.
void	startUpdateTransaction(boolean rollbackSupported) Starts an update transaction, which should be used to make changes to the existing permissioning data.
java.lang.String	toString() Returns a string that describes this PermissioningDataSource , including its master/slave role and the message protocol that it uses.
void	updateGlobalContext(java.lang.String identifier, java.util.Map<java.lang.String,java.lang.String> data) Adds data to the GlobalContext.

Methods inherited from class java.lang.Object

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

Constructor Detail

PermissioningDataSource

public PermissioningDataSource(DataSource dataSource,
                       Role role)

Creates a new PermissioningDataSource having a given role (master or slave) and an associated DataSource instance that allows the PermissioningDataSource to communicate with Liberator.

Parameters:

dataSource - The DataSource used to communicate with the Liberator.

role - The Role can be set to either master or slave. There can only be one master but there can be zero or more slaves. If the role is SLAVE, the slave name must be set by giving the DataSource the --permission.rolename argument when the DataSource is instantiated. For more information on roles, see the documents Caplin Permissioning: Permissioning Overview and Concepts and Caplin Permissioning: How To Create A Permissioning DataSource Adapter. The second document contains example code that shows how to construct both master and slave PermissioningDataSources.

Method Detail

startUpdateTransaction

public void startUpdateTransaction()
                            throws TransactionInProgressException

Starts an update transaction, which should be used to make changes to the existing permissioning data. An update transaction is a transaction in which one can make changes to the existing permissioning data - a relative change. If one wishes to reset all of the permissioning data and provide a new absolute set of permissioning data, one should start an image transaction using the startImageTransaction() method.

Transactions must be used in order to atomically send a set of changes to the permissioning data to the remote Liberator. A transaction must be started in order to create, remove or mutate Users, Groups or Rules.

Note: by default this will enable/disable rollback based on the global rollbackEnalbed flag.

Note: Only one transaction can be in progress at any time.

Throws:

TransactionInProgressException - if a transaction is already in progress.

startUpdateTransaction

public void startUpdateTransaction(boolean rollbackSupported)
                            throws TransactionInProgressException

Starts an update transaction, which should be used to make changes to the existing permissioning data. An update transaction is a transaction in which one can make changes to the existing permissioning data - a relative change. If one wishes to reset all of the permissioning data and provide a new absolute set of permissioning data, one should start an image transaction using the startImageTransaction() method.

Transactions must be used in order to atomically send a set of changes to the permissioning data to the remote Liberator. A transaction must be started in order to create, remove or mutate Users, Groups or Rules.

Note: Only one transaction can be in progress at any time.

Parameters:

rollbackSupported - if this is specified to true changes will be tracked and rollback will be permitted. If not changes will not be tracked and a call to commit will trigger a commit instead. The primary reason for disabling rollback is to remove the impact on performance in environments where it is known that rollback functionality will not be needed.

Throws:

TransactionInProgressException - if a transaction is already in progress.

startImageTransaction

public void startImageTransaction()
                           throws TransactionInProgressException

Starts an image transaction, which should be used to set the permissioning data. After an image transaction completes, only data that was added in that transaction will be present in the system. All data that was in the system before is removed, unless it is re-added in the image transaction. If one wishes to merely change the existing permissioning data one should use an update transaction, which is created using the startUpdateTransaction() method.

Transactions must be used in order to automatically send a set of changes to the permissioning data to the remote Permissioning Auth Module. A transaction must be started in order to create, remove or mutate Users, Groups or Rules.

Note: by default this will enable/disable rollback based on the global rollbackEnalbed flag.

Note: Only one transaction can be in progress at any time.

Throws:

TransactionInProgressException - if a transaction is already in progress.

startImageTransaction

public void startImageTransaction(boolean rollbackSupported)
                           throws TransactionInProgressException

Starts an image transaction, which should be used to set the permissioning data. After an image transaction completes, only data that was added in that transaction will be present in the system. All data that was in the system before is removed, unless it is re-added in the image transaction. If one wishes to merely change the existing permissioning data one should use an update transaction, which is created using the startUpdateTransaction() method.

Transactions must be used in order to automatically send a set of changes to the permissioning data to the remote Permissioning Auth Module. A transaction must be started in order to create, remove or mutate Users, Groups or Rules.

Note: Only one transaction can be in progress at any time.

Parameters:

rollbackSupported - if this is specified to true changes will be tracked and rollback will be permitted. If not changes will not be tracked and a call to commit will trigger a commit instead. The primary reason for disabling rollback is to remove the impact on performance in environments where it is known that rollback functionality will not be needed.

Throws:

TransactionInProgressException - if a transaction is already in progress.

commitTransaction

public void commitTransaction()
                       throws NoTransactionInProgressException

Finishes a transaction and sends the data for that transaction to the remote Liberator. This method is used to commit both types of transaction; image transactions and update transactions. Invoke this method after creating, removing or mutating Users, Groups or Rules in order to atomically send all the changes to the Liberator

Throws:

NoTransactionInProgressException - if there is no in-progress transaction to commit.

rollbackTransaction

public void rollbackTransaction()

Reverts the PermissioningDataSource data to its state before the current transaction was started. This can be used to effectively cancel all the changes made in both types of transaction.

WARNING: During rollback, all permissioning objects within the PermissioningDataSource are replaced with a copy of the objects from when the transaction was started. This means that if you are holding any permissioning objects you should throw them away and retrieve new objects using getGroup(String) and getUser(String). If you try to use the old objects they will no longer be valid and throw an IllegalStateException.

Throws:

NoTransactionInProgressException - if there is no in-progress transaction to commit.

isTransactionInProgress

public boolean isTransactionInProgress()

Determine whether an underlying transaction is already in progress - use before invoking startTransaction to guard against a TransactionInProgressException

Returns:

true if an underlying transaction is already in progress. Otherwise returns false.

createUser

public User createUser(java.lang.String name)

Creates a new, KeyMaster authenticated User that is known to this PermissioningDataSource. The created User will be sent to the Liberator upon the committing the current transaction. The User can only be removed from this PermissioningDataSource by calling removeUser(User) after which the User object is useless (you must create it again if you wish to re-add the User).

Parameters:

name - the new User's login name.

Returns:

the newly created User.

Throws:

NoTransactionInProgressException - if this method is called outside the scope of a transaction.

createUser

public User createUser(java.lang.String name,
              java.lang.String password)

Creates a new, text password authenticated User that is known to this PermissioningDataSource. The created User will be sent to the Liberator upon the committing the current transaction. The User can only be removed from this PermissioningDataSource by calling removeUser(User) after which the User object is useless (you must create it again if you wish to re-add the User).

Note: Only a master PermissioningDataSource can set the User's password.

Parameters:

name - the new User's login name.

password - the new User's login password.

Returns:

the newly created User.

Throws:

NoTransactionInProgressException - if this method is called outside the scope of a transaction.

createGroup

public Group createGroup(java.lang.String name)

Creates a new Group in this PermissioningDataSource. The Group is sent to the Liberator when the current transaction is committed.

To remove (detach) a Group from a PermissioningDataSource, call removeGroup(Group). If you want to re-use a group after it has been removed, you must call createGroup again to re-create the Group.

This method must be called as part of a transaction.

Parameters:

name - the name of the new Group.

Throws:

NoTransactionInProgressException - if this method is called outside the scope of a transaction.

getUser

public User getUser(java.lang.String userName)

Retrieve an existing User that is already known to this PermissioningDataSource.

Parameters:

userName - The name of the user for which the permissioning data will be returned.

Returns:

A User object containing permissioning data for userName.

Throws:

PermissionableNotFoundException - If the User with userName does not exist.

getGroup

public Group getGroup(java.lang.String groupName)

Retrieve an existing Group that is already known to this PermissioningDataSource.

Parameters:

groupName - The name of the group for which the permissioning data will be returned.

Returns:

A Group object containing permissioning data for groupName.

Throws:

PermissionableNotFoundException - If groupName does not exist.

removeUser

public void removeUser(User user)
                throws NoTransactionInProgressException

Removes a given User and implicitly removes the User from any Groups of which it is a member. Upon commit of this transaction, the Liberator is notified of the deletion. If the User is logged in, they will be ejected. The User will not be able to log in to the Liberator.

Parameters:

user - the User to be removed.

Throws:

NoTransactionInProgressException - if this method is called outside the scope of a transaction.

removeGroup

public void removeGroup(Group group)
                 throws NoTransactionInProgressException

Removes a given group and implicitly removes the group from all groups of which it is a member. Furthermore, any members of the group being removed remain on the system but are no longer members of this group.

Upon commit of this transaction, the Liberator is notified of the deletion and re-checks all permissions for affected Users.

Parameters:

group - the Group to be removed

Throws:

NoTransactionInProgressException - if this method is called outside the scope of a transaction.

createActionRefRule

public void createActionRefRule(java.lang.String subjectNameMatch,
                       java.lang.String permissionNameSpace,
                       java.lang.String actionRef,
                       java.lang.String productRef)

Creates a new Rule for an action on a product. Call this method if a field in the RTTP message contains the action for this Rule.

When a User attempts to trade a product, the Permissioning Auth Module inspects the content of the received RTTP message and tries to match the message subject with one or more Rules. If a Rule matches the message subject, the permission for the action specified by the Rule determines whether or not the request is allowed or denied.

Note: Only a master PermissioningDataSource can create a Rule.

This method must be called as part of an image transaction ( startImageTransaction()). The Rule is sent to the Liberator when the transaction is committed.

Parameters:

subjectNameMatch - A regular expression that is used to match the subject of the RTTP message. The regular expression can contain the substitution tokens %u or %U. When a subject is being matched to a Rule, the Permissioning Auth Module replaces %u with the username of the logged in User, and %U with the allocated session name. To match against the literal value of a token, escape the token with '\' (as in \%u).

permissionNameSpace - The namespace of the permission that either allows or denies the action.

actionRef - Permission for the action specified in this RTTP message field is checked to see if the message is allowed or denied.

productRef - Permission for the product specified in this RTTP message field is checked to see if the message is allowed or denied.

Throws:

NoTransactionInProgressException - if this method is called outside the scope of a transaction.

See Also:

Permissioning Rules

createActionRefRule

public void createActionRefRule(java.lang.String subjectNameMatch,
                       java.util.Map<java.lang.String,java.lang.String> fieldMatchCriteria,
                       java.lang.String permissionNameSpace,
                       java.lang.String actionRef,
                       java.lang.String productRef)

Creates a new Rule for an action on a product. Call this method if a field in the RTTP message contains the action for this Rule, and if the Rule must match other known message fields and values.

When a User attempts to trade a product, the Permissioning Auth Module inspects the content of the received RTTP message and tries to match the message subject with one or more Rules. If a Rule matches the message subject, the permission for the action specified by the Rule determines whether or not the request is allowed or denied.

Note: Only a master PermissioningDataSource can create a Rule.

This method must be called as part of an image transaction ( startImageTransaction()). The Rule is sent to the Liberator when the transaction is committed.

Parameters:

subjectNameMatch - A regular expression that is used to match the subject of the RTTP message. The regular expression can contain the substitution tokens %u or %U. When a subject is being matched to a Rule, the Permissioning Auth Module replaces %u with the username of the logged in User, and %U with the allocated session name. To match against the literal value of a token, escape the token with '\' (as in \%u).

fieldMatchCriteria - A map of RTTP message fields and values. The Rule will only match the message if the message contains these fields and values.

permissionNameSpace - The namespace of the permission that either allows or denies the action.

actionRef - Permission for the action specified in this RTTP message field is checked to see if the message is allowed or denied.

productRef - Permission for the product specified in this RTTP message field is checked to see if the message is allowed or denied.

Throws:

NoTransactionInProgressException - if this method is called outside the scope of a transaction.

See Also:

Permissioning Rules

createActionRule

public void createActionRule(java.lang.String subjectNameMatch,
                    java.lang.String permissionNameSpace,
                    java.lang.String action,
                    java.lang.String productRef)

Creates a new Rule for an action on a product. Call this method if you want to pass in the action as a parameter.

When a User attempts to trade a product, the Permissioning Auth Module inspects the content of the received RTTP message and tries to match the message subject with the subjectNameMatch of one or more Rules. If a Rule created with an action matches the message subject, the permission for the action specified by the Rule determines whether or not the message is allowed or denied.

Note: Only a master PermissioningDataSource can create a Rule.

This method must be called as part of an image transaction ( startImageTransaction()). The Rule is sent to the Liberator when the transaction is committed.

Parameters:

subjectNameMatch - A regular expression that is used to match the subject of the RTTP message. The regular expression can contain the substitution tokens %u or %U. When a subject is being matched to a Rule, the Permissioning Auth Module replaces %u with the username of the logged in User, and %U with the allocated session name. To match against the literal value of a token, escape the token with '\' (as in \%u).

permissionNameSpace - The namespace of the permission that either allows or denies the action.

action - permission for this action is checked to see if the message is allowed or denied.

productRef - permission for the product specified in this RTTP message field is checked to see if the message is allowed or denied.

Throws:

NoTransactionInProgressException - if this method is called outside the scope of a transaction.

See Also:

Permissioning Rules

createActionRule

public void createActionRule(java.lang.String subjectNameMatch,
                    java.util.Map<java.lang.String,java.lang.String> fieldMatchCriteria,
                    java.lang.String permissionNameSpace,
                    java.lang.String action,
                    java.lang.String productRef)

Creates a new Rule for an action on a product. Call this method if you want to pass in the action as a parameter, and if the Rule must match known RTTP message fields and values.

When a User attempts to trade a product, the Permissioning Auth Module inspects the content of the received RTTP message and tries to match the message subject with the subjectNameMatch of one or more Rules. If a Rule created with an action matches the message subject, the permission for the action specified by the Rule determines whether or not the message is allowed or denied.

Note: Only a master PermissioningDataSource can create a Rule.

This method must be called as part of an image transaction ( startImageTransaction()). The Rule is sent to the Liberator when the transaction is committed.

Parameters:

subjectNameMatch - A regular expression that is used to match the subject of the RTTP message. The regular expression can contain the substitution tokens %u or %U. When a subject is being matched to a Rule, the Permissioning Auth Module replaces %u with the username of the logged in User, and %U with the allocated session name. To match against the literal value of a token, escape the token with '\' (as in \%u).

fieldMatchCriteria - A map of RTTP message fields and values. The Rule will only match the message if the message contains these fields and values.

permissionNameSpace - The namespace of the permission that either allows or denies the action.

action - permission for this action is checked to see if the message is allowed or denied.

productRef - permission for the product specified in this RTTP message field is checked to see if the message is allowed or denied.

Throws:

NoTransactionInProgressException - if this method is called outside the scope of a transaction.

See Also:

Permissioning Rules

actionExists

public boolean actionExists(java.lang.String action)

A convenience method that will tell you if a rule for an action has been sent to Liberator. You send an action to Liberator when you send the rule that identifies the action.

Parameters:

action - The action that you want to check.

Returns:

true if the rule exists, otherwise false.

getName

public java.lang.String getName()

Gets the name of the PermissioningDataSource. A name is assigned when the permission.rolename argument is set on the DataSource.

Returns:

the name of the PermissioningDataSource.

isMaster

public boolean isMaster()

Indicates the role of the PermissioningDataSource.

Returns:

true if the role is master, or false if the role is slave.

Throws:

java.lang.NullPointerException - if the role of the PermissioningDataSource has not been set.

toString

public java.lang.String toString()

Returns a string that describes this PermissioningDataSource , including its master/slave role and the message protocol that it uses.

Overrides:

toString in class java.lang.Object

Returns:

a string that describes this PermissioningDataSource , including its master/slave role and the message protocol that it uses.

dump

public java.lang.String dump()

Prints structure of cached permission data, used for debugging

Returns:

a string containing the formatted cached data

updateGlobalContext

public void updateGlobalContext(java.lang.String identifier,
                       java.util.Map<java.lang.String,java.lang.String> data)

Adds data to the GlobalContext. This method must be called as part of an image or update transaction, and the request to add the data and identifier is sent to Liberator when the transaction is committed.

Note that unlike other permissioning data, an image transaction does not remove GlobalContext data that was added in previous transactions (see startImageTransaction()).

To remove data from the GlobalContext, pass the identifier for that data to removeGlobalContextData(). Because removeGlobalContextData() removes all data for an identifier, it is recommended that two PermissioningDataSources do not add or remove data for the same identifier.

Parameters:

identifier - A String that uniquely identifies data in the GlobalContext.

data - A Map of key-value pairs.

removeGlobalContextData

public void removeGlobalContextData(java.lang.String identifier)

Removes from the GlobalContext, the data identified by identifier. This method must be called as part of an image or update transaction. The signal to remove the data is sent to Liberator when the transaction is committed.

Note that this method removes all data for this identifier, including any data that was added by another PermissioningDataSource (see updateGlobalContext()).

Parameters:

identifier - A String that uniquely identifies the data in the GlobalContext.