Caplin Systems - TieringAuthenticator (Liberator Auth API 7.1.2-311825)

java.lang.Object
- examples.TieringAuthenticator

All Implemented Interfaces:

Authenticator
```
public class TieringAuthenticator
extends java.lang.Object
implements Authenticator
```
A simple Authenticator implementation that demonstrates: - mapping of requested symbols onto different underlying symbols (at request time) - dynamic mapping of subscribed symbols (at any time) - a naive example of underlying symbols being altered at run-time

Constructor Summary

Constructors
Constructor and Description

TieringAuthenticator()

Constructors
Constructor and Description
`TieringAuthenticator()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`AuthenticationResult`	`authoriseHTTP(AuthenticationUser user)` This method will be called when an HTTP directory access authorisation is required.
`java.lang.String`	`calculateMappedObject(java.lang.String subscription)` Given an FX subscription, extract the branch and currency pair, and use them to convert the associated amount into a tier.
`void`	`changeTiers()` NOTE: This is a naive algorithm to change the tier values from one set to another, (and back again next time) In a production system this would be achieved by the receipt of permission objects sent from a DataSource.
`AuthenticationResult`	`checkPermissionUpdate(UserSession session, RTTPObject object, java.lang.String key, java.util.Map<java.lang.String,java.lang.String> fieldValues)` Called on every update to a permission object to allow the Authenticator to authenticate each update based on content.
`AuthenticationResult`	`checkRead(UserSession session, RTTPObject object, java.lang.String requestedName)` This method will be called to check authentication every time a user tries to read an object.
`AuthenticationResult`	`checkUpdate(UserSession session, RTTPObject object, java.lang.String data)` Called on every update to an object (currently only news headline objects) to allow the Authenticator to authenticate each update based on content.
`AuthenticationResult`	`checkUser(UserSession session)` The user login authorisation method which is called every time a user tries to login to the server.
`AuthenticationResult`	`checkWrite(UserSession session, RTTPObject object, java.lang.String requestedName, java.lang.String contributionId, java.util.Map<java.lang.String,java.lang.String> fields)` This method will be called to check authentication every time a user attempts to create or write to an object.
`AuthenticationResult`	`discardObject(UserSession session, RTTPObject object)` This method will be called when a user's session is no longer subscribed to an object.
`void`	`globalPermissionUpdate(RTTPObject object, java.lang.String key, java.util.Map<java.lang.String,java.lang.String> fieldValues, PermissionUpdateType type)` Called on every update to a global permission object to allow the Authenticator to receive structured control messages.
`void`	`initialise(SessionManager sessionManager, DelayedResultReceiver delayedResultReceiver, ServerNode serverNode, java.lang.String loggerName)` Called on startup of the Liberator Auth Module.
`AuthenticationResult`	`mapObject(UserSession session, MapObject mapObject)` This method will be called every time a user tries to read an object (before checkRead).
`AuthenticationResult`	`newObject(RTTPObject object, RTTPObject parent)` This method is called when a new object is created in the Liberator.
`AuthenticationResult`	`releaseObject(RTTPObject object)` This method will be called when the Liberator deletes an object.
`AuthenticationResult`	`releaseUser(UserSession session)` This method will be called when the Liberator deletes the user session due to logout or timeout.
`AuthenticationResult`	`requestObject(UserSession session, RTTPObject object)` This method will be called when a user's session becomes subscribed to an object.
`void`	`shutdown()` Called when the Liberator is shutting down.
`int`	`stripAmount(java.lang.String subscription)` Helper method to extract the amount from a subscription symbol.
`java.lang.String`	`stripBranch(java.lang.String subscription)` Helper method to extract the branch from a subscription symbol.
`static java.lang.String`	`stripCurrencyPair(java.lang.String subscription)` Helper method to extract the currency pair from a subscription symbol.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - TieringAuthenticator
```
public TieringAuthenticator()
```
- Method Detail
  - stripCurrencyPair
```
public static java.lang.String stripCurrencyPair(java.lang.String subscription)
```
    Helper method to extract the currency pair from a subscription symbol.
    
    Parameters:
    
    subscription - An FX subscription
    
    Returns:
    
    The currency pair associated with the passed in symbol
  - stripBranch
```
public java.lang.String stripBranch(java.lang.String subscription)
```
    Helper method to extract the branch from a subscription symbol.
    
    Parameters:
    
    subscription - An FX subscription
    
    Returns:
    
    The currency pair associated with the passed in symbol
  - stripAmount
```
public int stripAmount(java.lang.String subscription)
```
    Helper method to extract the amount from a subscription symbol.
    
    Parameters:
    
    subscription - An FX subscription
    
    Returns:
    
    The currency pair associated with the passed in symbol
  - changeTiers
```
public void changeTiers()
```
    NOTE: This is a naive algorithm to change the tier values from one set to another, (and back again next time) In a production system this would be achieved by the receipt of permission objects sent from a DataSource. For the purposes of this example, this code should suffice to demonstrate that it is possible to dynamically change mappings at runtime. The cache will maintain tier information for branch and currency pair combination. The key for each tier is formed from the BRANCH|CURRENCY_PAIR The 'value' for each tier is an array of integers containing the maximum amount for each tier, in USD Example: For EURUSD and BRANCHA combination, following tiers could be available 0 - 1000 1 - 5000 2 - 10000
  - calculateMappedObject
```
public java.lang.String calculateMappedObject(java.lang.String subscription)
```
    Given an FX subscription, extract the branch and currency pair, and use them to convert the associated amount into a tier. For example, "EURUSD|CUSTA|BRANCHA|SP|1000|EUR" may map to "BRANCHA|EURUSD|Tier1"
    
    Parameters:
    
    subscription - An FX subscription
    
    Returns:
    
    A mapping for the passed in subscription, to reduce the number of unique objects in the system.
  - initialise
```
public void initialise(SessionManager sessionManager,
                       DelayedResultReceiver delayedResultReceiver,
                       ServerNode serverNode,
                       java.lang.String loggerName)
