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

  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 Details

  - ### FormattableObject

    protected FormattableObject()
    Default constructor.

- ## Method Details

  - ### 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()`