A partner company have set up an STS which is connected to their identity system. The issued SAML token contain claims in the attribute statement which do have a different encoding for the same meaning. Applications should not directly depend on the claims because they will be different for each partner. Therefore, the application trusts a so called Relying Party STS whereas the partner uses their Identity Provider STS. If identities of the partners are provisioned into your identiy system you're fine with the current IdentityMapper interface but this means claims must be provisioned too. This might work for different identity system within the same company but doesn't scale with partners. In this case, the RP STS transforms the claims of the IP STS to claims which are understood by the application.
If claims information are correlated to a security token like a SAML token it's encoded within an Attribute Statement. If it is a SecureConversation token, it's not part of the token itself but locally cached. The claims might be encoded within a custom token also.
The token can be part of the WS-Security header (issue request) or within the ValidateTarget (validate request).
The TokenValidator must validate the token and return the realm which is the source realm.
The claims of the source realm must be provided by the token validator or retrieved from the cache.
The target realm is provided as part of the RealmParser implementation.
The claims transformation interface looks like something:
List<Claim> mapClaims (String sourceRealm, List<Claim> sourceClaims, String targetRealm)