Class MetadataWriter

  • All Implemented Interfaces:
    Closeable, Flushable, Appendable, AutoCloseable

    public class MetadataWriter
    extends PrintWriter
    Writer implementation for writing BFS metadata files. The start of file marker (BFSformat) is written immediately at object construction. Use the bfsPrintSection(String, boolean, boolean) to start a new section, and bfsPrintValue(String, String...) to print a section entry. It is not recommended that any of the superclass methods (eg. PrintWriter methods} are used directly as it can create an invalid BFS metadata file.

    This class can be subclassed to get specific functionality in specific use cases.

    Version:
    2.15
    Author:
    Nicklas
    Last modified
    $Date: 2019-05-21 13:37:09 +0200 (tis, 21 maj 2019) $
    • Field Detail

      • filename

        private String filename
      • subtype

        private String subtype
      • usedSections

        private Set<String> usedSections
      • currentSection

        private String currentSection
      • uniqueKeys

        private boolean uniqueKeys
      • lineCount

        private int lineCount
      • sectionCount

        private int sectionCount
      • valueCount

        private int valueCount
    • Constructor Detail

      • MetadataWriter

        public MetadataWriter​(Writer out)
        Create a new BFS metadata writer.
        Parameters:
        out - The parent writer which this writer will print to
    • Method Detail

      • create

        public static MetadataWriter create​(OutputStream out,
                                            String filename)
        Utility method for creating a metadata writer when you have an output stream.
        Parameters:
        out - The output stream the metadata writer should print to
        filename - Optional, the name of the file the output stream is printing to
      • create

        public static MetadataWriter create​(File file)
        Utility method for creating a metadata writer to a file in the BASE file system. The character set and MIME type on the file are automatically updated.
        Parameters:
        file - The file in the BASE file system
      • create

        public static MetadataWriter create​(File file)
                                     throws IOException
        Utility method for creating a metadata writer to a file in the native file system. If the file doesn't exists, it is created.
        Parameters:
        file - The file in the native file system
        Throws:
        IOException
      • getFilename

        public String getFilename()
        Get the file name that this writer is printing to.
        Returns:
        The file name or null if not known
      • setFilename

        public void setFilename​(String filename)
        Set the file name that this writer is printing to.
      • getSubtype

        public String getSubtype()
        Get the BFS subtype.
        Returns:
        The unencoded subtype, or null if no subtype was specified when the object was created
      • setSubtype

        public void setSubtype​(String subtype)
        Set the BFS subtype for this writer. This method must be called before any printing method is called.
        Parameters:
        subtype - The subtype
        Throws:
        IllegalStateException - If data has already been written
      • getCurrentSection

        public String getCurrentSection()
        Get the name of the current section.
        Returns:
        The unencoded name of the section, or null if no section has been started yet
      • getUniqueKeys

        public boolean getUniqueKeys()
        Checks if the current section requires entry names to be unique or not.
      • isUsedKey

        public boolean isUsedKey​(String key)
        Checks if the current section already has an entry for the given key or not.
        Parameters:
        key - The key to check
        Returns:
        TRUE if the current section already has an entry for this key, FALSE otherwise
      • encodeValue

        public String encodeValue​(String value)
        Encode a value for use in a BFS file. There is usually no need to call this method, since values are automatically encoded.
        Parameters:
        value - The value to encode, may be null
        Returns:
        The encoded value
      • getLineCount

        public int getLineCount()
        Get the number of lines that has been written to this file so far, including all comment lines, empty lines, sections headers, etc.
      • getSectionCount

        public int getSectionCount()
        Get the number of sections that has been written to this file so far.
      • getValueCount

        public int getValueCount()
        Get the number of values that has been written to the current section so far.
      • bfsPrintEmptyLine

        public void bfsPrintEmptyLine​(int num)
        Print one or more empty lines to the metadata file.
        Parameters:
        num - The number of empty lines to print. If 0 or negative nothing is written
      • bfsPrintComment

        public void bfsPrintComment​(String comment)
        Prints one or more comment lines to the metadata file. A null comment is ignored. If the comment contains line-breaks and/or carriage returns, it will be split and written to multiple lines.
        Parameters:
        comment - The comment string
      • bfsPrintSection

        public void bfsPrintSection​(String name,
                                    boolean unique,
                                    boolean uniqueKeys)
        Start a new section.
        Parameters:
        name - The name of the section, null is not allowed
        unique - TRUE if this section must be unique within the metadata file
        uniqueKeys - TRUE if all keys in this section must be unique
        Throws:
        NullPointerException - If the section name is null
        IllegalArgumentException - If the name is not unique and the writer requires unique sections
      • bfsPrintValue

        public void bfsPrintValue​(String key,
                                  String... values)
        Prints a section entry. A section must have been started with bfsPrintSection(String, boolean, boolean) before this method is invoked.
        Parameters:
        key - The entry key; null is not allowed and it may not start with '[' or '#'
        values - An array of string values, each value will be encoded independently and separated with a tab
        Throws:
        NullPointerException - If the key is null
        IllegalArgumentException - If the key starts with '[' or '#', or if the key is not unique within a section that requires unique keys
        IllegalStateException - If no section has been started
      • bfsPrintValue

        public <T> void bfsPrintValue​(String key,
                                      T... values)
        Prints a section entry. A section must have been started with bfsPrintSection(String, boolean, boolean) before this method is invoked.
        Parameters:
        key - The entry key; null is not allowed and it may not start with '[' or '#'
        values - An array of objects, each value will be be converted to a string by calling the toString() method
        Throws:
        NullPointerException - If the key is null
        IllegalArgumentException - If the key starts with '[' or '#', or if the key is not unique within a section that requires unique keys
        IllegalStateException - If no section has been started
      • bfsPrintValue

        public <T> void bfsPrintValue​(String key,
                                      Formatter<T> formatter,
                                      T... values)
        Prints a section entry. A section must have been started with bfsPrintSection(String, boolean, boolean) before this method is invoked.
        Parameters:
        key - The entry key; null is not allowed and it may not start with '[' or '#'
        formatter - A formatter that should be used to convert the values to strings, or null to simply use the toString() method
        values - An array of objects, each value will be encoded independently and separated with a tab
        Throws:
        NullPointerException - If the key is null
        IllegalArgumentException - If the key starts with '[' or '#', or if the key is not unique within a section that requires unique keys
        IllegalStateException - If no section has been started
      • internalPrintBofMarker

        protected void internalPrintBofMarker()
        Prints the beginning-of-file marker. Eg. BFSformat<tab>subtype
      • internalPrintComment

        protected void internalPrintComment​(String comment)
        Print a single-line comment. This method should not be called with comment string that is null or contain line-breaks. Updates the line counter.
      • internalPrintSection

        protected void internalPrintSection​(String encodedName)
        Prints a section header assuming that the name has already been encoded. Updates line and section counters and resets the value counter.
      • internalPrintValue

        protected void internalPrintValue​(String encodedKey,
                                          String encodedValue)
        Prints a section entry assuming that the key and value has already been encoded. Updates the line and value counters.