Package org.incenp.obofoundry.sssom.transform

Class MappingFormatter

java.lang.Object
org.incenp.obofoundry.sssom.transform.MappingFormatter
public class MappingFormatter extends Object
Helper class to format mappings into strings.

This class is intended to facilitate the creation of strings that may contain values derived from mappings, using ”format specifiers” of the form %{placeholder} (or %placeholder, but generally the “bracketed” form should be preferred).

For example, this initialises a formatter that can substitute %{predicate} and %{justification} in a string by the predicate identifier and the justification of a mapping, respectively: 

 MappingFormatter formatter = new MappingFormatter();
 formatter.setSubstitution("predicate", (mapping) -> mapping.getPredicateId());
 formatter.setSubstitution("justification", (mapping) -$gt; mapping.getMappingJustification());

That formatter may then be used as follows: 

 String text = formatter.format("The mapping predicate is '%{predicate}', the justification is '%{justification'}",
         mapping);

which will return (for example), "The predicate is 'http://www.w3.org/2004/02/skos/core#exactMatch', the justification is 'https://w3id.org/semapv/vocab/ManualMappingCuration'".

Another way of using the formatter is to obtain a IMappingTransformer object that can then be used to directly transform a mapping into a formatted string. The following would return the same value as the previous example: 

 IMappingTransformer<String> transformer = formatter
         .getTransformer("The mapping predicate is '%{predicate}', the justification is '%{justification}'");
 String text = transformer.transform(mapping);

  • Constructor Details

    • MappingFormatter

      public MappingFormatter()

  • Method Details

    • setPrefixManager

      public void setPrefixManager(PrefixManager prefixManager)
      Sets the prefix manager to use when attempting to resolve a placeholder name into the name of an extension slot.
      Parameters:
      prefixManager - The prefix manager.

    • setSubstitution

      public void setSubstitution(String placeholder, IMappingTransformer<Object> transformer)
      Defines a placeholder text to be substituted by a value derived from a mapping.

      The placeholder will be recognised within a format string if it is found:

      • within curly backets preceded by a single '%' character, as in %{placeholder}, or
      • simply preceded by a single '%' character, as in %placeholder.

      The placeholder cannot contain a '{' or a '|' character.

      Note that in addition, an un-bracketed placeholder can only be recognised if it starts with a letter, and contains only letters and underscores. So while it is possible to define a placeholder named, for example, my-placeholder, such a placeholder can only be used with the bracketed form (%{my-placeholder}); %my-placeholder would be interpreted as the placeholder my (if such a placeholder exists) followed by the plain string -placeholder.

      Parameters:
      placeholder - The placeholder value that should be substituted by a mapping-derived value.
      transformer - The transformer to produce the value that should replace the placeholder.
      Throws:
      IllegalArgumentException - If the placeholder contains illegal characters.

    • setStandardSubstitutions

      public void setStandardSubstitutions()
      Defines “standard” substitutions using the name of mapping fields as defined in the SSSOM specification. That is, this defines, for example, %{subject_id} as a placeholder for the mapping’s subject ID, and so on for all the standard fields.

    • setModifier

      public void setModifier(IFormatModifierFunction modifier)
      Registers a modifier function that can be used to alter the value of a substitution.

      In a format string, a modifier function can called within the brackets after the name of the placeholder, separated from it by a '|' character, as in %{placeholder|modifier(arg1, arg2)}.

      The modifier function will receive as its first argument the mapping-derived substitution value for the placeholder (optionally modified by other modifiers). Remaining arguments are those explicitly passed to the function, if any (arg1 and arg2 in the example above). The function must return the value that should effectively be inserted into the formatted string.

      If the function does not need any additional argument beyond the mandatory substitution value, the parentheses may be omitted, as in %{placeholder|modifier}.

      Modifier functions can only be used with the bracketed syntax.

      Parameters:
      modifier - The modifier function to register.

    • format

      public String format(String format, Mapping mapping)
      Formats a string with values derived from a mapping. This method finds and replaces all the placeholders defined by previous calls to setSubstitution(String, IMappingTransformer).
      Parameters:
      format - The format string containing placeholders to substitute by mapping-derived values.
      mapping - The mapping to format the text with.
      Returns:
      A new string containing the substituted values (or the original string if no substitution took place).
      Throws:
      IllegalArgumentException - If the format string contains invalid format specifiers.

    • getTransformer

      public IMappingTransformer<String> getTransformer(String format)
      Gets a mapping transformer that can directly create a formatted string from a mapping by application of all the substitutions defined in this object.
      Parameters:
      format - The format string containing placeholders to substitute by mapping-derived values.
      Returns:
      A mapping transformer that can transform a mapping into a formatted string.
      Throws:
      IllegalArgumentException - If the format string contains invalid format specifiers.

    • getTransformer

      public IMappingTransformer<String> getTransformer(String format, IFormatModifierFunction defaultModifier, List<String> modifierArguments)
      Gets a mapping transformer that can directly create a formatted string from a mapping by application of all the substitutions defined in this object.
      Parameters:
      format - The format string containing placeholders to substitute by mapping-derived values.
      defaultModifier - A default modifier function to apply to all simple (un-bracketed) placeholders. May be null.
      modifierArguments - Arguments to the default modifier function, if any. May be null.
      Returns:
      A mapping transformer that can transform a mapping into a formatted string.
      Throws:
      IllegalArgumentException - If the format string contains invalid format specifiers.