com.caplin.permissioning

Interface SwitchableSubjectMapper

All Superinterfaces:

SubjectMapper

All Known Implementing Classes:

SwitchByKeySubjectPatternMapper

Deprecated.

This interface exists purely to support a mode of TOBO that is inferior in many ways to the other supported TOBO modes. It is unnecessarily expensive in memory usage, creates potential for data inconsistencies if used incorrectly by an API client and is undocumented to strongly discourage its use. You should use one of the TOBO modes documented in the Permissioning Guides.

public interface SwitchableSubjectMapper
extends SubjectMapper

The SwitchableSubjectMapper interface extends the SubjectMapper interface, allowing:

• Multiple sets of subject mappings to be defined.
• The set of subject mappings that are currently being applied to be switched at the request of the client application.
• A default set of subject mappings to be applied when the end user logs in (or if the currently applied set of subject mappings are removed while the user is logged in).

A typical implementation of this interface is a class that switches subject mappings when the end user selects a different trading account. This allows the prices that are streamed to the end user to be tiered according to the selected account. For example, if the end user selects to trade using account-1, then subject mappings for account-1 are applied. If the end user then switches to trading account-2, subject mappings for account-2 are applied. In each case a different set of prices could be streamed to the end user depending on the account selected and the subject mappings that apply to that account.

The SwitchByKeySubjectPatternMapper class is a switchable subject mapper that implements this interface, and the documentation for this class includes an example that shows you how to set up switchable subject mappings. The SwitchByKeySubjectPatternMapper class is provided with the Permissioning Auth Module kit.

Configuring Liberator

To use a switchable subject mapper you must configure Liberator by deploying a javaauth.properties file on the classpath of the Permissioning Auth Module. This file must set the following properties.

• delegateToMapper: Set to true to enable the SwitchableSubjectMapper.
• ToboSubject: The subject of the RTTP message that the client application sends when it wants to switch subject mappings. This value is used internally by the Permissioning Auth Module to identify the RTTP message that contains the subject mapping request.
• ToboField: The value of this key determines which set of subject mappings the subject mapper should apply. The end user must have permission for Action on the value of this field (see Setting Permissions and creating a Permissioning Rule).

Setting Permissions and creating a Permissioning Rule

The Permissioning Auth Module will reject requests to switch subject mappings unless:

• A permissioning Rule has been created for switchable subject mappings.
• The end user requesting the switch is permitted to switch subject mappings.

The Rule for switchable subject mappings must identify the permission that the Permissioning Auth Module checks when it determines whether or not subject mappings can be switched. For example, if the name of the RTTP message field that contains the switch key is Account, and the value of this field is account-2, the Rule must instruct the Permissioning Auth Module to check that the user has permission for account-2 Action in the namespace used for account permissions.

For further information about Rules and how to create them, refer to the following documents:

• Permissioning 6.0: Permissioning Overview And Concepts.
• Permissioning 6.0: How To Create A Permissioning Adapter.
• The Rules section in the Overview of this API document.

Removing subject mappings while the end user is logged in

The Permissioning Auth Module keeps a record of the currently applied set of subject mappings, and calls switchToDefaultMappings() to switch to the default set if the currently applied set is removed while the end user is logged in.

When subject mappings are removed as part of a Permissioning transaction, it is important that the permission to switch to the removed mappings is also removed as part of the transaction.

The client application is not informed when subject mappings are added or removed, but is informed when permissions are added or removed. By removing the permission to switch subject mappings as part of the same transaction that removes the mappings, the client application can handle the situation (perhaps by requesting the end user to select another account).

Without this feedback the end user would continue to trade, not knowing that subject mappings (and hence the prices they see) had changed.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	switchMappings(java.lang.String keyField, java.util.Map<java.lang.String,java.lang.String> switchFields) Deprecated. This method is called by the Permissioning Auth Module when it receives an RTTP request from the client application to switch to a named set of subject mappings.
void	switchToDefaultMappings() Deprecated. This method is called by the Permissioning Auth Module when a user logs in, or if the set of subject mappings currently being applied are removed while the user is logged in.

Methods inherited from interface com.caplin.permissioning.SubjectMapper

mapSubject, setGlobalContext, updateMappings

Method Detail

switchMappings

boolean switchMappings(java.lang.String keyField,
                     java.util.Map<java.lang.String,java.lang.String> switchFields)

Deprecated.

This method is called by the Permissioning Auth Module when it receives an RTTP request from the client application to switch to a named set of subject mappings.

If the request refers to a valid set of subject mappings (that is, the set exists), the method must switch the currently used set to the requested set, and return true. This informs the client application that the requested switch was successful. After a successful switch, the subject mapper must map subjects using the current set of subject mappings (see SubjectMapper.mapSubject()).

If the request refers to an invalid set of subject mappings (that is, the set does not exist), the method must return false. This informs the client application that the requested switch was not successful.

Sets of subject mapping are added to the subject mapper when the Permissioning Auth Module calls the SubjectMapper.updateMappings() method.

The Permissioning Auth Module only calls this method if the end user is permitted to switch to the requested set of subject mappings (that is, has permission for Action on the value of the field identified by the keyField parameter).

Parameters:

keyField - the name of the RTTP field that contains the switch key. The value that switch key maps to in switchFields identifies the requested set of subject mappings.

switchFields - the fields of the RTTP message that requested the switch. One of these fields is the switch key (the mapping for keyField. The client application may send other RTTP fields and values in the switch request message..

Returns:

true if the switch was successfully made, false otherwise.

switchToDefaultMappings

void switchToDefaultMappings()

Deprecated.

This method is called by the Permissioning Auth Module when a user logs in, or if the set of subject mappings currently being applied are removed while the user is logged in.

After this method has been called, the subject mapper must map subjects using the default set of subject mappings (see SubjectMapper.mapSubject()). If a default set has not been defined in your code, then SubjectMapper.mapSubject() must return null when called, to indicate that the passed in subject has no mapping.

This method does not have a return value and must always succeed.