Package org.apache.sis.parameter
Class ParameterFormat
- All Implemented Interfaces:
Serializable
,Cloneable
,Localized
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
The kinds of objects accepted by this formatter are:
DefaultParameterDescriptorGroup
javadoc
will be formatted by default as below:
Class | Remarks |
---|---|
ParameterValueGroup | Default values column is replaced by a column of the actual values. |
ParameterDescriptorGroup | Table caption is the parameter group name. |
OperationMethod | Table 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 mostjava.text.Format
subclasses, is not thread-safe.
- Since:
- 0.4
- Version:
- 1.3
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enum
The amount of information to include in the table formatted byParameterFormat
.Nested classes/interfaces inherited from class java.text.Format
Format.Field
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Colors
The colors for an output on X3.64 compatible terminal, ornull
if none.private ParameterFormat.ContentLevel
The amount of information to put in the table.private final Locale
The locale for international strings.private static final AtomicReference
<ParameterFormat> An instance created when first needed and potentially shared.If the identifier should be written only for some code spaces, those code spaces.private static final String
The default column separator.private static final long
For cross-version compatibility.Fields inherited from class org.apache.sis.io.TabularFormat
beforeFill, columnSeparator, fillCharacter, lineSeparator, omitTrailingNulls
-
Constructor Summary
ConstructorsConstructorDescriptionCreates a new formatter for the default locale and timezone.ParameterFormat
(Locale locale, TimeZone timezone) Creates a new formatter for the given locale and timezone. -
Method Summary
Modifier and TypeMethodDescriptionclone()
Returns a clone of this format.private static void
configure
(NumberFormat format, double m) Configures the number pattern to use for the given value.void
format
(Object object, Appendable toAppendTo) Formats the given object to the given stream of buffer.private void
format
(String name, org.opengis.parameter.ParameterDescriptorGroup group, org.opengis.parameter.ParameterValueGroup values, Appendable out) Implementation of publicformat(…)
methods for all content levels exceptNAME_SUMMARY
.private void
formatSummary
(org.opengis.referencing.IdentifiedObject[] objects, Appendable out) Implementation of publicformat(…)
methods forNAME_SUMMARY
content level.Returns the colors for an output on X3.64 compatible terminal, ornull
if none.Returns the amount of information to put in the table.getLocale
(Locale.Category category) Returns the locale for the given category.String[]
Returns the code spaces of names, aliases and identifiers to show, ornull
if there is no restriction.private static ParameterFormat
getSharedInstance
(Colors colors) Returns a shared instance ofParameterFormat
if possible, or a new one otherwise.Returns the type of objects formatted by this class.private boolean
isPreferredCodespace
(String codespace) Returnstrue
if a name, alias or identifier in the given codespace should be formatted.private void
nextColumn
(TableAppender table) Invoked when the formatter needs to move to the next column.parse
(CharSequence text, ParsePosition pos) Not yet supported.(package private) static void
Writes the given object to the console using a shared instance ofParameterFormat
.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.void
Sets the colors for an output on X3.64 compatible terminal.void
Sets the amount of information to put in the table.void
setPreferredCodespaces
(String... codespaces) Filters names, aliases and identifiers by their code spaces.(package private) static String
sharedFormat
(Object object) Formats the given object using a shared instance ofParameterFormat
.Methods inherited from class org.apache.sis.io.TabularFormat
getColumnSeparatorMatcher, getColumnSeparatorPattern, getLineSeparator, setColumnSeparatorPattern, setLineSeparator
Methods inherited from class org.apache.sis.io.CompoundFormat
createFormat, format, getFormat, getLocale, getTimeZone, parseObject, parseObject
Methods inherited from class java.text.Format
format, formatToCharacterIterator
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
INSTANCE
An instance created when first needed and potentially shared. -
SEPARATOR
The default column separator. User can change the separator by a call toTabularFormat.setColumnSeparatorPattern(String)
.- See Also:
-
displayLocale
The locale for international strings. -
contentLevel
The amount of information to put in the table.- See Also:
-
preferredCodespaces
If the identifier should be written only for some code spaces, those code spaces. Otherwisenull
. This set should not be modified; new set are created if needed.- See Also:
-
colors
The colors for an output on X3.64 compatible terminal, ornull
if none.- See Also:
-
-
Constructor Details
-
ParameterFormat
public ParameterFormat()Creates a new formatter for the default locale and timezone. -
ParameterFormat
Creates a new formatter for the given locale and timezone.- Parameters:
locale
- the locale, ornull
forLocale.ROOT
.timezone
- the timezone, ornull
for UTC.
-
-
Method Details
-
getValueType
Returns the type of objects formatted by this class. This method has to returnObject.class
since it is the only common parent to all object types accepted by this formatter.- Specified by:
getValueType
in classCompoundFormat<Object>
- Returns:
Object.class
-
getLocale
Returns the locale for the given category.Locale.Category.FORMAT
specifies the locale to use for values.Locale.Category.DISPLAY
specifies the locale to use for labels.
- Overrides:
getLocale
in classCompoundFormat<Object>
- Parameters:
category
- the category for which a locale is desired.- Returns:
- the locale for the given category (never
null
).
-
getContentLevel
Returns the amount of information to put in the table. The default value isParameterFormat.ContentLevel.BRIEF
.- Returns:
- the table content.
-
setContentLevel
Sets the amount of information to put in the table.- Parameters:
level
- the amount of information to put in the table.
-
getPreferredCodespaces
Returns the code spaces of names, aliases and identifiers to show, ornull
if there is no restriction. This method returns the sequence specified by the last call tosetPreferredCodespaces(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
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 aReferenceIdentifier.getCodeSpace()
,ScopedName.head()
orGenericName.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, ornull
for accepting all of them. Some typical values are"EPSG"
,"OGC"
or"GeoTIFF"
.
-
isPreferredCodespace
Returnstrue
if a name, alias or identifier in the given codespace should be formatted. -
getColors
Returns the colors for an output on X3.64 compatible terminal, ornull
if none. The default value isnull
.- Returns:
- the colors for an output on X3.64 compatible terminal, or
null
if none.
-
setColors
Sets the colors for an output on X3.64 compatible terminal.- Parameters:
colors
- the colors for an output on X3.64 compatible terminal, ornull
if none.
-
nextColumn
Invoked when the formatter needs to move to the next column. -
format
Formats the given object to the given stream of buffer. The object may be an instance of any of the following types:ParameterValueGroup
ParameterDescriptorGroup
OperationMethod
IdentifiedObject[]
— accepted only forParameterFormat.ContentLevel.NAME_SUMMARY
.
- Specified by:
format
in classCompoundFormat<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 publicformat(…)
methods for all content levels exceptNAME_SUMMARY
.- Parameters:
name
- the group name, usuallydescriptor.getName().getCode()
.group
- the parameter descriptor, usuallyvalues.getDescriptor()
.values
- the parameter values, ornull
if none.- Throws:
IOException
- if an error occurred while writing to the given appendable.
-
configure
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 publicformat(…)
methods forNAME_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.
-
print
Writes the given object to the console using a shared instance ofParameterFormat
. -
parse
Not yet supported.- Specified by:
parse
in classCompoundFormat<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
Returns a clone of this format.- Overrides:
clone
in classTabularFormat<Object>
- Returns:
- a clone of this format.
-