```
    Description copied from interface: Authenticator
    
    Called on startup of the Liberator Auth Module.
    
    Allows initialisation of required resources and connections. e.g. reading configuration files, connecting to a database or other external application, or constructing internal data structures.
    
    The logger name can be used for obtaining the native logger java.util.logging.Logger.getLogger(String). This logger will log messages to the Liberator's auth log file.
    
    Specified by:
    
    initialise in interface Authenticator
    
    Parameters:
    
    sessionManager - a SessionManager instance that can be used for invalidating and ejecting user sessions in the Liberator.
    
    delayedResultReceiver - a DelayedResultReceiver instance that can be used for sending delayed authentication results after an AuthenticationResult.DELAYED is used.
    
    serverNode - a ServerNode instance that provides access to information about the server and its session count.
    
    loggerName - the name of the logger that provides native logging output to the Liberator's auth log file (by default auth-rttpd.log).
  - checkUser
```
public AuthenticationResult checkUser(UserSession session)
```
    Description copied from interface: Authenticator
    
    The user login authorisation method which is called every time a user tries to login to the server.
    
    This method should be used to perform authorisation of the user's credentials.
    
    If the authentication requires the use of an external service (e.g. database) to verify the user credentials, the AuthenticationResult.DELAYED return code should be used, followed by a call to DelayedResultReceiver#delayedCheckUserResult when the result is available. This mechanism avoids the Liberator thread beeing blocked whilst waiting for the result, and the obvious associated performance impact.
    
    N.B. The delayed result functionality is only available for the checkUser and mapObject methods. To avoid unnecessary delays during methods such as checkRead, if the user's permission set is contained in a remote database or service, then it can be beneficial to cache this locally at logon time during this method execution.
    Subsequent permission checks such as checkRead can then access the locally cached permission set for optimal performance.
    If the cached permissions are then modified, then SessionManager#invalidateAllSessions or SessionManager#invalidateSessions methods can be used as necessary to force the Liberator to re-validate the user's permissions.
    
    Specified by:
    
    checkUser in interface Authenticator
    
    Parameters:
    
    session - the UserSession object containing information about the user and their login details.
    
    Returns:
    
    an AuthenticationResult instance - usually AuthenticationResult.OK , AuthenticationResult.DENY or one of the specific failure results such as AuthenticationResult.INVALID_USER.
    
    See Also:
    
    DelayedResultReceiver.delayedCheckUserResult(UserSession, AuthenticationResult), AuthenticationResult.DELAYED
  - releaseUser
```
public AuthenticationResult releaseUser(UserSession session)
```
    Description copied from interface: Authenticator
    
    This method will be called when the Liberator deletes the user session due to logout or timeout.
    
    Use this call to clean-up any resources that may have been allocated to a session.
    
    Specified by:
    
    releaseUser in interface Authenticator
    
    Parameters:
    
    session - the UserSession object for the released session.
    
    Returns:
    
    an AuthenticationResult instance - this is currently ignored, so use only AuthenticationResult.OK.
  - newObject
```
public AuthenticationResult newObject(RTTPObject object,
                                      RTTPObject parent)
```
    Description copied from interface: Authenticator
    
    This method is called when a new object is created in the Liberator.
    
    This is a notification method that can be used, for example, to pre-cache authentication information for the object. It will be called at the point of object creation in the Liberator, regardless of whether this object is created by a broadcast datasource, as the result of a user request or by an RTTP object creation by a user
    
    Specified by:
    
    newObject in interface Authenticator
    
    Parameters:
    
    object - the new RTTPObject that has been created.
    
    parent - the parent object of the newly created object, or null if the new object is at the root level in the Liberator.
    
    Returns:
    
    an AuthenticationResult instance - this is currently ignored, so use only AuthenticationResult.OK.
  - releaseObject
```
public AuthenticationResult releaseObject(RTTPObject object)
```
    Description copied from interface: Authenticator
    
    This method will be called when the Liberator deletes an object.
    
    Use this call to clean-up any resources that may have been allocated to the object.
    
    Specified by:
    
    releaseObject in interface Authenticator
    
    Parameters:
    
    object - the RTTPObject that has been deleted.
    
    Returns:
    
    an AuthenticationResult instance - this is currently ignored, so use only AuthenticationResult.OK.
  - checkRead
```
public AuthenticationResult checkRead(UserSession session,
                                      RTTPObject object,
                                      java.lang.String requestedName)
```
    Description copied from interface: Authenticator
    
    This method will be called to check authentication every time a user tries to read an object.
    
    Specified by:
    
    checkRead in interface Authenticator
    
    Parameters:
    
    session - the user's session. This will be the same session object that is passed on the Authenticator.checkUser(com.caplin.server.auth.UserSession) call when the user logs in.
    
    object - the RTTPObject the user is attempting to read.
    
    requestedName - The subject that was requested by the user before any mappings got applied
    
    Returns:
    
    either AuthenticationResult.OK, AuthenticationResult.DENY or AuthenticationResult.AGAIN
  - checkWrite
```
public AuthenticationResult checkWrite(UserSession session,
                                       RTTPObject object,
                                       java.lang.String requestedName,
                                       java.lang.String contributionId,
                                       java.util.Map<java.lang.String,java.lang.String> fields)
```
    Description copied from interface: Authenticator
    
    This method will be called to check authentication every time a user attempts to create or write to an object.
    
    Specified by:
    
    checkWrite in interface Authenticator
    
    Parameters:
    
    session - the user's session. This will be the same session object that is passed on the Authenticator.checkUser(com.caplin.server.auth.UserSession) call when the user logs in.
    
    object - the RTTPObject the user is attempting to read.
    
    requestedName - The subject that was contributed to by the user before any mappings got applied
    
    contributionId - the contribution Id that can be passed to the DelayedResultReceiver.delayedCheckWriteResult(com.caplin.server.auth.UserSession, com.caplin.server.auth.RTTPObject, java.lang.String, com.caplin.server.auth.AuthenticationResult) when a delayed result is required.
    
    fields - a map containing field name/value pairs, present in the update being authenticated
    
    Returns:
    
    either AuthenticationResult.OK or AuthenticationResult.DENY or AuthenticationResult.DELAYED
    You can only return {AuthenticationResult.DELAYED when the contributionId is non-null.
  - mapObject
```
public AuthenticationResult mapObject(UserSession session,
                                      MapObject mapObject)
```
    Description copied from interface: Authenticator
    
    This method will be called every time a user tries to read an object (before checkRead).
    
    Provides a mechanism for mapping an object name on a per-user basis.
    
    An Authenticator has the ability to map a user-requested object name to a different name in the server (and therefore at upstream DataSource(s) too). This can be useful for providing different data under the same symbol name to different users or groups of users, for example in order to provide preferential currency spreads to certain customers, or customised data for particular logins.
    
    e.g. The user "U1" requests object "/OBJ1" and this is mapped here to "/OBJ1-U1". The user still sees the object as "/OBJ1", but the Liberator will request "/OBJ-U1" from the DataSource(s)
    
    To use this functionality, the MapObject that is passed into this method should have it's mapped name set using the MapObject#setMappedName method. In addition, if mapping has occured, the return value should be AuthenticationResult.OK. The user-requested object name is available from the MapObject#getOriginalName method.
    
    Alternatively, if the result may take some time to be established, the {AuthenticationResult.DELAYED return value may be used. This allows for Liberator processing to continue whilst the mapped name is retrieved, perhaps from an external service or database. After the mapping is decided, the DelayedResultReceiver#delayedMapObjectResult method should be called, passing the UserSession, MapObject and AuthenticationResult as parameters. N.B. It is valid, even after delaying the result, to return AuthenticationResult.FALSE if no mapping is to be performed
    If the Authenticator is not providing mapping functionality then simply leave the MapObject unchanged and return the AuthenticationResult.FALSE result.
    
    Specified by:
    
    mapObject in interface Authenticator
    
    Parameters:
    
    session - the user's session. This will be the same session object that is passed on the Authenticator.checkUser(com.caplin.server.auth.UserSession) call when the user logs in.
    
    mapObject - the object to be optionally mapped.
    
    Returns:
    
    either AuthenticationResult.FALSE if the object name has not been mapped, AuthenticationResult.OK if it has been mapped, or AuthenticationResult.DELAYED if the mapping is delayed.
    
    See Also:
    
    DelayedResultReceiver.delayedMapObjectResult(UserSession, MapObject, AuthenticationResult), AuthenticationResult.DELAYED
  - requestObject
```
public AuthenticationResult requestObject(UserSession session,
                                          RTTPObject object)
```
    Description copied from interface: Authenticator
    
    This method will be called when a user's session becomes subscribed to an object.
    
    A user session may become subscribed to the same object multiple times. In this case there will be multiple calls to this method and corresponding calls to discardObject for each discard the session performs
    
    N.B. This method will be called after a successful checkRead call has completed
    
    Specified by:
    
    requestObject in interface Authenticator
    
    Parameters:
    
    session - the user's session. This will be the same session object that is passed on the Authenticator.checkUser(com.caplin.server.auth.UserSession) call when the user logs in.
    
    object - the RTTPObject to which the user is now subscribed.
    
    Returns:
    
    an AuthenticationResult instance - this is currently ignored, so use only AuthenticationResult.OK.
  - discardObject
```
public AuthenticationResult discardObject(UserSession session,
                                          RTTPObject object)
```
    Description copied from interface: Authenticator
    
    This method will be called when a user's session is no longer subscribed to an object.
    
    Specified by:
    
    discardObject in interface Authenticator
    
    Parameters:
    
    session - the user's session. This will be the same session object that is passed on the Authenticator.checkUser(com.caplin.server.auth.UserSession) call when the user logs in.
    
    object - the RTTPObject to which the user is no longer subscribed.
    
    Returns:
    
    an AuthenticationResult instance - this is currently ignored, so use only AuthenticationResult.OK.
  - authoriseHTTP
```
public AuthenticationResult authoriseHTTP(AuthenticationUser user)
```
    Description copied from interface: Authenticator
    
    This method will be called when an HTTP directory access authorisation is required.
    
    Suitable HTTP directories must be configured in the Liberator before this method will be called.
    
    As HTTP authorisation is a one-off event, no UserSession object is created, and an AuthenticationUser is passed directly.
    
    Specified by:
    
    authoriseHTTP in interface Authenticator
    
    Parameters:
    
    user - an AuthenticationUser containing the user name and password provided for HTTP directory access.
    
    Returns:
    
    either AuthenticationResult.OK or AuthenticationResult.DENY.
  - checkUpdate
```
public AuthenticationResult checkUpdate(UserSession session,
                                        RTTPObject object,
                                        java.lang.String data)
```
    Description copied from interface: Authenticator
    
    Called on every update to an object (currently only news headline objects) to allow the Authenticator to authenticate each update based on content.
    
    Allows an Authenticator to perform permissioning on news headlines / alerts. Can be useful where only certain content is to be sent to particular users or groups of users.
    
    Specified by:
    
    checkUpdate in interface Authenticator
    
    Parameters:
    
    session - the user's session. This will be the same session object that is passed on the Authenticator.checkUser(com.caplin.server.auth.UserSession) call when the user logs in.
    
    object - the RTTPObject that has been updated (currently only news headline objects).
    
    data - the content of the update to the object.
    
    Returns:
    
    either AuthenticationResult.OK or AuthenticationResult.DENY.
  - checkPermissionUpdate
```
public AuthenticationResult checkPermissionUpdate(UserSession session,
                                                  RTTPObject object,
                                                  java.lang.String key,
                                                  java.util.Map<java.lang.String,java.lang.String> fieldValues)
```
    Description copied from interface: Authenticator
    
    Called on every update to a permission object to allow the Authenticator to authenticate each update based on content.
    
    Specified by:
    
    checkPermissionUpdate in interface Authenticator
    
    Parameters:
    
    session - the user's session. This will be the same session object that is passed on the Authenticator.checkUser(com.caplin.server.auth.UserSession) call when the user logs in.
    
    object - the RTTPObject that has been updated (currently only news headline objects).
    
    key - The permission key that has been updated
    
    fieldValues - The field/value pairs for this permission
    
    Returns:
    
    either AuthenticationResult.OK or AuthenticationResult.DENY.
  - globalPermissionUpdate
```
public void globalPermissionUpdate(RTTPObject object,
                                   java.lang.String key,
                                   java.util.Map<java.lang.String,java.lang.String> fieldValues,
                                   PermissionUpdateType type)
```
    Description copied from interface: Authenticator
    
    Called on every update to a global permission object to allow the Authenticator to receive structured control messages.
    
    Specified by:
    
    globalPermissionUpdate in interface Authenticator
    
    Parameters:
    
    object - the RTTPObject that has been updated.
    
    key - The permission key that has been updated
    
    fieldValues - The field/value pairs for this permission
    
    type - an enum value specifying the type of update.
  - shutdown
```
public void shutdown()
```
    Description copied from interface: Authenticator
    
    Called when the Liberator is shutting down.
    
    Allows clean shutdown of connections, files and resources by the Authenticator.
    
    Specified by:
    
    shutdown in interface Authenticator

Class TieringAuthenticator

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TieringAuthenticator

Method Detail

stripCurrencyPair

stripBranch

stripAmount

changeTiers

calculateMappedObject

initialise

checkUser

releaseUser

newObject

releaseObject

checkRead

checkWrite

mapObject

requestObject

discardObject

authoriseHTTP

checkUpdate

checkPermissionUpdate

globalPermissionUpdate

shutdown