Interface MappingLoader

All Known Implementing Classes:
ConceptMapJsonLoader, ConceptMapLoader, ConceptMapXmlLoader, GroovyMappingLoader, XmlMappingLoader, YamlMappingLoader
public interface MappingLoader
Turns a mapping source document into Mappings: a SimpleMapping for every table the source declares, and, where the format spreads one translation over several tables, a CompositeMapping over them, listed after its parts.

Implementations are discovered with ServiceLoader, so a single Mappings instance can hold mappings written in different formats. The format is a decision per mapping file, and it is reached in either of two ways:

  • by file extension, through supports(URI). This is the default and needs no configuration - a *.mapping.xml file finds its loader on its own.
  • by format id, when the caller names one. Extensions cannot always decide: a mapping fetched from https://tx.example.org/ConceptMap/gender has no extension at all, a file may be called gender.xml for reasons outside IPF's control, and two loaders may be able to read one and the same extension. Naming the format bypasses supports(URI) entirely.
Register an implementation by listing it in META-INF/services/org.openehealth.ipf.commons.map.MappingLoader.
Since:
6.0

  • Method Details

    • format

      String format()
      Short, stable identifier of the format this loader reads, e.g. xml, yaml or conceptmap-r4-json. It is what a caller names to select this loader regardless of the source's file extension, and it is compared case-insensitively.

      Two loaders on one classpath must not share a format id, since the id is what picks one of them; qualify it the way conceptmap-r4-json does when a format has versions or encodings that a second loader might read.

      Returns:
      the format id, never null or blank

    • supports

      boolean supports(URI source)
      Whether this loader claims a source that nobody named a format for. Implementations decide by file extension: a source it cannot recognize from its name alone is not its own, even if it could read the content, because that is what keeps dispatch predictable.
      Parameters:
      source - location of the mapping source, used for its file extension
      Returns:
      whether this loader can read the given source

    • load

      List<Mapping> load(InputStream in, URI source, MappingFunctionRegistry functions) throws IOException
      Reads all mappings contained in one source document.
      Parameters:
      in - the source content; the caller closes the stream
      source - location of the source, for diagnostics
      functions - registry a loader may add functions to, and against which it should validate any Unmatched.Computed reference it produces
      Returns:
      the mappings read, in declaration order
      Throws:
      IOException - if the source cannot be read
      MappingException - if the source is not valid for this format

    • load

      default List<Mapping> load(InputStream in, URI source, MappingFunctionRegistry functions, Consumer<String> warnings) throws IOException
      Reads all mappings contained in one source document, reporting what the model cannot hold.

      A format that can state more than the model - the legacy Groovy DSL binds arbitrary objects where the model holds strings - reports each such loss to warnings, one message per mapping, starting with the mapping's name. MappingConverter collects them. The default implementation has nothing to report.

      Parameters:
      in - the source content; the caller closes the stream
      source - location of the source, for diagnostics
      functions - registry a loader may add functions to
      warnings - receives a human-readable message for every loss the loader has to make
      Returns:
      the mappings read, in declaration order
      Throws:
      IOException - if the source cannot be read
      MappingException - if the source is not valid for this format

    • path

      static String path(URI source)
      Parameters:
      source - a source location
      Returns:
      the path portion of the location, also for opaque URIs such as jar: URLs

    • hasExtension

      static boolean hasExtension(URI source, String extension)
      Parameters:
      source - a source location
      extension - file extension including the leading dot, compared case-insensitively
      Returns:
      whether the source location ends with the given extension