Package org.apache.sis.io

Class TableAppender

java.lang.Object
org.apache.sis.io.Appender
org.apache.sis.io.TableAppender
All Implemented Interfaces:
Flushable, Appendable
public class TableAppender extends Appender implements Flushable
An Appendable which formats the text as a table suitable for displaying in devices using a monospaced font. Columns are separated by tabulations ('\t') and rows are separated by line or paragraph separators. The content of every table cells are stored in memory until the flush() method is invoked. When invoked, flush() copies the cell contents to the underlying stream or buffer while replacing tabulations by some amount of spaces and drawing borders. The exact number of spaces is computed from the cell widths.

For example, the following code:

produces the following output:
Since:
0.3
Version:
1.0
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
    TableAppender.Cell
    A class wrapping a cell content and its text alignment.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final byte
    ALIGN_CENTER
    A possible value for cell alignment.
    static final byte
    ALIGN_LEFT
    A possible value for cell alignment.
    static final byte
    ALIGN_RIGHT
    A possible value for cell alignment.
    private byte
    alignment
    Alignment for current and next cells.
    private static final char[][]
    BOX
    Drawing-box characters.
    private final StringBuilder
    buffer
    Temporary string buffer.
    private final List<TableAppender.Cell>
    cells
    List of TableAppender.Cell objects, from left to right and top to bottom.
    private final String
    columnSeparator
    The column separator, or an empty string if none.
    private int
    currentColumn
    Column position of the cell currently being written.
    private int
    currentRow
    Line position of the cell currently being written.
    private final String
    leftBorder
    The left table border, or an empty string if none.
    private String
    lineSeparator
    The line separator.
    private int[]
    maximalColumnWidths
    Maximum width for each columns.
    private boolean
    multiLinesCells
    Tells if cells can span more than one line.
    private boolean
    ownOut
    Sets to true at construction time if Appender.out has been created by the constructor rather than supplied by the user.
    private final String
    rightBorder
    The right table border, or an empty string if none.
    private boolean
    skipLF
    true if the next character needs to be skipped if equals to '\n'.
    private static final char
    SPACE
    The character for empty spaces to insert between columns.

    Fields inherited from class org.apache.sis.io.Appender

    out

  • Constructor Summary

    Constructors
    Constructor
    Description
    TableAppender()
    Creates a new table formatter writing in an internal buffer with a default column separator.
    TableAppender(Appendable out)
    Creates a new table formatter writing in the given output with a default column separator.
    TableAppender(Appendable out, String separator)
    Creates a new table formatter writing in the given output with the specified column separator.
    TableAppender(Appendable out, String leftBorder, String separator, String rightBorder)
    Creates a new table formatter writing in the given output with the specified column separator and border.
    TableAppender(String separator)
    Creates a new table formatter writing in an internal buffer with the specified column separator.

  • Method Summary

    Modifier and Type
    Method
    Description
    TableAppender
    append(char c)
    Writes a single character.
    TableAppender
    append(CharSequence sequence)
    Appends the specified character sequence.
    TableAppender
    append(CharSequence sequence, int start, int end)
    Writes a portion of a character sequence.
    void
    appendHorizontalSeparator()
    Writes an horizontal separator using the '─' character.
    void
    flush()
    Flushes the table content to the underlying stream or buffer.
    byte
    getCellAlignment()
    Returns the alignment of the text inside the current cell.
    int
    getColumnCount()
    Returns the number of columns in this table.
    String
    getLineSeparator()
    Returns the line separator between table rows.
    int
    getRowCount()
    Returns the number of rows in this table.
    private static boolean
    isEmpty(Object[] array)
    Checks if array contains only null elements.
    boolean
    isMultiLinesCells()
    Returns true if EOL characters are used for line feeds inside current cells.
    void
    nextColumn()
    Moves one column to the right.
    void
    nextColumn(char fill)
    Moves one column to the right, filling remaining space with the given character.
    void
    nextLine()
    Moves to the first column on the next row.
    void
    nextLine(char fill)
    Moves to the first column on the next row, filling every remaining cell in the current row with the specified character.
    private static void
    repeat(Appendable out, char car, int count)
    Repeats a character.
    void
    setCellAlignment(byte alignment)
    Sets the alignment of the text inside the current cell.
    void
    setMultiLinesCells(boolean multiLines)
    Sets the desired behavior for EOL and tabulations characters.
    String
    toString()
    Returns the content of this TableAppender as a string if possible.
    private void
    writeBorder(int horizontalBorder, int verticalBorder, char horizontalChar)
    Writes a border or a corner to the underlying stream or buffer.
    private void
    writeTable()
    Writes the table without clearing the TableAppender content.

    Methods inherited from class org.apache.sis.io.Appender

    appendCodePoint, appendSurrogate, isHighSurrogate, lineSeparator, toCodePoint

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • ALIGN_LEFT

      public static final byte ALIGN_LEFT
      A possible value for cell alignment. This specifies that the text is aligned to the left indent and extra whitespace should be placed on the right.
      See Also:

    • ALIGN_CENTER

      public static final byte ALIGN_CENTER
      A possible value for cell alignment. This specifies that the text is aligned to the center and extra whitespace should be placed equally on the left and right.
      See Also:

    • ALIGN_RIGHT

      public static final byte ALIGN_RIGHT
      A possible value for cell alignment. This specifies that the text is aligned to the right indent and extra whitespace should be placed on the left.
      See Also:

    • BOX

      private static final char[][] BOX
      Drawing-box characters. The last two characters are horizontal and vertical line respectively.

    • SPACE

      private static final char SPACE
      The character for empty spaces to insert between columns.
      See Also:

    • buffer

      private final StringBuilder buffer
      Temporary string buffer. This buffer contains only one cell content.

    • cells

      private final List<TableAppender.Cell> cells
      List of TableAppender.Cell objects, from left to right and top to bottom. By convention, a null value or a TableAppender.Cell object with TableAppender.Cell.text == null means that we need to move to the next line.

    • alignment

      private byte alignment
      Alignment for current and next cells.
      See Also:

    • currentColumn

      private int currentColumn
      Column position of the cell currently being written. The field is incremented every time nextColumn() is invoked.

    • currentRow

      private int currentRow
      Line position of the cell currently being written. The field is incremented every time nextLine() is invoked.

    • maximalColumnWidths

      private int[] maximalColumnWidths
      Maximum width for each columns. This array length must be equal to the number of columns in this table.

    • lineSeparator

      private String lineSeparator
      The line separator. We will use the first line separator found in the text to provided by the user, or the system default if none.

    • columnSeparator

      private final String columnSeparator
      The column separator, or an empty string if none.

    • leftBorder

      private final String leftBorder
      The left table border, or an empty string if none.

    • rightBorder

      private final String rightBorder
      The right table border, or an empty string if none.

    • multiLinesCells

      private boolean multiLinesCells
      Tells if cells can span more than one line. If true, then EOL characters likes '\n' move to the next line inside the current cell. If false, then EOL characters move to the next table row. Default value is false.

    • skipLF

      private boolean skipLF
      true if the next character needs to be skipped if equals to '\n'.

    • ownOut

      private boolean ownOut
      Sets to true at construction time if Appender.out has been created by the constructor rather than supplied by the user.

  • Constructor Details

    • TableAppender

      public TableAppender()
      Creates a new table formatter writing in an internal buffer with a default column separator. The default is a vertical double line for the left and right table borders, and a single line between the columns.

    • TableAppender

      public TableAppender(String separator)
      Creates a new table formatter writing in an internal buffer with the specified column separator.
      Parameters:
      separator - string to write between columns.

    • TableAppender

      public TableAppender(Appendable out)
      Creates a new table formatter writing in the given output with a default column separator. The default is a vertical double line for the left and right table borders, and a single line between the columns.
      Parameters:
      out - the underlying stream or buffer to write to.

    • TableAppender

      public TableAppender(Appendable out, String separator)
      Creates a new table formatter writing in the given output with the specified column separator.
      Parameters:
      out - the underlying stream or buffer to write to.
      separator - string to write between columns.

    • TableAppender

      public TableAppender(Appendable out, String leftBorder, String separator, String rightBorder)
      Creates a new table formatter writing in the given output with the specified column separator and border.
      Parameters:
      out - the underlying stream or buffer to write to.
      leftBorder - string to write on the left side of the table.
      separator - string to write between columns.
      rightBorder - string to write on the right side of the table.
      Since:
      0.8

  • Method Details

    • writeBorder

      private void writeBorder(int horizontalBorder, int verticalBorder, char horizontalChar) throws IOException
      Writes a border or a corner to the underlying stream or buffer.
      Parameters:
      horizontalBorder - -1 for left border, +1 for right border, 0 for center.
      verticalBorder - -1 for top border, +1 for bottom border, 0 for center.
      horizontalChar - character to use for horizontal line.
      Throws:
      IOException - if the writing operation failed.

    • isMultiLinesCells

      public boolean isMultiLinesCells()
      Returns true if EOL characters are used for line feeds inside current cells.
      Returns:
      true if EOL characters are to be write inside the cell.

    • setMultiLinesCells

      public void setMultiLinesCells(boolean multiLines)
      Sets the desired behavior for EOL and tabulations characters.
      • If true, then tabulations, line and paragraph separator characters are copied into the current cell. Subsequent writing operations will continue inside the same cell.
      • If false, then tabulations move to next column and EOL move to the first cell of next row (i.e. tabulation and EOL are equivalent to nextColumn() and nextLine() calls respectively).
      The default value is false.
      Parameters:
      multiLines - true true if EOL are used for line feeds inside current cells, or false if EOL move to the next row.

    • getCellAlignment

      public byte getCellAlignment()
      Returns the alignment of the text inside the current cell. The default value is ALIGN_LEFT.
      Returns:
      current cell alignment as one of the ALIGN_LEFT, ALIGN_RIGHT or ALIGN_CENTER constants.

    • setCellAlignment

      public void setCellAlignment(byte alignment)
      Sets the alignment of the text inside the current cell. The alignments of any cell written prior this method call are left unchanged. The new alignment will apply to the next cells too until this setCellAlignment(…) method is invoked again with a different value.

      If this method is never invoked, then the default alignment is ALIGN_LEFT.

      Parameters:
      alignment - the new cell alignment as one of the ALIGN_LEFT, ALIGN_RIGHT or ALIGN_CENTER constants.

    • getLineSeparator

      public String getLineSeparator()
      Returns the line separator between table rows. This is the first line separator found in the text formatted as a table, or the system default if no line separator was found in the text to format.
      Returns:
      the line separator between table rows.
      Since:
      1.0

    • getRowCount

      public int getRowCount()
      Returns the number of rows in this table. This count is reset to 0 by flush().
      Returns:
      the number of rows in this table.

    • getColumnCount

      public int getColumnCount()
      Returns the number of columns in this table.
      Returns:
      the number of columns in this table.

    • append

      public TableAppender append(char c)
      Writes a single character. If isMultiLinesCells() is false (which is the default), then:
      Specified by:
      append in interface Appendable
      Parameters:
      c - character to write.
      Returns:
      this.

    • append

      public TableAppender append(CharSequence sequence)
      Appends the specified character sequence.
      Specified by:
      append in interface Appendable
      Overrides:
      append in class Appender
      Parameters:
      sequence - the character sequence to append, or null.
      Returns:
      a reference to this Appendable.

    • append

      public TableAppender append(CharSequence sequence, int start, int end)
      Writes a portion of a character sequence. Tabulations and line separators are interpreted as by append(char).
      Specified by:
      append in interface Appendable
      Parameters:
      sequence - the character sequence to be written.
      start - index from which to start reading characters.
      end - index of the character following the last character to read.
      Returns:
      this.

    • appendHorizontalSeparator

      public void appendHorizontalSeparator()
      Writes an horizontal separator using the '─' character.
      See Also:

    • nextColumn

      public void nextColumn()
      Moves one column to the right. The subsequent writing operations will occur in a new cell on the same row.

    • nextColumn

      public void nextColumn(char fill)
      Moves one column to the right, filling remaining space with the given character. The subsequent writing operations will occur in a new cell on the same row.

      Calling nextColumn('*') from the first character in a cell is a convenient way to put a pad value in this cell.

      Parameters:
      fill - character filling the cell (default to whitespace).

    • nextLine

      public void nextLine()
      Moves to the first column on the next row. The subsequent writing operations will occur on a new row.

    • nextLine

      public void nextLine(char fill)
      Moves to the first column on the next row, filling every remaining cell in the current row with the specified character. The subsequent writing operations will occur on a new row.

      Calling nextLine('-') or nextLine('═') from the first column of a row is a convenient way to fill this row with a line separator.

      Parameters:
      fill - character filling the rest of the line (default to whitespace). This character may be use as a row separator.
      See Also:

    • flush

      public void flush() throws IOException
      Flushes the table content to the underlying stream or buffer. This method should not be called before the table is completed (otherwise, columns may have the wrong width).
      Specified by:
      flush in interface Flushable
      Throws:
      IOException - if an output operation failed.

    • toString

      public String toString()
      Returns the content of this TableAppender as a string if possible.
      • If this TableAppender has been created without explicit Appendable, then this method always returns the current table content formatted as a string.
      • Otherwise, if Appender.out implements CharSequence or is directly or indirectly a wrapper around a CharSequence, returns its toString() representation. The string will contain this table content only if flush() has been invoked prior this toString() method.
      • Otherwise returns the localized "Unavailable content" string.
      Overrides:
      toString in class Appender
      Returns:
      the content of this Appendable, or a localized message for unavailable content.
      See Also:

    • writeTable

      private void writeTable() throws IOException
      Writes the table without clearing the TableAppender content. Invoking this method many time would result in the same table being repeated.
      Throws:
      IOException

    • isEmpty

      private static boolean isEmpty(Object[] array)
      Checks if array contains only null elements.

    • repeat

      private static void repeat(Appendable out, char car, int count) throws IOException
      Repeats a character. The count value may be negative, which is handled as if it was zero.
      Parameters:
      out - the stream or buffer where to repeat the character.
      car - character to write (usually ' ').
      count - number of repetition, negative means 0.
      Throws:
      IOException