Package org.apache.sis.io.wkt

## Class FormattableObject

- Object
- - FormattableObject

- Direct Known Subclasses:
    `AbstractDirectPosition`, `AbstractEnvelope`, `AbstractIdentifiedObject`, `AbstractMathTransform`, `BursaWolfParameters`, `DefaultFormula`, `DefaultParameterValue`, `ImmutableIdentifier`

      public abstract class FormattableObject
      extends Object

  Base class for objects that can be formatted as Well Known Text (WKT). `WKTFormat` checks for this class at formatting time for each element to format. When a `FormattableObject` element is found, its `formatTo(Formatter)` method is invoked for allowing the element to control its formatting.

  This class provides two methods for getting a default Well Known Text representation of this object:

  - `toWKT()` tries to return a strictly compliant WKT or throws `UnformattableObjectException` if this object contains elements not defined by the ISO 19162 standard.
  - `toString()` returns a WKT with some redundant information omitted and some constraints relaxed. This method never throw `UnformattableObjectException`; it will rather use non-standard representation if necessary.
  Syntax coloring
  A convenience `print()` method is provided, which is roughly equivalent to `System​.out​.println(this)` except that syntax coloring is automatically applied if the terminal seems to support the ANSI escape codes.
  Non-standard WKT
  If this object can not be formatted without violating some WKT constraints, then the behavior depends on the method invoked:
  - `toWKT()` will throw a `UnformattableObjectException`.
  - `toString()` will ignore the problem and uses non-standard elements if needed.
  - `print()` will show the non-standard elements in red if syntax coloring is enabled.
  Since:
    0.4
  See Also:
    WKT 2 specification, Legacy WKT 1

  Defined in the `sis-referencing` module

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `FormattableObject()` | Default constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected abstract String` | `formatTo​(Formatter formatter)` | Formats the inner part of this Well Known Text (WKT) element into the given formatter.
    `void` | `print()` | Prints a string representation of this object to the standard output stream.
    `String` | `toString()` | Returns a Well Known Text (WKT) or an alternative text representation for this object.
    `String` | `toString​(Convention convention)` | Returns a Well Known Text (WKT) for this object using the specified convention.
    `String` | `toWKT()` | Returns a strictly compliant Well Known Text (WKT) using the default convention, symbols and indentation.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### FormattableObject

          protected FormattableObject()

      Default constructor.

  - ### Method Detail

    - #### toWKT

          public String toWKT()
                       throws UnformattableObjectException

      Returns a strictly compliant Well Known Text (WKT) using the default convention, symbols and indentation. If this object can not be represented in a standard way, then this method throws an `UnformattableObjectException`.

      By default this method formats this object according the `Convention​.WKT2` rules.

      Returns:
        the default Well Know Text representation of this object.
      Throws:
        `UnformattableObjectException` - if this object can not be formatted as a standard WKT.
      See Also:
        `IdentifiedObject​.toWKT()`

    - #### toString

          public String toString()

      Returns a Well Known Text (WKT) or an alternative text representation for this object. If this object can not be represented in a standard way, then this method may fallback on non-standard representation, or leave unformattable elements empty and append warnings after the WKT.

      By default this method formats this object according the `Convention​.WKT2_SIMPLIFIED` rules, except that Unicode characters are kept as-is (they are not converted to ASCII). Consequently the WKT is not guaranteed to be ISO 19162 compliant. For stricter conformance, use `toWKT()` instead.

      Overrides:
        `toString` in class `Object`
      Returns:
        the Well Known Text (WKT) or an alternative representation of this object.

    - #### toString

          public String toString​(Convention convention)

      Returns a Well Known Text (WKT) for this object using the specified convention. Unicode characters are kept as-is (they are not converted to ASCII). The returned string may contain non-standard elements or warnings if this object can not be formatted according the given convention.

      For stricter conformance to ISO 19162 standard, use `toWKT()` or `WKTFormat` instead.

      Parameters:
        `convention` - the WKT convention to use.
      Returns:
        the Well Known Text (WKT) or a pseudo-WKT representation of this object.

    - #### print

          @Debug
          public void print()

      Prints a string representation of this object to the standard output stream. If a console is attached to the running JVM (i.e. if the application is run from the command-line and the output is not redirected to a file) and if Apache SIS thinks that the console supports the ANSI escape codes (a.k.a. X3.64), then a syntax coloring will be applied.

      This is a convenience method for debugging purpose and for console applications.

    - #### formatTo

          protected abstract String formatTo​(Formatter formatter)

      Formats the inner part of this Well Known Text (WKT) element into the given formatter. This method is automatically invoked by `WKTFormat` when a formattable element is found.

      Keywords, opening and closing brackets shall not be formatted here. For example if this formattable element is for a `GeodeticCRS[…]` element, then this method shall write the content starting at the insertion point shown below:

      >     GeodeticCRS[ ]
      >                 ↑
      >         (insertion point)

      Formatting non-standard WKT
      If the implementation can not represent this object without violating some WKT constraints, it can uses its own (non-standard) keywords but shall declare that it did so by invoking one of the `Formatter​.setInvalidWKT(…)` methods.

      Alternatively, the implementation may also have no WKT keyword for this object. This happen frequently when an abstract class defines a base implementation, while the keyword needs to be defined by the concrete subclasses. In such case, the method in the abstract class shall return `null`.

      Parameters:
        `formatter` - the formatter where to format the inner content of this WKT element.
      Returns:
        the CamelCase keyword for the WKT element, or `null` if unknown.
      See Also:
        `toWKT()`, `toString()`