Module org.apache.sis.util
Package org.apache.sis.io

# Class IO

Object
Static
IO

public final class IO extends Static
Utilities methods working on `Appendable` objects.

Since:
  0.3

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Writer`
  `asWriter(Appendable out)`
  Returns a view of the given `Appendable` as a `Writer`.
  `static void`
  `close(Appendable out)`
  If the given `out` argument implements `Closeable`, or is a chain of wrappers defined in this package around a closeable object, invokes the `close()` method on that object.
  `static CharSequence`
  `content(Appendable out)`
  If the given `out` argument implements `CharSequence`, or is a chain of wrappers defined in this package around a `CharSequence`, returns that character sequence.
  `static void`
  `flush(Appendable out)`
  If the given `out` argument implements `Flushable`, or is a chain of wrappers defined in this package around a flushable object, invokes the `flush()` method on that object.

  ### Methods inherited from class Object

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

- ## Method Details

  - ### flush

    public static void flush(Appendable out) throws IOException
    If the given `out` argument implements `Flushable`, or is a chain of wrappers defined in this package around a flushable object, invokes the `flush()` method on that object. Otherwise do nothing.

    Chains of wrappers are followed until a `Flushable` instance is found, if any. The search stops at the first occurrence found.

    Parameters:
      `out` - the output stream, writer or buffer to flush, or `null`.
    Throws:
      `IOException` - if an error occurred while flushing the given stream.

  - ### close

    public static void close(Appendable out) throws IOException
    If the given `out` argument implements `Closeable`, or is a chain of wrappers defined in this package around a closeable object, invokes the `close()` method on that object. Otherwise do nothing.

    Chains of wrappers are followed until a `Closeable` instance is found, if any. The first `Flushable` instance found before the `Closeable` one, if any, is flushed. The search stops at the first `Closeable` occurrence found.

    Parameters:
      `out` - the output stream, writer or buffer to close, or `null`.
    Throws:
      `IOException` - if an error occurred while closing the given stream.

  - ### content

    public static CharSequence content(Appendable out)
    If the given `out` argument implements `CharSequence`, or is a chain of wrappers defined in this package around a `CharSequence`, returns that character sequence. Otherwise returns `null`.

    Special cases:

    - If an `Appendable` is a `StringWriter` instance, then its underlying buffer is returned.
    - If an `Appendable` is a `CharArrayWriter` instance, then its content is returned as a string.

    This method is useful for getting the result of an `Appendable` which wrote, directly or indirectly, into a `StringBuilder` or similar kind of character buffer. Note that this method returns the underlying buffer if possible; callers should not change `CharSequence` content, unless the `Appendable` is not used anymore after this method call.

    It may be necessary to invoke `flush(Appendable)` before this method in order to get proper content. In particular, this is necessary if the chain of `Appendable`s contains `TableAppender` or `LineAppender` instances.

    Parameters:
      `out` - the output stream, writer or buffer from which to get the content, or `null`.
    Returns:
      the content of the given stream of buffer, or `null` if unavailable.
    See Also:
      - `flush(Appendable)`

  - ### asWriter

    public static Writer asWriter(Appendable out)
    Returns a view of the given `Appendable` as a `Writer`. If the given argument is already a `Writer` instance, then it is returned unchanged. Otherwise if the argument is non-null, then it is wrapped in an adapter. Any write operations performed on the returned writer will be forwarded to the given `Appendable`.
    Parameters:
      `out` - the output stream, writer or buffer to view as a `Writer`, or `null`.
    Returns:
      a view of this `Appendable` as a writer, or `null` if the given argument was null.