Class Warnings

java.lang.Object
org.apache.sis.io.wkt.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 cannot be formatted in a standard-compliant WKT.
  • At parsing time, unknown keywords.
Example: after parsing the following WKT: a call to WKTFormat.getWarnings() would return a Warnings instance with the following information:
Since:
0.6
Version:
0.6
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final Locale
    The locale in which warning messages are reported.
    private Map<Exception,String[]>
    The keywords of elements in which exception occurred.
    private Map<String,List<String>>
    Keyword of unknown elements.
    private final boolean
    false if the warnings occurred while formatting, or true if they occurred while parsing.
    private List<Object>
    Warning messages or exceptions emitted during parsing or formatting.
    private boolean
    true if publish() has been invoked.
    private String
    Name identifier or class name of the root object being parsed or formatted.
    private static final long
    For cross-version compatibility.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Warnings(Locale locale, boolean isParsing, Map<String,List<String>> ignoredElements)
    Creates a new object for declaring warnings.
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) final void
    add(org.opengis.util.InternationalString message, Exception cause, String[] source)
    Adds a warning.
    getException(int index)
    Returns the exception which was the cause of the message at the given index, or null if none.
    Returns the non-fatal exceptions that occurred during the parsing or formatting.
    Returns the keywords of the WKT element where the given exception occurred, or null if unknown.
    Returns the locale in which warning messages are reported by the default toString() method.
    getMessage(int index)
    Returns a warning message.
    final int
    Returns the number of warning messages.
    Returns the name of the root element being parsed or formatted.
    Returns the keyword of WKT elements that contains the given unknown element.
    Returns the keywords of all unknown elements found during the WKT parsing.
    (package private) final void
    Must be invoked before this Warnings instance is given to the user, in order to protect this instance from changes caused by the next parsing operation.
    (package private) final void
    Invoked after construction for setting the identifier name or class name of the root object being parsed or formatted.
    Returns a string representation of the warning messages in the formatter locale.
    toString(Locale locale)
    Returns a string representation of the warning messages in the given locale.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • errorLocale

      private final Locale errorLocale
      The locale in which warning messages are reported. Not necessarily the same than the locale for number and date parsing or formatting.
      See Also:
    • isParsing

      private final boolean isParsing
      false if the warnings occurred while formatting, or true if they occurred while parsing.
    • root

      private String root
      Name identifier or class name of the root object being parsed or formatted.
      See Also:
    • messages

      private List<Object> messages
      Warning messages or exceptions emitted during parsing or formatting. Initially null and created when first needed.

      Objects in this list must be a sequence of the following tuple:

      • An optional message as an InternationalString.
      • An optional warning cause as an Exception.
      Any element of the above tuple can be null, but at least one element must be non-null.
      See Also:
    • exceptionSources

      private Map<Exception,String[]> exceptionSources
      The keywords of elements in which exception occurred. Initially null and created when first needed.

      For each String[] value, the first array element shall be the keyword of the WKT element in which the exception occurred. The second array element shall be the parent of above-cited first element. Other array elements can optionally be present for declaring the parents of the parent, but they will be ignored by this Warnings implementation.

    • ignoredElements

      private Map<String,List<String>> ignoredElements
      Keyword of unknown elements. This is initially a direct reference to the AbstractParser.ignoredElements map, which is okay only until a new parsing start. If this Warnings instance is given to the user, then the publish() method must be invoked in order to copy this map.
      See Also:
    • published

      private boolean published
      true if publish() has been invoked.
  • Constructor Details

    • Warnings

      Warnings(Locale locale, boolean isParsing, Map<String,List<String>> ignoredElements)
      Creates a new object for declaring warnings.
      Parameters:
      locale - the locale for reporting warning messages.
      isParsing - false if formatting, or true if parsing.
      ignoredElements - the AbstractParser.ignoredElements map, or an empty map (cannot be null).
  • Method Details

    • setRoot

      final void setRoot(Object obj)
      Invoked after construction for setting the identifier name or class name of the root object being parsed or formatted. Defined as a separated method instead of as an argument for the constructor because this information is more easily provided by WKTFormat rather than by the parser or formatter that created the Warnings object.
    • add

      final void add(org.opengis.util.InternationalString message, Exception cause, String[] source)
      Adds a warning. At least one of message or cause shall be non-null.
      Parameters:
      message - the message, or null.
      cause - the exception that caused the warning, or null
      source - the location of the exception, or null. If non-null, then source[0] shall be the keyword of the WKT element where the exception occurred, and source[1] the keyword of the parent of source[0].
    • publish

      final void publish()
      Must be invoked before this Warnings instance is given to the user, in order to protect this instance from changes caused by the next parsing operation.
    • 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.