Home | Class Index

SDK Version: 3.11.4-302512

Documentation generated on 24 July 2015

Class
caplin.services.security

PermissionService

This class allows you to query the product permissions of the currently logged in user, or the permissions they have when they are trading on behalf of another user.

The methods of the PermissionService class fall into three distinct categories. Methods in the first category return permissioning data when called. This category can be used by the classes of your application that respond to user interactions. An example of where this category could be employed would be in the code that responds to user attempts to open a trade ticket. In this case the permission is determined when the user initiates the action.

Methods that return permissioning data when called are:

Methods in the second category allow you to register listeners that subscribe to current and future product permissions. This category can be used to register the classes of your application that need to be notified when user permissions change.

An example of where this category would be employed is in the code responsible for displaying trade tiles. Trade tiles are typically grouped in one or more panels on the screen and are always on display. If a user permission changes, this may require the status of one or more trade tiles to change; for example, the button that allows the user to trade from the tile may need to be disabled. By attaching a permission listener to the tile its status can be changed independently of what the user is doing; it is not be necessary for the user to initiate an action on the trade tile for the change in permission to take effect.

Methods that register or remove listeners are:

Methods in the third (and final) category allow you to retrieve user attributes. A user can be assigned any number of attributes in the form of name/value pairs. User attributes are not processed by the Permissioning Auth Module and therefore do not affect permissioning directly. A typical use would be to send information to Caplin Trader about the maximum tradable amount that a user is permitted to trade. Your application could then use this information to limit the tradeable amounts shown to the user.

Methods that return the value of a user attribute when called are #getUserAttribute and #getToboUserAttribute. Methods that register a subscription listener to current and future values of a user attribute are #addAttributeListener and #addToboUserAttributeListener.

Trading on behalf of (TOBO)

When a logged in user is 'trading on behalf of' (TOBO) another user, the permissions that are sent to and cached by the permissioning library depend on the permissioning mode the Permissioning Auth Module is configured to run in.

If the permissioning mode is SalesUser, only permissions for the logged in user are sent to the permissioning library. In this mode, the methods that return product permissions always return permissions for the logged in user, even if that user is trading on behalf of another user.

If the permissioning mode is SalesIntersectCustomerUser, permissions for both the logged in user and the user they are trading on behalf of are sent to and cached by the permissioning library. In this mode, the permissions returned by the methods of this class are the logical AND of the logged in user and the user they are trading on behalf of.

For permissions that reside in specified namespaces, the permissioning library can be configured to return permissions for the logged in user only, even if that user is trading on behalf of another user and the permissioning mode is SalesIntersectCustomerUser. For further information about setting up this configuration, refer to the document Caplin Trader: Permissioning Configuration XML Reference.

Constructor Summary

Attributes Name and Description
caplin.services.security.PermissionService()

This class returns permissioning data for the currently logged in user.

Field Summary

Attributes Name and Description
<static> caplin.services.security.PermissionService.ALL

A constant that is passed to #addPermissionSetListener to indicate that the listener is subscribing to "ALL" permissions.
<static> caplin.services.security.PermissionService.ALL_ACTIONS

A constant that is passed to #addPermissionSetListener to indicate that the listener is subscribing to "all actions".
<static> caplin.services.security.PermissionService.ALL_PRODUCTS

A constant that is passed to #addPermissionSetListener to indicate that the listener is subscribing to "all products".
<static> caplin.services.security.PermissionService.ALLOW

A constant that is passed to #addPermissionSetListener to indicate that the listener is subscribing to "ALLOW" permissions.
<static> caplin.services.security.PermissionService.DENY

A constant that is passed to #addPermissionSetListener to indicate that the listener is subscribing to "DENY" permissions.
<static> caplin.services.security.PermissionService.NO_PERMISSION

A constant that indicates that the item has no permissions.

Method Summary

Attributes Name and Description
void addAttributeListener(String sAttributeName, caplin.services.security.PermissionServiceListener oListener)

Registers a listener that subscribes to current and future values of a single user attribute.
int addGlobalPermissionListener(String sProduct, String sAction, caplin.services.security.PermissionServiceListener oListener)

