Caplin Trader 4.8.0

Class: module:caplin/security/permissioning/AbstractPermissionService

module:caplin/security/permissioning/AbstractPermissionService

Constructor

new module:caplin/security/permissioning/AbstractPermissionService()

This class returns permissioning data for the currently logged in user. 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 module:caplin/security/permissioning/AbstractPermissionService#getUserAttribute and module:caplin/security/permissioning/AbstractPermissionService#getToboUserAttribute. Methods that register a subscription listener to current and future values of a user attribute are module:caplin/security/permissioning/AbstractPermissionService#addAttributeListener and module:caplin/security/permissioning/AbstractPermissionService#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.

Implements:

Methods

addAttributeListener(sAttributeName, 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 module:caplin/security/permissioning/AbstractPermissionService#addToboUserAttributeListener instead.

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

Parameters:
Name Type Description
sAttributeName String The name of the user attribute that you want to subscribe to.
oListener module:caplin/services/security/PermissionServiceListener The listener object that will receive the subscription updates.
Implements:

addGlobalPermissionListener(sProduct, sAction, 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 module: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 module:caplin/security/permissioning/AbstractPermissionService#addPermissionListener instead.

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

addPermissionListener(sProduct, sNamespace, sAction, 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 module: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 module:caplin/security/permissioning/AbstractPermissionService#addGlobalPermissionListener instead.

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

addPermissionSetListener(sProduct, sNamespaceopt, sType, 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 module:caplin/security/permissioning/AbstractPermissionService#ALL permissions, module:caplin/security/permissioning/AbstractPermissionService#ALLOW permissions, or module:caplin/security/permissioning/AbstractPermissionService#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 module:caplin/services/security/PermissionServiceListener#onPermissionsChanged, which is called when the listener is first registered and also when a product permission changes.

Parameters:
Name Type Attributes Description
sProduct String The name of the product that the subscription is for (for example "/FX/EURUSD").
sNamespace String <optional>
 The namespace in which the product permission resides (for example "tenors"). If null, then the permission resides in the global (default) namespace.
sType String The type of permission that the subscription is for (module:caplin/security/permissioning/AbstractPermissionService#ALL, module:caplin/security/permissioning/AbstractPermissionService#ALLOW, or module:caplin/security/permissioning/AbstractPermissionService#DENY).
oListener module:caplin/services/security/PermissionServiceListener The listener object that will receive the subscription updates.
Implements:
See:
Returns:
A unique identifier that allows the listener to be removed from the listener register (see module:caplin/security/permissioning/AbstractPermissionService#removeListener).

addPermissionTypeListener(product, namespace, action, type, listener) → {number}

A convenience method for #addPermissionListener that allows the type to be filtered.
Parameters:
Name Type Description
product string The name of the product
namespace string The namespace in which the product permission resides
action string The action the subscription is for
type string The type of permission that the subscription is for
listener PermissionServiceListener The listener that will receive permission updates
Implements:
Returns:
A unique identifier that allows the removal of the listener
Type
number

addProductPermissionsListener(pProducts, sNamespaceopt, sAction, bIsAuthorized, 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 module: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:
Name Type Attributes Description
pProducts Array An array of strings representing the set of products that the subscription is for.
sNamespace String <optional>
 The namespace in which the product permission resides (for example "tenors"). If null, then the permission resides in the global (default) namespace.
sAction String The action that the subscription is for (for example "TRADE").
bIsAuthorized Boolean The type of permission that the subscription is for (true for allowed permissions and false for denied permissions).
oListener module:caplin/services/security/PermissionServiceListener The listener object that will receive the subscription updates.
Implements:
See:
Returns:
A unique identifier that allows the listener to be removed from the listener register (see module:caplin/security/permissioning/AbstractPermissionService#removeListener).

addToboUserAttributeListener(sAttributeName, 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 module:caplin/security/permissioning/AbstractPermissionService#addAttributeListener instead.

The listener that you register must implement module: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:
Name Type Description
sAttributeName String The name of the user attribute that you want to subscribe to.
oListener module:caplin/services/security/PermissionServiceListener The listener object that will receive the subscription updates.
Implements:

canUserPerformAction(sProduct, sNamespace, 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 module:caplin/security/permissioning/AbstractPermissionService#canUserPerformGlobalAction instead.

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

canUserPerformGlobalAction(sProduct, sAction) → {boolean}

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 module:caplin/security/permissioning/AbstractPermissionService#canUserPerformAction instead.

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

getAllowPermissions(sProduct, sNamespaceopt, fSortFunctionopt)

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:
Name Type Attributes Description
sProduct String The name of the product (for example "/FX/EURUSD").
sNamespace String <optional>
 The namespace in which the product permissions reside (for example "tenors"). If null, then the permissions reside in the global (default) namespace.
fSortFunction function <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.
Implements:
See:
Returns:
An array of strings representing actions that are allowed on the product.

getAllPermissions(sProduct, sNamespaceopt)

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:
Name Type Attributes Description
sProduct String The name of the product (for example "/FX/EURUSD").
sNamespace String <optional>
 The namespace in which the product permissions reside (for example "tenors"). If null, then the permissions reside in the global (default) namespace.
Implements:
See:
Returns:
An array of strings representing all permissioned actions on the product (allowed and denied).

getDenyPermissions(sProduct, sNamespaceopt)

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:
Name Type Attributes Description
sProduct String The name of the product (for example "/FX/EURUSD").
sNamespace String <optional>
 The namespace in which the product permissions reside (for example "tenors"). If null, then the permissions reside in the global (default) namespace.
Implements:
See:
Returns:
An array of strings representing actions that are denied on the product.

getPermissionedProducts(pProducts, sNamespaceopt, sAction)

Given a list of products, returns the subset of that list on which a specified action is allowed.
Parameters:
Name Type Attributes Description
pProducts Array An array of strings representing the list of products being queried.
sNamespace String <optional>
 The namespace in which the product permissions reside (for example "tenors"). If null, then the permissions reside in the global (default) namespace.
sAction String The action being queried.
Implements:
Returns:
An array of strings representing the subset of products on which the action is permitted.

getToboAllowedProducts(sNamespaceopt, 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 module:caplin/security/permissioning/AbstractPermissionService#getUserAllowedProducts instead.

Parameters:
Name Type Attributes Description
sNamespace String <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.
sAction String The action that is allowed (for example "1-Week").
Implements:
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.

getToboDeniedProducts(sNamespaceopt, sAction) → {Array}

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 module:caplin/security/permissioning/AbstractPermissionService#getUserDeniedProducts instead.

Parameters:
Name Type Attributes Description
sNamespace String <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.
sAction String The action that is denied (for example "1-Week").
Implements:
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.
Type
Array

getToboUserAttribute(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 module:caplin/security/permissioning/AbstractPermissionService#getUserAttribute instead.

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

getUnpermissionedProducts(pProducts, sNamespaceopt, sAction)

Given a list of products, returns the subset of that list on which a specified action is denied.
Parameters:
Name Type Attributes Description
pProducts Array An array of strings representing the list of products being queried.
sNamespace String <optional>
 The namespace in which the product permissions reside (for example "tenors"). If null, then the permissions reside in the global (default) namespace.
sAction String The action being queried.
Implements:
Returns:
An array of strings representing the subset of products on which the action is denied.

getUserAllowedProducts(sNamespaceopt, 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 module:caplin/security/permissioning/AbstractPermissionService#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:
Name Type Attributes Description
sNamespace String <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.
sAction String The action that is allowed (for example "1-Week" or "ChangeTradeOnBehalfOfUser").
Implements:
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.

getUserAttribute(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 module:caplin/security/permissioning/AbstractPermissionService#getToboUserAttribute instead.

Parameters:
Name Type Description
sAttributeName String The name of the user attribute that you want the value of.
Implements:
Returns:
The value of the user attribute.

getUserDeniedProducts(sNamespaceopt, 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 module:caplin/security/permissioning/AbstractPermissionService#getToboDeniedProducts instead.

Parameters:
Name Type Attributes Description
sNamespace String <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.
sAction String The action that is denied (for example "1-week").
Implements:
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.

removeListener(nListenerId)

Removes a listener from the listener register. The removed listener will no longer be notified of current or future product permissions.
Parameters:
Name Type Description
nListenerId int The unique identifier that was returned when the listener was registered.
Implements:
See: