Interface SubjectMapper

  • All Known Subinterfaces:
    SwitchableSubjectMapper
    All Known Implementing Classes:
    RegexSuffixSubjectMapper, SwitchByKeySubjectPatternMapper

    public interface SubjectMapper

    The SubjectMapper interface must be implemented by any custom SubjectMapper class that you write.

    Subject mapping allows the subject of an RTTP message to be modified by Liberator. Subject mapping is transparent to the user and could be used, for example, to provide preferential data to selected users (see Permissiong 6.0: Permissioning Overview And Concepts for further details).

    Subjects are modified for a User in the Permissioning Auth Module from mappings that you set on the User in the PermissioningDataSource. For example the subject "FX/USDGBR" could be changed to "FX/USDGBR-tier2", so that the end user is shown tier 2 prices when they request the "FX/USDGBR" instrument.

    If a SubjectMapper modifies the subject of an RTTP message, the user must have permission for the modified subject and not the original subject.

    A default SubjectMapper is provided with the Permissioning software that allows one subject mapping to be added for each User, and a RegexSuffixSubjectMapper is provided that allows multiple subject mappings to be added for each User. To set the RegexSuffixSubjectMapper class as the SubjectMapper for a User, call User.setSubjectMapper(), passing in the fully qualified class name com.caplin.permissionnig.RegexSuffixSubjectMapper.

    If you want to provide customized mapping logic, then you must create a custom SubjectMapper. To create a custom subject mapper you must:

    • Write a custom Java class that implements this SubjectMapper interface.
    • Compile and deploy the custom SubjectMapper Java class to the Permissioning Auth Module and configure Liberator to use the compiled code.
    • Call User.setSubjectMapper() so that subjects will be mapped by the custom SubjectMapper for this user.

    Because custom SubjectMapper classes are dynamically loaded and instantiated, all such classes must provide a public default (zero argument) constructor, or let the compiler create the default constructor.

    The document Permissioning 6.0: How To Create A Permissioning Adapter provides an example of a custom SubjectMapper class that implements the SubjectMapper interface, and describes how to deploy the class and configure Liberator.

    Thread Safety: The methods of a SubjectMapper will never be called concurrently with any other SubjectMapper method and no GlobalContext method will ever be called concurrently with a SubjectMapper method. Therefore there are no concurrency issues when implementing a custom SubjectMapper.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.lang.String mapSubject​(java.lang.String subject)
      This method is called by the Permissioning Auth Module when Liberator receives an RTTP message from the client application.
      void setGlobalContext​(GlobalContext globalContext)
      This method is called by the Permissioning Auth Module when the GlobalContext is updated at the PermissioningDataSource as part of a transaction.
      void updateMappings​(java.lang.String key, java.util.Map<java.lang.String,​java.lang.String> updateMap)
      This method is called by the Permissioning Auth Module when subject mappings are received from the PermissioningDataSource.
    • Method Detail

      • updateMappings

        void updateMappings​(java.lang.String key,
                            java.util.Map<java.lang.String,​java.lang.String> updateMap)

        This method is called by the Permissioning Auth Module when subject mappings are received from the PermissioningDataSource. The method is passed a key and the subject mappings for that key.

        Subject mappings are set in the PermissioningDataSource using the User.addSubjectMappings() method and sent to the Permissioning Auth Module as part of a transaction.

        The updateMappings method of this interface has no return value but allows you to store the received keys and subject mappings, and to make them available to mapSubject(). Each subject mapping is a name-value pair that typically consists of a subject pattern and subject suffix.

        Keys can be used by mapSubject() to limit the scope of a subject mapping. For example if a key is set to "FX", then mapSubject() could limit the scope of the associated subject mappings to FX instruments.

        Parameters:
        key - the key associated with the subject mappings at the Permissioning DataSource.
        updateMap - the subject mappings received from the Permissioning DataSource.
      • setGlobalContext

        void setGlobalContext​(GlobalContext globalContext)

        This method is called by the Permissioning Auth Module when the GlobalContext is updated at the PermissioningDataSource as part of a transaction. The method is passed the current GlobalContext and includes the latest update.

        If the SubjectMapper needs to access GlobalContext data to map a subject, this method must store a reference to the current GlobalContext and make it available to mapsubject() . If the SubjectMapper does not need to access GlobalContext data, this method can simply return.

        The setGlobalContext() method can be called at any time in the lifecycle of the SubjectMapper, and could be called several times.

        Parameters:
        globalContext - the current GlobalContext object.
      • mapSubject

        java.lang.String mapSubject​(java.lang.String subject)

        This method is called by the Permissioning Auth Module when Liberator receives an RTTP message from the client application. The subject passed to this method is the subject of the RTTP message received by Liberator, and the method must determine whether or not the subject is to be mapped.

        If the subject is to be mapped, return the modified subject to Liberator as a string. Liberator will use the modified subject to request data from the DataSource and to check user permissions.

        If the subject is not to be mapped, return null. In this case Liberator will use the original subject of the RTTP message to request data from the DataSource and to check user permissions.

        To map a subject, this method must be able to access the subject mappings and GlobalContext that the Permissioning Auth Module passed to updateMappings() and setGlobalContext().

        Parameters:
        subject - the subject of the original RTTP message that was received by Liberator.
        Returns:
        the modified subject if a mapping was found, or null if a mapping was not found.