Package org.apache.sis.io.wkt

# Class Warnings

Object
Warnings

All Implemented Interfaces:
  `Serializable`, `Localized`

public final class Warnings extends Object implements Localized, Serializable
Warnings that occurred during a Well Known Text (WKT) parsing or formatting. Information provided by this object include:

- Recoverable exceptions.
- At formatting time, object that can not be formatted in a standard-compliant WKT.
- At parsing time, unknown keywords.

Example: after parsing the following WKT:

>     GeographicCRS[“WGS 84”,
>       Datum[“World Geodetic System 1984”,
>         Ellipsoid[“WGS84”, 6378137.0, 298.257223563, Intruder[“some text here”]]],
>         PrimeMeridian[“Greenwich”, 0.0, Intruder[“other text here”]],
>       AngularUnit[“degree”, 0.017453292519943295]]

a call to `WKTFormat​.getWarnings()` would return a `Warnings` instance with the following information:

- `getRootElement()` returns `"WGS 84"`,
- `getUnknownElements()` returns `{"Intruder"}`, and
- `getUnknownElementLocations("Intruder")` returns `{"Ellipsoid", "PrimeMeridian"}`.

Since:
  0.6
See Also:
  - `WKTFormat​.getWarnings()`
  - Serialized Form

Defined in the `sis-referencing` module

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Exception`
  `getException(int index)`
  Returns the exception which was the cause of the message at the given index, or `null` if none.
  `Set<Exception>`
  `getExceptions()`
  Returns the non-fatal exceptions that occurred during the parsing or formatting.
  `String[]`
  `getExceptionSource(Exception ex)`
  Returns the keywords of the WKT element where the given exception occurred, or `null` if unknown.
  `Locale`
  `getLocale()`
  Returns the locale in which warning messages are reported by the default `toString()` method.
  `String`
  `getMessage(int index)`
  Returns a warning message.
  `final int`
  `getNumMessages()`
  Returns the number of warning messages.
  `String`
  `getRootElement()`
  Returns the name of the root element being parsed or formatted.
  `Collection<String>`
  `getUnknownElementLocations(String element)`
  Returns the keyword of WKT elements that contains the given unknown element.
  `Set<String>`
  `getUnknownElements()`
  Returns the keywords of all unknown elements found during the WKT parsing.
  `String`
  `toString()`
  Returns a string representation of the warning messages in the formatter locale.
  `String`
  `toString(Locale locale)`
  Returns a string representation of the warning messages in the given locale.

  ### Methods inherited from class Object

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

- ## Method Details

  - ### getLocale

    public Locale getLocale()
    Returns the locale in which warning messages are reported by the default `toString()` method. This is not necessarily the same locale than the one used for parsing and formatting dates and numbers in the WKT.
    Specified by:
      `getLocale` in interface `Localized`
    Returns:
      the locale or warning messages are reported.

  - ### getRootElement

    public String getRootElement()
    Returns the name of the root element being parsed or formatted. If the parsed of formatted object implement the `IdentifiedObject` interface, then this method returns the value of `IdentifiedObject​.getName()​.getCode()`. Otherwise this method returns a simple class name.
    Returns:
      the name of the root element, or `null` if unknown.

  - ### getNumMessages

    public final int getNumMessages()
    Returns the number of warning messages.
    Returns:
      the number of warning messages.

  - ### getMessage

    public String getMessage(int index)
    Returns a warning message.
    Parameters:
      `index` - 0 for the first warning, 1 for the second warning, etc. until `getNumMessages()` - 1.
    Returns:
      the i-th warning message.

  - ### getException

    public Exception getException(int index)
    Returns the exception which was the cause of the message at the given index, or `null` if none.
    Parameters:
      `index` - the value given to `getMessage(int)`.
    Returns:
      the exception which was the cause of the warning message, or `null` if none.

  - ### getExceptions

    public Set<Exception> getExceptions()
    Returns the non-fatal exceptions that occurred during the parsing or formatting. If no exception occurred, returns an empty set.
    Returns:
      the non-fatal exceptions that occurred.

  - ### getExceptionSource

    public String[] getExceptionSource(Exception ex)
    Returns the keywords of the WKT element where the given exception occurred, or `null` if unknown. If this method returns a non-null array, then `source[0]` is the keyword of the WKT element where the exception occurred and `source[1]` is the keyword of the parent of `source[0]`.
    Note: in other words, this method returns the tail of the path to the WKT element where the exception occurred, but with path elements stored in reverse order.
    Parameters:
      `ex` - the exception for which to get the source.
    Returns:
      the keywords of the WKT element where the given exception occurred, or `null` if unknown.

  - ### getUnknownElements

    public Set<String> getUnknownElements()
    Returns the keywords of all unknown elements found during the WKT parsing.
    Returns:
      the keywords of unknown WKT elements, or an empty set if none.

  - ### getUnknownElementLocations

    public Collection<String> getUnknownElementLocations(String element)
    Returns the keyword of WKT elements that contains the given unknown element. If the given element is not one of the value returned by `getUnknownElements()`, then this method returns `null`.

    The returned collection elements are in no particular order.

    Parameters:
      `element` - the keyword of the unknown element.
    Returns:
      the keywords of elements where the given unknown element was found.

  - ### toString

    public String toString()
    Returns a string representation of the warning messages in the formatter locale. The locale used by this method is given by `getLocale()`.
    Overrides:
      `toString` in class `Object`
    Returns:
      a string representation of the warning messages.

  - ### toString

    public String toString(Locale locale)
    Returns a string representation of the warning messages in the given locale. This method formats the warnings in a bullet list.
    Parameters:
      `locale` - the locale to use for formatting warning messages.
    Returns:
      a string representation of the warning messages.