Interface Mappings

All Known Implementing Classes:
DefaultMappings, SpringMappings
public interface Mappings
Typed front door to a set of Mappings, whatever format they were loaded from.

Compared to the older MappingService this interface is String-typed and returns Optional rather than null, so call sites no longer cast. An unknown mapping name is a programming error and raises IllegalArgumentException; an unknown key within a known mapping yields an empty Optional. Mappings instances can be built programmatically like this: 

var mappings = Mappings.builder()
    .function("oidUri", s -> !s.isEmpty() && Character.isDigit(s.charAt(0)) ? "urn:oid:" + s : s)
    .load("classpath:/META-INF/map/atna2fhir.mapping.xml")
    .build();

String uri = mappings.map("atnaCodingSystem", "DCM").orElseThrow();
Since:
6.0

  • Method Details

    • mapping

      Optional<Mapping> mapping(String mapping)
      Parameters:
      mapping - mapping name
      Returns:
      the mapping itself, or empty if no mapping of that name is registered

    • mappingNames

      Set<String> mappingNames()
      Returns:
      the names of all registered mappings, in registration order

    • mappingsFor

      List<Mapping> mappingsFor(String keySystem, String valueSystem)
      Finds mappings by the code systems they translate between, rather than by name.

      A caller holding a code to translate knows which code system it is in and which one it wants, not what the mapping happens to be called - which is the shape of FHIR's ConceptMap/$translate, and the only way to reach a mapping read from a source that names itself, such as a ConceptMap resource. Either argument may be null for "any", so passing only a key system finds every mapping that translates out of it.

      This is a scan over the registered mappings, not an index: resolve the mapping once and keep it, rather than calling this per message.

      Parameters:
      keySystem - identifier of the key code system, or null for any
      valueSystem - identifier of the value code system, or null for any
      Returns:
      the matching mappings, in registration order

    • mappingFor

      default Optional<Mapping> mappingFor(String keySystem, String valueSystem)
      Where a CompositeMapping matches together with some of its parts, the composite stands for them: it answers for all of them, so asking the whole of a ConceptMap by its source system finds the ConceptMap rather than failing on its groups.
      Parameters:
      keySystem - identifier of the key code system, or null for any
      valueSystem - identifier of the value code system, or null for any
      Returns:
      the single mapping translating between the two systems, empty if there is none
      Throws:
      IllegalArgumentException - if several mappings translate between them, since picking one of them would be arbitrary - use mappingsFor(String, String) to see them all
      See Also:

    • lookup

      Optional<String> lookup(String mapping, String key)
      Looks up a key without applying the mapping's unmatched behavior.
      Parameters:
      mapping - mapping name
      key - left side of the mapping
      Returns:
      the value declared for that key, empty if the mapping declares no entry for it
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • lookupReverse

      Optional<String> lookupReverse(String mapping, String value)
      Looks up a value without applying the mapping's reverse unmatched behavior.
      Parameters:
      mapping - mapping name
      value - right side of the mapping
      Returns:
      the key declared for that value, empty if the mapping declares no invertible entry for it
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • unmatched

      Optional<String> unmatched(String mapping, String key)
      Applies a mapping's unmatched behavior to a key, without looking the key up first.
      Parameters:
      mapping - mapping name
      key - left side of the mapping
      Returns:
      the fallback value, empty if the mapping declares no fallback
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • reverseUnmatched

      Optional<String> reverseUnmatched(String mapping, String value)
      Applies a mapping's reverse unmatched behavior to a value, without looking it up first.
      Parameters:
      mapping - mapping name
      value - right side of the mapping
      Returns:
      the fallback key, empty if the mapping declares no reverse fallback
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • map

      default Optional<String> map(String mapping, String key)
      Parameters:
      mapping - mapping name
      key - left side of the mapping
      Returns:
      the mapped value, falling back to the mapping's unmatched behavior
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • map

      default String map(String mapping, String key, String defaultValue)
      Parameters:
      mapping - mapping name
      key - left side of the mapping
      defaultValue - value to return if neither an entry nor a fallback yields one
      Returns:
      the mapped value or defaultValue
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • mapReverse

      default Optional<String> mapReverse(String mapping, String value)
      Parameters:
      mapping - mapping name
      value - right side of the mapping
      Returns:
      the key mapping to that value, falling back to the mapping's reverse unmatched behavior
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • mapReverse

      default String mapReverse(String mapping, String value, String defaultKey)
      Parameters:
      mapping - mapping name
      value - right side of the mapping
      defaultKey - key to return if neither an entry nor a fallback yields one
      Returns:
      the reverse-mapped key or defaultKey
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • translate

      default Optional<Translation> translate(String mapping, String key)
      Maps a key like map(String, String), and says which code system the answer belongs to and how it is displayed - what a caller needs to build a coded value from it.

      The system is that of the mapping which actually answered: a composite answers with the system of the part that had the answer, a delegating fallback with that of the mapping delegated to. An identity fallback answers with the key itself, and so with the key system.

      The default implementation knows none of that and answers with the mapping's value system and no display; DefaultMappings overrides it.

      Parameters:
      mapping - mapping name
      key - left side of the mapping
      Returns:
      the mapped value with its system and display, falling back to the mapping's unmatched behavior
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • translateReverse

      default Optional<Translation> translateReverse(String mapping, String value)
      Maps a value back like mapReverse(String, String), and says which code system the answer belongs to and how it is displayed.
      Parameters:
      mapping - mapping name
      value - right side of the mapping
      Returns:
      the key mapping to that value with its system and display, falling back to the mapping's reverse unmatched behavior
      Throws:
      IllegalArgumentException - if the mapping name is not registered
      See Also:

    • keySystem

      Optional<String> keySystem(String mapping)
      Parameters:
      mapping - mapping name
      Returns:
      formal identifier of the key code system, empty if the mapping declares none
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • valueSystem

      Optional<String> valueSystem(String mapping)
      Parameters:
      mapping - mapping name
      Returns:
      formal identifier of the value code system, empty if the mapping declares none
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • keys

      Set<String> keys(String mapping)
      Parameters:
      mapping - mapping name
      Returns:
      the keys this mapping translates, in declaration order. A key declared only by a Equivalence.DISJOINT entry is not among them, because it does not translate. The keys of a mapping this one delegates to follow its own, since a lookup asks that mapping for every key this one does not declare; keys that only a fallback such as identity answers are not listed. For a composite they are the keys of all its parts. Changes to the set do not change the mapping
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • values

      Collection<String> values(String mapping)
      Parameters:
      mapping - mapping name
      Returns:
      the values this mapping translates to, in declaration order. Changes to the collection do not change the mapping
      Throws:
      IllegalArgumentException - if the mapping name is not registered
      See Also:

    • entries

      default List<Entry> entries(String mapping)
      The entries a mapping declares, whatever its kind: those of a SimpleMapping, and for a CompositeMapping those of its parts, in part order. Unlike keys(String), this is the declaration - disjoint entries included, and a key declared by several parts listed once per part.
      Parameters:
      mapping - mapping name
      Returns:
      the declared entries, in declaration order
      Throws:
      IllegalArgumentException - if the mapping name is not registered

    • functions

      MappingFunctions functions()
      Returns:
      read access to the functions available to Unmatched.Computed fallbacks. Functions are registered while building, with Mappings.Builder.function(String, Function); a built instance cannot be changed through what this returns

    • builder

      static Mappings.Builder builder()