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

    All Methods Instance Methods Concrete Methods
    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.
    `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 default 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 Detail

    - #### 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 default locale. The locale used by this method is given by `getLocale()`. This is usually the locale given to the `WKTFormat` constructor.
      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.