Package com.caplin.server.auth

Interface Authenticator

  • All Known Implementing Classes:
    AuthenticatorAdaptor, DelayedLoginAuthenticator, KeyMasterAuthenticator, OpenAuthenticator, PermissionAuthenticator, TieringAuthenticator
    public interface Authenticator

    Defines the interface to be implemented by a Liberator Auth Module.

    This is the main interface that the developer of a Liberator Auth Module for the Liberator needs to be aware of. It provides a set of method signatures that are called by the Liberator to perform user and object authentication.

    Any class that implements this interface must define a default constructor. This will be constructed automatically by the Liberator at startup. The constructor should not perform any initialisation or startup, instead, this should be performed when the initialise method is called. Before this time, assume it is unsafe to perform any operations.

    When creating a simple Authenticator implementation that only needs to provide limited custom functionality it may be easier to subclass the AuthenticatorAdaptor as it provides default implementations of this interface.

    See Also:
    AuthenticatorAdaptor, OpenAuthenticator

    • Method Detail

      • initialise

        void initialise​(SessionManager sessionManager,
                DelayedResultReceiver delayedReceiver,
                ServerNode serverNode,
                java.lang.String loggerName)

        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.

        Parameters:
        sessionManager - a SessionManager instance that can be used for invalidating and ejecting user sessions in the Liberator.
        delayedReceiver - 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).

      • releaseUser

        AuthenticationResult releaseUser​(UserSession session)

        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.

        Parameters:
        session - the UserSession object for the released session.
        Returns:
        an AuthenticationResult instance - this is currently ignored, so use only AuthenticationResult.OK.

      • newObject

        AuthenticationResult newObject​(RTTPObject object,
                               RTTPObject parent)

        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

        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

        AuthenticationResult releaseObject​(RTTPObject object)

        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.

        Parameters:
        object - the RTTPObject that has been deleted.
        Returns:
        an AuthenticationResult instance - this is currently ignored, so use only AuthenticationResult.OK.

      • mapObject

        AuthenticationResult mapObject​(UserSession session,
                               MapObject mapObject)

        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.

        Parameters:
        session - the user's session. This will be the same session object that is passed on the 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

        AuthenticationResult requestObject​(UserSession session,
                                   RTTPObject object)

        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

        Parameters:
        session - the user's session. This will be the same session object that is passed on the 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.

      • checkUpdate

        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.

        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.

        Parameters:
        session - the user's session. This will be the same session object that is passed on the 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

        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.

        Parameters:
        session - the user's session. This will be the same session object that is passed on the 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

        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.

        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

        void shutdown()

        Called when the Liberator is shutting down.

        Allows clean shutdown of connections, files and resources by the Authenticator.