Registers a listener that subscribes to current and future permissions for an action on a single product in the global (default) namespace.
int addPermissionListener(String sProduct, String sNamespace, String sAction, caplin.services.security.PermissionServiceListener oListener)

Registers a listener that subscribes to current and future permissions for an action on a single product in a given namespace.
int addPermissionSetListener(String sProduct, String sNamespace, String sType, caplin.services.security.PermissionServiceListener oListener)

Registers a listener that subscribes to a set of current and future permissions on a single product in a given namespace.
int addProductPermissionsListener(Array pProducts, String sNamespace, String sAction, Boolean bIsAuthorized, caplin.services.security.PermissionServiceListener oListener)

Registers a listener that subscribes to current and future permissions on a set of products.
void addToboUserAttributeListener(String sAttributeName, caplin.services.security.PermissionServiceListener oListener)

Registers a listener that subscribes to current and future values of a single user attribute.
Boolean canUserPerformAction(String sProduct, String sNamespace, String sAction)

Determines whether an action on a product is allowed or denied in a given permissioning namespace.
Boolean canUserPerformGlobalAction(String sProduct, String sAction)

Determines whether an action on a product is allowed or denied in the global (default) namespace.
Array getAllowPermissions(String sProduct, String sNamespace, Function fSortFunction)

Returns the set of actions that are allowed on a product within a given namespace.
Array getAllPermissions(String sProduct, String sNamespace)

Returns the entire set of permissioned actions on a product within a given namespace.
Array getDenyPermissions(String sProduct, String sNamespace)

Returns the set of actions that are denied on a product within a given namespace.
Array getPermissionedProducts(Array pProducts, String sNamespace, String sAction)

Given a list of products, returns the subset of that list on which a specified action is allowed.
Array getToboAllowedProducts(String sNamespace, String sAction)

Returns the products that have "Allow" permission for a given namespace and action.
Array getToboDeniedProducts(String sNamespace, String sAction)

Returns the products that have "Deny" permission for a given namespace and action.
String getToboUserAttribute(String sAttributeName)

Gets the current value of a user attribute.
Array getUnpermissionedProducts(Array pProducts, String sNamespace, String sAction)

Given a list of products, returns the subset of that list on which a specified action is denied.
Array getUserAllowedProducts(String sNamespace, String sAction)

Returns the products that have "Allow" permission for a given namespace and action.
String getUserAttribute(String sAttributeName)

Gets the current value of a user attribute.
Array getUserDeniedProducts(String sNamespace, String sAction)

Returns the products that have "Deny" permission for a given namespace and action.
void removeListener(int nListenerId)

Removes a listener from the listener register.

Constructor Detail

► caplin.services.security.PermissionService()

This class returns permissioning data for the currently logged in user.

Field Detail

► <static> String caplin.services.security.PermissionService.ALL

A constant that is passed to #addPermissionSetListener to indicate that the listener is subscribing to "ALL" permissions.

► <static> String caplin.services.security.PermissionService.ALL_ACTIONS

A constant that is passed to #addPermissionSetListener to indicate that the listener is subscribing to "all actions".

► <static> String caplin.services.security.PermissionService.ALL_PRODUCTS

A constant that is passed to #addPermissionSetListener to indicate that the listener is subscribing to "all products".

► <static> String caplin.services.security.PermissionService.ALLOW

A constant that is passed to #addPermissionSetListener to indicate that the listener is subscribing to "ALLOW" permissions.

► <static> String caplin.services.security.PermissionService.DENY

A constant that is passed to #addPermissionSetListener to indicate that the listener is subscribing to "DENY" permissions.

► <static> String caplin.services.security.PermissionService.NO_PERMISSION

A constant that indicates that the item has no permissions.

Method Detail

► void addAttributeListener(String sAttributeName, caplin.services.security.PermissionServiceListener oListener)

Registers a listener that subscribes to current and future values of a single user attribute. After calling this method, the registered listener will be notified of the value of the user attribute.

This is the value assigned to the logged in user. To be notified of the value assigned to the user they are trading on behalf of, call #addToboUserAttributeListener instead.

The listener that you register must implement caplin.services.security.PermissionServiceListener#onAttributeChanged, which is called when the listener is first registered and also when the value of the attribute changes.

