Package org.apache.sis.parameter

Class ParameterFormat

java.lang.Object
java.text.Format
org.apache.sis.io.CompoundFormat<T>
org.apache.sis.io.TabularFormat<Object>
org.apache.sis.parameter.ParameterFormat
All Implemented Interfaces:
Serializable, Cloneable, Localized
public class ParameterFormat extends TabularFormat<Object>
Formats parameter descriptors or parameter values in a tabular format. This format assumes a monospaced font and an encoding supporting drawing box characters (e.g. UTF-8).

This class can format parameters with different levels of verbosity, specified by the ParameterFormat.ContentLevel property. The content level controls whether the formatter should write all names and aliases (at the cost of multi-line rows), or to pickup one name per parameter for a more compact table. See ParameterFormat.ContentLevel javadoc for output examples.

Example: The Mercator (variant A) example given in DefaultParameterDescriptorGroup javadoc will be formatted by default as below:
The kinds of objects accepted by this formatter are:
Formattable object types
Class Remarks
ParameterValueGroupDefault values column is replaced by a column of the actual values.
ParameterDescriptorGroupTable caption is the parameter group name.
OperationMethodTable caption is the method name (not necessarily the same than parameter group name).
IdentifiedObject[]Accepted only for ParameterFormat.ContentLevel.NAME_SUMMARY.

Limitations

  • The current implementation can only format features — parsing is not yet implemented.
  • ParameterFormat, like most java.text.Format subclasses, is not thread-safe.
