Class FormattableObject

java.lang.Object
org.apache.sis.io.wkt.FormattableObject
Direct Known Subclasses:
AbstractDirectPosition, AbstractEnvelope, AbstractIdentifiedObject, AbstractMathTransform, BursaWolfParameters, ContextualParameters.WKT, DefaultCoordinateSystemAxis.Order, DefaultFormula, DefaultParameterValue, DefaultTemporalDatum.Origin, DirectionAlongMeridian, ExplicitParameters, Geographic3Dto2D.WKT, ImmutableIdentifier, ImmutableIdentifier.Cite, ReferencingByIdentifiers.SubElement, ResidualGrid.Data

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 cannot be formatted without violating some WKT constraints, then the behavior depends on the method invoked:
Since:
0.4
Version:
0.6
See Also:
  • Field Details

    • FORMATTER

      private static final AtomicReference<Formatter> FORMATTER
      The formatter for the toWKT() and toString() methods. Formatters are not thread-safe, consequently we must make sure that only one thread uses a given instance.
      Note 1: We do not use synchronization because the formatter will call back user's code, which introduce a risk of thread lock if the user performs his own synchronization.
      Note 2: We do not use ThreadLocal because Formatter is not reentrant neither, so it may produce very confusing behavior when debugging a code that perform WKT formatting (some debuggers seem to invoke toString() for their own purpose in the same thread). Since toString() is typically invoked for debugging purpose, a single formatter for any thread is presumed sufficient.
  • 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 cannot 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 cannot 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 cannot 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 cannot 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.

    • formatWKT

      private String formatWKT(Convention convention, boolean colorize, boolean strict) throws UnformattableObjectException
      Returns a WKT for this object using the specified convention. If strict is true, then an exception is thrown if the WKT is not standard-compliant. If strict if false, then warnings are appended after the WKT instead.
      Parameters:
      convention - the convention for choosing WKT element names.
      colorize - true for applying syntax coloring, or false otherwise.
      strict - true if an exception shall be thrown for unformattable objects, or false for providing a non-standard formatting instead.
      Returns:
      the Well Known Text (WKT) or a pseudo-WKT representation of this object.
      Throws:
      UnformattableObjectException - if strict is true and this object cannot be formatted.
    • 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:

      Formatting non-standard WKT

      If the implementation cannot 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: