Package org.incenp.obofoundry.sssom

Class TSVReader

java.lang.Object
org.incenp.obofoundry.sssom.SSSOMReader
org.incenp.obofoundry.sssom.TSVReader
public class TSVReader extends SSSOMReader
A parser to read a SSSOM mapping set from the TSV serialisation format. It can read both files that have an embedded metadata block or files with external metadata. Use one of the two-arguments constructors to explicitly specify the name of the external metadata file.

That parser can also be indirectly used to parse a JSON file: if it detects that the first byte of the file is a { character, it will assume the file is a JSON file (no valid SSSOM/TSV file can start with a {) and will automatically invoke a JSONReader.

Usage: 

 try {
     TSVReader reader = new TSVReader("my-mappings.sssom.tsv");
     MappingSet mappingSet = reader.read();
 } catch ( IOException ioe ) {
     // Generic, non-SSSOM-related I/O error (e.g. file not found)
 } catch ( SSSOMFormatException sfe ) {
     // Invalid SSSOM data
 }

  • Constructor Details

    • TSVReader

      public TSVReader(File tsvFile, File metaFile) throws FileNotFoundException
      Creates a new instance that will read data from the specified files.
      Parameters:
      tsvFile - The main TSV file. May be null if one only wants to read a metadata file (in which case the second argument cannot also be null).
      metaFile - The accompanying metadata file. If null, the parser will attempt to automatically locate the metadata from the main file.
      Throws:
      FileNotFoundException - If any of the files cannot be found.

    • TSVReader

      public TSVReader(File file) throws FileNotFoundException
      Creates a new instance that will read data from a single file. That file should either contain an embedded metadata block, or a file containing the metadata should exist alongside it.
      Parameters:
      file - The single file to read.
      Throws:
      FileNotFoundException - If the file cannot be found.

    • TSVReader

      public TSVReader(InputStream tsvStream, InputStream metaStream)
      Creates a new instance that will read data from the specified streams. Note that when reading from a stream, the metadata either needs to be embedded with the TSV stream or an explicit metadata stream must be specified; the reader cannot automatically locate an external metadata file.
      Parameters:
      tsvStream - The main stream, containing the TSV data. May be null if one only wants to read a metadata stream (in which case the second argument cannot also be null).
      metaStream - The accompanying metadata stream. If null, the metadata must be embedded in the TSV stream.

    • TSVReader

      public TSVReader(InputStream stream)
      Creates a new instance that will read data from a single stream. That file must contain an embedded metadata block.
      Parameters:
      stream - The single stream to read from.

    • TSVReader

      public TSVReader(Reader tsvReader, Reader metaReader)
      Creates a new instance that will read data from the specified reader. Note that when reading from a reader object, the metadata either needs to be embedded with the TSV or an explicit reader for the metadata must be specified; the reader cannot automatically locate an external metadata file.
      Parameters:
      tsvReader - The main reader, containing the TSV data. May be null if one only wants to read the metadata (in which case the second argument cannot also be null).
      metaReader - The accompagnying metadata reader. If null, the metadata must be embedded with the TSV section.

    • TSVReader

      public TSVReader(Reader tsvReader, Reader metaReader, String filename)
      Creates a new instance that will read data from the specified reader.

      This constructor behaves similarly to TSVReader(Reader, Reader), but allows providing the filename of the TSV file in the third argument, which will be used to try locating the external metadata file if (1) the TSV file does not contain an embedded metadata block and (2) the metaReader argument is null.

      Parameters:
      tsvReader - The main reader, containing the TSV data. May be null if one only wants to read the metadata (in which case the second argument cannot also be null.
      metaReader - The accompanying metadata reader. If null, the metadata must either be embedded with the TSV section or be in a file in the same directory and with the same basename than the name provided in the third argument.
      filename - The name of the file containing the TSV section; that name is not used to actually read the TSV section, but to try locating the external metadata file if needed (if the TSV file contains no embedded metadata and the second argument is null).

    • TSVReader

      public TSVReader(Reader tsvReader)
      Creates a new instance that will read data from the specified reader.

      The metadata must be embedded with the TSV section; the reader cannot automatically locate an external metadata file. To read from a Reader object while still being able to automatically locate and use an external metadata file, use TSVReader(Reader, Reader, String) with the second argument set to null and the third argument set to the filename of the TSV section.

      Parameters:
      tsvReader - The single reader to read from.

    • TSVReader

      public TSVReader(String tsvFile, String metaFile) throws FileNotFoundException
      Creates a new instance that will read data from the specified files.
      Parameters:
      tsvFile - The name of the main TSV file. May be null if one only wants to read a metadata file (in which case the second argument cannot also be null).
      metaFile - The name of the accompanying metadata file. If null, the parser will attempt to automatically locate the metadata from the main file.
      Throws:
      FileNotFoundException - If any of the files cannot be found.

    • TSVReader

      public TSVReader(String file) throws FileNotFoundException
      Creates a new instance that will read data from a single file. That file should either contain an embedded metadata block, or a file containing the metadata should exist alongside it.
      Parameters:
      file - The name of the single file to read.
      Throws:
      FileNotFoundException - If the file cannot be found.

  • Method Details

    • fillPrefixMap

      public void fillPrefixMap(Map<String,String> map)
      Description copied from class: SSSOMReader
      Declares all prefix names in the specified map. Prefix names declared here complement the declarations from the file’s own prefix map, allowing the reader to parse a file with an incomplete prefix map.

      It is up to concrete implementations to actually do something with that map. Some of them may ignore it.

      Overrides:
      fillPrefixMap in class SSSOMReader
      Parameters:
      map - The prefix map to use.

    • setSeparatorMode

      public void setSeparatorMode(TSVReader.SeparatorMode mode)
      Sets the behaviour of the reader regarding the column separator character.

      By default, the reader tries to guess whether columns in the TSV section are separated by tabs or by commas (defaulting to tabs if it cannot positively determine the separator). Use this method to force the reader to expect a given separator.

      Parameters:
      mode - The separator mode to be used by this reader.

    • read

      public MappingSet read() throws SSSOMFormatException, IOException
      Reads a mapping set from the source file(s).
      Specified by:
      read in class SSSOMReader
      Returns:
      A complete SSSOM mapping set, unless no TSV file was provided to the constructor when this object was created, in which case the returned object will contain no mappings.
      Throws:
      SSSOMFormatException - If encountering invalid SSSOM data. This includes the case where the metadata cannot be found.
      IOException - If any kind of non-SSSOM-related I/O error occurs.

    • read

      public MappingSet read(boolean metadataOnly) throws SSSOMFormatException, IOException
      Reads a mapping set from the source file(s), with the option of reading the metadata only.
      Parameters:
      metadataOnly - If true, the mappings themselves will not be read, only the metadata. The returned MappingSet object will contain no mappings. If no TSV file was provided to the constructor when this object was created, then no mappings will be read regardless of the value of this parameter.
      Returns:
      A SSSOM mapping set, with or without any mappings depending on the parameter.
      Throws:
      SSSOMFormatException - If encountering invalid SSSOM data.
      IOException - If any kind of non-SSSOM-related I/O error occurs.