Since:
0.4
Version:
1.3
See Also:

  • Field Details

  • Constructor Details

    • ParameterFormat

      public ParameterFormat()
      Creates a new formatter for the default locale and timezone.

    • ParameterFormat

      public ParameterFormat(Locale locale, TimeZone timezone)
      Creates a new formatter for the given locale and timezone.
      Parameters:
      locale - the locale, or null for Locale.ROOT.
      timezone - the timezone, or null for UTC.

  • Method Details

    • getValueType

      public final Class<Object> getValueType()
      Returns the type of objects formatted by this class. This method has to return Object.class since it is the only common parent to all object types accepted by this formatter.
      Specified by:
      getValueType in class CompoundFormat<Object>
      Returns:
      Object.class

    • getLocale

      public Locale getLocale(Locale.Category category)
      Returns the locale for the given category.
      Overrides:
      getLocale in class CompoundFormat<Object>
      Parameters:
      category - the category for which a locale is desired.
      Returns:
      the locale for the given category (never null).

    • getContentLevel

      public ParameterFormat.ContentLevel getContentLevel()
      Returns the amount of information to put in the table. The default value is ParameterFormat.ContentLevel.BRIEF.
      Returns:
      the table content.

    • setContentLevel

      public void setContentLevel(ParameterFormat.ContentLevel level)
      Sets the amount of information to put in the table.
      Parameters:
      level - the amount of information to put in the table.

    • getPreferredCodespaces

      public String[] getPreferredCodespaces()
      Returns the code spaces of names, aliases and identifiers to show, or null if there is no restriction. This method returns the sequence specified by the last call to setPreferredCodespaces(String[]), without duplicated values.

      The default value is null.

      Returns:
      the code spaces of names and identifiers to show, or null if no restriction.

    • setPreferredCodespaces

      public void setPreferredCodespaces(String... codespaces)
      Filters names, aliases and identifiers by their code spaces. If the given array is non-null, then the only names, aliases and identifiers to be formatted are those having a ReferenceIdentifier.getCodeSpace(), ScopedName.head() or GenericName.scope() value in the given list, unless no name or alias matches this criterion.
      Parameters:
      codespaces - the preferred code spaces of names, aliases and identifiers to format, or null for accepting all of them. Some typical values are "EPSG", "OGC" or "GeoTIFF".

    • isPreferredCodespace

      private boolean isPreferredCodespace(String codespace)
      Returns true if a name, alias or identifier in the given codespace should be formatted.

    • getColors

      public Colors getColors()
      Returns the colors for an output on X3.64 compatible terminal, or null if none. The default value is null.
      Returns:
      the colors for an output on X3.64 compatible terminal, or null if none.

    • setColors

      public void setColors(Colors colors)
      Sets the colors for an output on X3.64 compatible terminal.
      Parameters:
      colors - the colors for an output on X3.64 compatible terminal, or null if none.

    • nextColumn

      private void nextColumn(TableAppender table)
      Invoked when the formatter needs to move to the next column.

    • format

      public void format(Object object, Appendable toAppendTo) throws IOException
      Formats the given object to the given stream of buffer. The object may be an instance of any of the following types:
      Specified by:
      format in class CompoundFormat<Object>
      Parameters:
      object - the object to format.
      toAppendTo - where to format the object.
      Throws:
      IOException - if an error occurred while writing to the given appendable.

    • format

      private void format(String name, org.opengis.parameter.ParameterDescriptorGroup group, org.opengis.parameter.ParameterValueGroup values, Appendable out) throws IOException
      Implementation of public format(…) methods for all content levels except NAME_SUMMARY.
      Parameters:
      name - the group name, usually descriptor.getName().getCode().
      group - the parameter descriptor, usually values.getDescriptor().
      values - the parameter values, or null if none.
      Throws:
      IOException - if an error occurred while writing to the given appendable.

    • configure

      private static void configure(NumberFormat format, double m)
      Configures the number pattern to use for the given value. The main intent of this method is to ensure that the map projection scale factor (a value close to 1) is formatted with a sufficient number of fraction digits. A common default NumberFormat precision is 3 digits, which is not sufficient. For example, the scale factor of Transverse Mercator projections is 0.9996 (4 digits), and the scale factor of "NTF (Paris) / Lambert zone II" projection is 0.99987742 (8 digits).
      Parameters:
      format - the format to configure.
      m - the absolute value (magnitude) of the value to write.

    • formatSummary

      private void formatSummary(org.opengis.referencing.IdentifiedObject[] objects, Appendable out) throws IOException
      Implementation of public format(…) methods for NAME_SUMMARY content level.
      Parameters:
      objects - the collection of objects to format.
      out - the stream or buffer where to write the summary.
      Throws:
      IOException - if an error occurred will writing to the given appendable.

    • putIfAbsent

      private static String[] putIfAbsent(Vocabulary resources, String[] row, Map<String,Integer> columnIndices, String codespace, String name)
      Stores a value in the given position of the given row, expanding the array if needed. This operation is performed only if no value already exists in the cell.
      Parameters:
      row - all columns in a single row.
      columnIndices - indices of columns for each codespace.
      codespace - the codespace of the name or alias to add.
      name - the code of the name or alias to add.
      Returns:
      row, or a new array if it was necessary to expand the row.

    • getSharedInstance

      private static ParameterFormat getSharedInstance(Colors colors)
      Returns a shared instance of ParameterFormat if possible, or a new one otherwise.

    • sharedFormat

      static String sharedFormat(Object object)
      Formats the given object using a shared instance of ParameterFormat. This is used for AbstractParameterDescriptor.toString() implementation.

    • print

      static void print(Object object)
      Writes the given object to the console using a shared instance of ParameterFormat.

    • parse

      public Object parse(CharSequence text, ParsePosition pos) throws ParseException
      Not yet supported.
      Specified by:
      parse in class CompoundFormat<Object>
      Parameters:
      text - the character sequence for the object to parse.
      pos - the position where to start the parsing. On return, the position where the parsing stopped or where an error occurred.
      Returns:
      currently never return.
      Throws:
      ParseException - currently always thrown.

    • clone

      public ParameterFormat clone()
      Returns a clone of this format.
      Overrides:
      clone in class TabularFormat<Object>
      Returns:
      a clone of this format.