Parameters
String sAttributeName The name of the user attribute that you want to subscribe to.
caplin.services.security.PermissionServiceListener oListener The listener object that will receive the subscription updates.

► int addGlobalPermissionListener(String sProduct, String sAction, caplin.services.security.PermissionServiceListener oListener)

Registers a listener that subscribes to current and future permissions for an action on a single product in the global (default) namespace. After calling this method, the registered listener will be notified of the permission that the user has for the requested action on the specified product.

The listener that you register must implement caplin.services.security.PermissionServiceListener#onSinglePermissionChanged, which is called when the listener is first registered and also when the product permission changes.

Note: If you want to specify a different namespace, then use #addPermissionListener instead.

Parameters
String sProduct The name of the product that the subscription is for (for example "/FX/EURUSD").
String sAction The action that the subscription is for (for example "TRADE").
caplin.services.security.PermissionServiceListener oListener The listener object that will receive the subscription updates.
Returns
A unique indentifier that allows the listener to be removed from the listener register (see #removeListener).
See
#canUserPerformGlobalAction
#removeListener

► int addPermissionListener(String sProduct, String sNamespace, String sAction, caplin.services.security.PermissionServiceListener oListener)

Registers a listener that subscribes to current and future permissions for an action on a single product in a given namespace. After calling this method, the registered listener will be notified of the permission that the user has for the requested action on the specified product.

The listener that you register must implement caplin.services.security.PermissionServiceListener#onSinglePermissionChanged, which is called when the listener is first registered and also when the product permission changes.

Note: If you want to specify the global (default) namespace, then use #addGlobalPermissionListener instead.

Parameters
String sProduct The name of the product that the subscription is for (for example "/FX/EURUSD").
String sNamespace The namespace in which the product permission resides (for example "tenors").
String sAction The action that the subscription is for (for example "TRADE").
caplin.services.security.PermissionServiceListener oListener The listener object that will receive the subscription updates.
Returns
A unique identifier that allows the listener to be removed from the listener register (see #removeListener).
See
#canUserPerformAction
#removeListener

► int addPermissionSetListener(String sProduct, String sNamespace, String sType, caplin.services.security.PermissionServiceListener oListener)

Registers a listener that subscribes to a set of current and future permissions on a single product in a given namespace. You can subscribe to #ALL permissions, #ALLOW permissions, or #DENY permissions.

After calling this method, the registered listener will be notified of the set of actions in the given namespace for which the user has the requested permission. A typical use would be to subscribe to the set of permitted tenors on a product.

The listener that you register must implement caplin.services.security.PermissionServiceListener#onPermissionsChanged, which is called when the listener is first registered and also when a product permission changes.

Parameters
String sProduct The name of the product that the subscription is for (for example "/FX/EURUSD").
String sNamespace (Optional) The namespace in which the product permission resides (for example "tenors"). If null, then the permission resides in the global (default) namespace.
String sType The type of permission that the subscription is for (#ALL, #ALLOW, or #DENY).
caplin.services.security.PermissionServiceListener oListener The listener object that will receive the subscription updates.
Returns
A unique identifier that allows the listener to be removed from the listener register (see #removeListener).
See
#getAllowPermissions
#getAllPermissions
#getDenyPermissions
#removeListener

► int addProductPermissionsListener(Array pProducts, String sNamespace, String sAction, Boolean bIsAuthorized, caplin.services.security.PermissionServiceListener oListener)

Registers a listener that subscribes to current and future permissions on a set of products. You can subscribe to products for which an action is either alllowed or denied.

After calling this method, the registered listener will be notified of the subset of products for which the user has the requested permission for the requested action.

The listener that you register must implement caplin.services.security.PermissionServiceListener#onPermissionsChanged, which is called when the listener is first registered and also when a permission changes for any product in the given set of products.

Parameters
Array pProducts An array of strings representing the set of products that the subscription is for.
String sNamespace (Optional) The namespace in which the product permission resides (for example "tenors"). If null, then the permission resides in the global (default) namespace.
String sAction The action that the subscription is for (for example "TRADE").
Boolean bIsAuthorized The type of permission that the subscription is for (true for allowed permissions and false for denied permissions).
caplin.services.security.PermissionServiceListener oListener The listener object that will receive the subscription updates.
Returns
A unique identifier that allows the listener to be removed from the listener register (see #removeListener).
See
#getPermissionedProducts
#getUnpermissionedProducts
#removeListener

► void addToboUserAttributeListener(String sAttributeName, caplin.services.security.PermissionServiceListener oListener)

Registers a listener that subscribes to current and future values of a single user attribute. After calling this method, the registered listener will be notified of the value of the user attribute.

This is the value assigned to the user that the logged in user is trading on behalf of. To be notified of the value assigned to the logged in user, call #addAttributeListener instead.

The listener that you register must implement caplin.services.security.PermissionServiceListener#onAttributeChanged, which is called when the listener is first registered and also when the value of the attribute changes.

If the user is not trading on behalf of any other user, null is passed to the listener when it is first registered.

Parameters
String sAttributeName The name of the user attribute that you want to subscribe to.
caplin.services.security.PermissionServiceListener oListener The listener object that will receive the subscription updates.

► Boolean canUserPerformAction(String sProduct, String sNamespace, String sAction)

Determines whether an action on a product is allowed or denied in a given permissioning namespace.

Note: If you want to specify the global (default) namespace, then use #canUserPerformGlobalAction instead.

Parameters
String sProduct The name of the product (for example "/FX/EURUSD").
String sNamespace The namespace in which the product permission resides (for example "tenors").
String sAction The action on which the permission may be granted (for example "TRADE").
Returns
true if the action is allowed, false if the action is denied.

► Boolean canUserPerformGlobalAction(String sProduct, String sAction)

Determines whether an action on a product is allowed or denied in the global (default) namespace.

Note: If you want to specify a different namespace, then use #canUserPerformAction instead.

Parameters
String sProduct The name of the product (for example "/FX/EURUSD").
String sAction The action on which the permission may be granted (for example "TRADE").
Returns
true if the action is allowed, false if the action is denied.

► Array getAllowPermissions(String sProduct, String sNamespace, Function fSortFunction)

Returns the set of actions that are allowed on a product within a given namespace. A typical use would be to retrieve the set of allowed tenors on a product.

Parameters
String sProduct The name of the product (for example "/FX/EURUSD").
String sNamespace (Optional) The namespace in which the product permissions reside (for example "tenors"). If null, then the permissions reside in the global (default) namespace.
Function fSortFunction (Optional) An optional function used to sort the list of permissions returned from the PermissionEngine, if not passed in, the permissions will be returned unsorted.
Returns
An array of strings representing actions that are allowed on the product.
See
#getAllPermissions
#getDenyPermissions
#addPermissionSetListener

► Array getAllPermissions(String sProduct, String sNamespace)

Returns the entire set of permissioned actions on a product within a given namespace. The entire set includes the actions that are allowed and the actions that are denied.

Parameters
String sProduct The name of the product (for example "/FX/EURUSD").
String sNamespace (Optional) The namespace in which the product permissions reside (for example "tenors"). If null, then the permissions reside in the global (default) namespace.
Returns
An array of strings representing all permissioned actions on the product (allowed and denied).
See
#getAllowPermissions
#getDenyPermissions
#addPermissionSetListener

► Array getDenyPermissions(String sProduct, String sNamespace)

Returns the set of actions that are denied on a product within a given namespace. A typical use would be to retrieve the set of denied tenors on a product.

Parameters
String sProduct The name of the product (for example "/FX/EURUSD").
String sNamespace (Optional) The namespace in which the product permissions reside (for example "tenors"). If null, then the permissions reside in the global (default) namespace.
Returns
An array of strings representing actions that are denied on the product.
See
#getAllPermissions
#getAllowPermissions
#addPermissionSetListener

► Array getPermissionedProducts(Array pProducts, String sNamespace, String sAction)

Given a list of products, returns the subset of that list on which a specified action is allowed.

Parameters
Array pProducts An array of strings representing the list of products being queried.
String sNamespace (Optional) The namespace in which the product permissions reside (for example "tenors"). If null, then the permissions reside in the global (default) namespace.
String sAction The action being queried.
Returns
An array of strings representing the subset of products on which the action is permitted.

► Array getToboAllowedProducts(String sNamespace, String sAction)

Returns the products that have "Allow" permission for a given namespace and action.

The allowed products are always for the user that the logged in user is trading on behalf of. To get allowed products for the logged in user only, call #getUserAllowedProducts instead.

Parameters
String sNamespace (Optional) The namespace in which the product permissions reside (for example "tenors"). If omitted or set to null, the product permissions reside in the global (default) namespace.
String sAction The action that is allowed (for example "1-Week").
Returns
An array of strings representing the allowed products. Each string in the array could be a JavaScript regular expression that matches more than one product. The array will be empty if the logged in user is not trading on behalf of another user.

► Array getToboDeniedProducts(String sNamespace, String sAction)

Returns the products that have "Deny" permission for a given namespace and action.

The denied products are always for the user that the logged in user is trading on behalf of. To get denied products for the logged in user only, call #getUserDeniedProducts instead.

Parameters
String sNamespace (Optional) The namespace in which the product permissions reside (for example "tenors"). If omitted or set to null, the product permissions reside in the global (default) namespace.
String sAction The action that is denied (for example "1-Week").
Returns
An array of strings representing the denied products. Each string in the array could be a JavaScript regular expression that matches more than one product. The array will be empty if the logged in user is not trading on behalf of another user.

► String getToboUserAttribute(String sAttributeName)

Gets the current value of a user attribute.

This is the value assigned to the user that the logged in user is trading on behalf of. To get the value assigned to the logged in user, call #getUserAttribute instead.

Parameters
String sAttributeName The name of the user attribute that you want the value of.
Returns
The value of the user attribute, or null if the user is not trading on behalf of another user.

► Array getUnpermissionedProducts(Array pProducts, String sNamespace, String sAction)

Given a list of products, returns the subset of that list on which a specified action is denied.

Parameters
Array pProducts An array of strings representing the list of products being queried.
String sNamespace (Optional) The namespace in which the product permissions reside (for example "tenors"). If null, then the permissions reside in the global (default) namespace.
String sAction The action being queried.
Returns
An array of strings representing the subset of products on which the action is denied.

► Array getUserAllowedProducts(String sNamespace, String sAction)

Returns the products that have "Allow" permission for a given namespace and action.

The allowed products are always for the logged in user only, even if they are trading on behalf of another user. To get allowed products for the user they are trading on behalf of, call #getToboAllowedProducts instead.

A typical use would be to get the users (as an array of products) that the logged in user can trade on behalf of (TOBO). By convention, the namespace of such products is "TradeOnBehalfOf" and the action is "ChangeTradeOnBehalfOfUser". For further information about TOBO, refer to the document Caplin Platform: Permissioning Overview And Concepts.

Parameters
String sNamespace (Optional) The namespace in which the product permissions reside (for example "tenors" or "TradeOnBehalfOf"). If omitted or set to null, the product permissions reside in the global (default) namespace.
String sAction The action that is allowed (for example "1-Week" or "ChangeTradeOnBehalfOfUser").
Returns
An array of strings representing the allowed products. Each string in the array could be a JavaScript regular expression that matches more than one product.

► String getUserAttribute(String sAttributeName)

Gets the current value of a user attribute.

This is the value assigned to the logged in user. To get the value assigned to a user they are trading on behalf of, call #getToboUserAttribute instead.

Parameters
String sAttributeName The name of the user attribute that you want the value of.
Returns
The value of the user attribute.

► Array getUserDeniedProducts(String sNamespace, String sAction)

Returns the products that have "Deny" permission for a given namespace and action.

The denied products are always for the logged in user only, even if they are trading on behalf of another user. To get denied products for the user they are trading on behalf of, call #getToboDeniedProducts instead.

Parameters
String sNamespace (Optional) The namespace in which the product permissions reside (for example "tenors"). If omitted or set to null, the product permissions reside in the global (default) namespace.
String sAction The action that is denied (for example "1-week").
Returns
An array of strings representing the denied products. Each string in the array could be a JavaScript regular expression that matches more than one product.

► void removeListener(int nListenerId)

Removes a listener from the listener register. The removed listener will no longer be notified of current or future product permissions.

Parameters
int nListenerId The unique identifier that was returned when the listener was registered.
See
#addPermissionListener
#addGlobalPermissionListener
#addProductPermissionsListener
#addPermissionSetListener