Package org.incenp.obofoundry.sssom.transform

Class SSSOMTransformReader<T>

  • Type Parameters:
    T - The type of object that should be produced by the processing rules for each mapping.
    public class SSSOMTransformReader<T>
extends Object
    A parser to read mapping processing rules in the SSSOM Transform language.

    This parser knows nothing of the functions that are allowed to be used in SSSOM/T rules and what they are supposed to do. Client code must initialise the parser with a ISSSOMTransformApplication implementation that will provide the required application-specific knowledge.

    See Also:
    The SSSOM/Transform language

    • Constructor Detail

      • SSSOMTransformReader

        public SSSOMTransformReader​(ISSSOMTransformApplication<T> application)
        Creates a new instance without an input source. Use this constructor to parse SSSOM Transform from something else than a file or file-like source, coupled with the read(String) method.
        Parameters:
        application - The SSSOM/T specialised application.

      • SSSOMTransformReader

        public SSSOMTransformReader​(ISSSOMTransformApplication<T> application,
                            Reader input)
                     throws IOException
        Creates a new instance to read from a reader object.
        Parameters:
        application - The SSSOM/T specialised application.
        input - The reader to parse the SSSOM/T ruleset from.
        Throws:
        IOException - If any non-SSSOM/T I/O error occurs when reading from the reader object.

      • SSSOMTransformReader

        public SSSOMTransformReader​(ISSSOMTransformApplication<T> application,
                            InputStream input)
                     throws IOException
        Creates a new instance to read from a stream.
        Parameters:
        application - The SSSOM/T specialised application.
        input - The stream to parse the SSSOM/T ruleset from.
        Throws:
        IOException - If any non-SSSOM/T I/O error occurs when reading from the stream.

      • SSSOMTransformReader

        public SSSOMTransformReader​(ISSSOMTransformApplication<T> application,
                            File input)
                     throws IOException
        Creates a new instance to read from a file.
        Parameters:
        application - The SSSOM/T specialised application.
        input - The file to parse the SSSOM/T ruleset from.
        Throws:
        IOException - If any non-SSSOM/T I/O error occurs when reading from the file.

      • SSSOMTransformReader

        public SSSOMTransformReader​(ISSSOMTransformApplication<T> application,
                            String filename)
                     throws IOException
        Creates a new instance to read from a file.
        Parameters:
        application - The SSSOM/T specialised application.
        filename - The name of the file to read from.
        Throws:
        IOException - If any non-SSSOM/T I/O error occurs when reading from the file.

    • Method Detail

      • setPrefixManager

        public void setPrefixManager​(PrefixManager prefixManager)
        Sets the prefix manager to use. Calling this method voids all prefixes previously declared with addPrefix(String, String) or addPrefixMap(Map).

        This method is intended to be used in situations where the calling code may need more than just the prefix map itself -- for example, if it needs to know whether the manager has encountered any prefix that it could not expand or any IRI that it could not shorten.

        Parameters:
        prefixManager - The prefix manager used by this reader.

      • addPrefix

        public void addPrefix​(String prefixName,
                      String prefix)
        Adds a prefix to the reader's prefix map. The prefix map is used to expand short identifiers ("CURIEs") that may be found in the SSSOM/T ruleset.
        Parameters:
        prefixName - The prefix name to add.
        prefix - The corresponding URL prefix.

      • addPrefixMap

        public void addPrefixMap​(Map<String,​String> map)
        Adds prefixes to the reader's prefix map.
        Parameters:
        map - A map between prefix names and their corresponding URL prefixes.

      • getPrefixMap

        public Map<String,​String> getPrefixMap()
        Gets the effective prefix map used by this reader. It contains all prefixes known to the reader, whether they were read from a SSSOM/T file or explicitly added by addPrefix(String, String).
        Returns:
        The prefix map as used by the reader.

      • read

        public boolean read()
        Parses the SSSOM/T ruleset from the underlying source. After this methods returns true, call the getRules() method to get the result.

        This method may only be used if an input source has been specified to the constructor.

        Returns:
        true if the ruleset was successfully parsed, or false if SSSOM/T syntax errors were found.
        Throws:
        IllegalArgumentException - If the method is called while no input source has been set.

      • read

        public boolean read​(String text)
        Parses the SSSOM/T ruleset from the specified string. After this method returns true, call the getRules() method to get the result.

        This method does not require that an input has been set and may be called repeatedly on different inputs in the lifetime of the SSSOMTransformReader object.

        For convenience, this method does not require a single-action rule to be terminated by a semi-colon. That is, an input of 

         "subject==UBERON:* -> stop()"
        will be accepted as equivalent to 
         "subject==UBERON:* -> stop();"
        even though the former is, strictly speaking, incorrect as per the SSSOM/T syntax. This is only true if the input has no trailing whitespace, though.
        Parameters:
        text - The SSSOM/T ruleset to parse.
        Returns:
        true if the ruleset was successfully parsed, or false of SSSOM/T syntax errors were found.

      • getRules

        public List<MappingProcessingRule<T>> getRules()
        Gets the SSSOM/T rules that have been parsed from the underlying source. This method sould be called after calling read() and checking that it returned true, indicating that parsing was successful.

        As a convenience, this method will call read() automatically if needed, if an input has been set. The caller should then use hasErrors() to check whether syntax errors were found.

        When read(String) is called repeatedly on different inputs, this method always returns all the rules that have been parsed since this object was created, not only the rules resulting from the last read(String) call.

        Returns:
        The SSSOM/T processing rules. May be an empty list if nothing has been parsed or if syntax errors were found.

      • hasErrors

        public boolean hasErrors()
        Indicates whether parsing errors occurred. Calling this method after read() is another way of checking whether syntax errors were found when parsing.
        Returns:
        true if at least one parsing error occured, otherwise false.

      • getErrors

        public List<SSSOMTransformError> getErrors()
        Gets all syntax errors that were found when parsing, if any.

        The parser does not throw any exception upon encountering a SSSOM/T syntax error (it only throws IOException upon I/O errors unrelated to SSSOM/T. Instead, all syntax errors are collected in the form of SSSOMTransformError objects, which may be retrieved with this method.

        Returns:
        A list of objects representing the syntax errors (empty if no errors occured).