Package com.caplin.permissioning

Class PermissioningDataSource

java.lang.Object
com.caplin.permissioning.PermissioningDataSource
public class PermissioningDataSource extends 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
    Description
    PermissioningDataSource(com.caplin.datasource.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

    Modifier and Type
    Method
    Description
    boolean
    actionExists(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(String subjectNameMatch, String permissionNameSpace, String actionRef, String productRef)
    Creates a new Rule for an action on a product.
    void
    createActionRefRule(String subjectNameMatch, Map<String,String> fieldMatchCriteria, String permissionNameSpace, String actionRef, String productRef)
    Creates a new Rule for an action on a product.
    void
    createActionRule(String subjectNameMatch, String permissionNameSpace, String action, String productRef)
    Creates a new Rule for an action on a product.
    void
    createActionRule(String subjectNameMatch, Map<String,String> fieldMatchCriteria, String permissionNameSpace, String action, String productRef)
    Creates a new Rule for an action on a product.
    Group
    createGroup(String name)
    Creates a new Group in this PermissioningDataSource.
    User
    createUser(String name)
    Creates a new, KeyMaster authenticated User that is known to this PermissioningDataSource.
    User
    createUser(String name, String password)
    Creates a new, text password authenticated User that is known to this PermissioningDataSource .
    String
    dump()
    Prints structure of cached permission data, used for debugging
    Group
    getGroup(String groupName)
    Retrieve an existing Group that is already known to this PermissioningDataSource.
    String
    getName()
    Gets the name of the PermissioningDataSource.
    User
    getUser(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(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
    setUserRequestListener(UserRequestListener listener)
    Registers a UserRequestListener to be called back when a user container is requested or discarded.
    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.
    String
    toString()
    Returns a string that describes this PermissioningDataSource , including its master/slave role and the message protocol that it uses.
    void
    updateGlobalContext(String identifier, Map<String,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 Details

    • PermissioningDataSource

      public PermissioningDataSource(com.caplin.datasource.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 Details

    • 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(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(String name, 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(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.
      Returns:
      The created Group
      Throws:
      NoTransactionInProgressException - if this method is called outside the scope of a transaction.

    • getUser

      public User getUser(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. null if the User userName does not exist.

    • getGroup

      public Group getGroup(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. null if Group 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(String subjectNameMatch, String permissionNameSpace, String actionRef, 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:

    • createActionRefRule

      public void createActionRefRule(String subjectNameMatch, Map<String,String> fieldMatchCriteria, String permissionNameSpace, String actionRef, 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.

      The fieldMatchCriteria can contain some special values as detailed below:

      Special Field Name Description
      *APPLICATION_ID Match the users StreamLink Application Id against the regular expression given as the value.
      *KEYMASTER_TOKEN:<token>

      Match the users KeyMaster extra parameters token against the regular expression given as the value.

      For example given a field of *KEYMASTER_TOKEN:TRADING and a value of TRUE, then the rule would only fire if the KeyMaster password token contained an extra data parameter for TRADING=TRUE.
      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:

    • createActionRule

      public void createActionRule(String subjectNameMatch, String permissionNameSpace, String action, 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:

    • createActionRule

      public void createActionRule(String subjectNameMatch, Map<String,String> fieldMatchCriteria, String permissionNameSpace, String action, 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.

      The fieldMatchCriteria can contain some special values as detailed below:

      Special Field Name Description
      *APPLICATION_ID Match the users StreamLink Application Id against the regular expression given as the value.
      *KEYMASTER_TOKEN:<token>

      Match the users KeyMaster extra parameters token against the regular expression given as the value.

      For example given a field of *KEYMASTER_TOKEN:TRADING and a value of TRUE, then the rule would only fire if the KeyMaster password token contained an extra data parameter for TRADING=TRUE.
      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:

    • actionExists

      public boolean actionExists(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 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:
      NullPointerException - if the role of the PermissioningDataSource has not been set.

    • toString

      public 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 Object
      Returns:
      a string that describes this PermissioningDataSource , including its master/slave role and the message protocol that it uses.

    • dump

      public String dump()
      Prints structure of cached permission data, used for debugging
      Returns:
      a string containing the formatted cached data

    • updateGlobalContext

      public void updateGlobalContext(String identifier, Map<String,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(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.

    • setUserRequestListener

      public void setUserRequestListener(UserRequestListener listener)
      Registers a UserRequestListener to be called back when a user container is requested or discarded. This can be used to add users to the store on demand. The datasource response to the request is delayed until the callback returns. All callbacks will occur synchronously on a single thread. Setting the value to null removes the listener.
      Parameters:
      listener - a listener for the request and discard events.