Class Formatter
- All Implemented Interfaces:
Localized
Formatter
instances are created by WKTFormat
and given to the
FormattableObject.formatTo(Formatter)
method of the object to format.
Formatter
provides the following services:
- A series of
append(…)
methods to be invoked by theformatTo(Formatter)
implementations. - Contextual information. In particular, the contextual units depend on the enclosing WKT element.
- A flag for declaring the object unformattable.
- Since:
- 0.4
- Version:
- 1.1
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate org.opengis.metadata.citation.Citation
The preferred authority for objects or parameter names.(package private) static final String
The value ofX364.BACKGROUND_DEFAULT.sequence()
, hard-coded for avoidingX364
class loading.(package private) static final int
Accuracy of geographic bounding boxes, in number of fraction digits.private StringBuffer
The buffer in which to format.private int
Incremented whensetColor(ElementKind)
is invoked, and decremented whenresetColor()
is invoked.private Colors
The colors to use for this formatter, ornull
for no syntax coloring.private Convention
The preferred convention for objects or parameter names.private final DateFormat
The object to use for formatting dates.private final FieldPosition
Dummy field position.private int
Index of the first character in the buffer where the element content will be formatted.private final List<FormattableObject>
The enclosing WKT element being formatted.private final Locale
The locale for error messages (not for formatting).(package private) static final String
The value ofX364.FOREGROUND_DEFAULT.sequence()
, hard-coded for avoidingX364
class loading.private long
A bits mask of elements which defined a contextual units.private boolean
true
if the last formatted element was invalid WKT and shall be highlighted with syntactic coloration.private byte
The amount of spaces to use in indentation, or -1 if indentation is disabled.private boolean
true
if we are in the process of formatting the optional complementary attributes.private IntegerList
Indices where to insert additional margin, ornull
if none.private int
Maximum number of elements to show in lists, orInteger.MAX_VALUE
if unlimited.private final Locale
The locale for the localization of international strings.private byte
-1
for short keywords,+1
for long keywords or 0 for the default.private int
The amount of space to write on the left side of each line.private final NumberFormat
The object to use for formatting numbers.private boolean
true
if a new line were requested during the execution ofappend(FormattableObject)
.private final String
The value ofSymbols.getSeparator()
without trailing spaces, followed by the system line separator.private final Symbols
The symbols to use for this formatter.private byte
1
if keywords shall be converted to upper cases, or-1
for lower cases.(package private) Transliterator
Transliterator.IDENTITY
for preserving non-ASCII characters.private final UnitFormat
The object to use for formatting unit symbols.private final Map<javax.measure.Unit<?>,
javax.measure.Unit<?>> The contextual units for writing lengths, angles or other type of measurements.(package private) boolean
true
if thisFormatter
should verify the validity of characters in quoted texts.private static final int
Maximal accuracy of vertical extents, in number of fraction digits.private Warnings
The warnings that occurred during WKT formatting, ornull
if none. -
Constructor Summary
ConstructorsConstructorDescriptionCreates a new formatter instance with the default configuration.Formatter
(Locale locale, Locale errorLocale, Symbols symbols, NumberFormat numberFormat, DateFormat dateFormat, UnitFormat unitFormat) Constructor for private use byWKTFormat
only.Formatter
(Convention convention, Symbols symbols, int indentation) Creates a new formatter instance with the specified convention, symbols and indentation. -
Method Summary
Modifier and TypeMethodDescription<Q extends javax.measure.Quantity<Q>>
javax.measure.Unit<Q>addContextualUnit
(javax.measure.Unit<Q> unit) Adds a unit to use for the next measurements of the quantityQ
.void
append
(boolean value) Appends a boolean value.void
append
(double number) Appends an floating point value.void
append
(long number) Appends an integer value.void
append
(String text, ElementKind type) Appends a character string between quotes.void
Appends a date.void
append
(javax.measure.Unit<?> unit) Appends a unit in aUnit[…]
element or one of the specialized elements.void
append
(FormattableObject object) Appends the givenFormattableObject
.void
Appends rows of numbers.void
append
(org.opengis.metadata.extent.GeographicBoundingBox bbox, int fractionDigits) Appends the given geographic bounding box in aBBOX[…]
element.void
append
(org.opengis.referencing.operation.MathTransform transform) Appends the given math transform, typically (but not necessarily) in aPARAM_MT[…]
element.void
append
(org.opengis.util.CodeList<?> code) Appends an enumeration or code list value.void
Appends an object or an array of objects.private void
appendComplement
(org.opengis.referencing.IdentifiedObject object, FormattableObject parent, FormattableObject gp) Appends the optional complementary attributes common to manyIdentifiedObject
subtypes.(package private) final boolean
appendElement
(Object value) Tries to append an object of theKEYWORD[something]
form.private void
appendExact
(double number) Appends a number which is assumed to have no rounding error greater than the limit of IEEE 754 accuracy.private void
appendForSubtypes
(org.opengis.referencing.IdentifiedObject object) Appends the anchor, scope and domain of validity of the given object.private void
appendOnNewLine
(String keyword, org.opengis.util.InternationalString text, ElementKind type) Appends an international text in an element having the given keyword.private void
appendPreset
(double number) Appends the given number without any change to theNumberFormat
setting.private void
Conditionally appends a separator to the buffer, if needed.private void
appendTemporalExtent
(Range<Date> range) Appends the given temporal extent, if non-null.(package private) final boolean
appendValue
(Object value) Tries to append a small unit of information like number, date, boolean, code list, character string or an array of those.private void
Appends the given vertical extent, if non-null.(package private) final void
Appends the warnings after the WKT string.(package private) final void
clear()
Clears this formatter before formatting a new object.private void
closeElement
(boolean newLine) Closes the element opened byopenElement(boolean, String)
.private void
closeQuote
(int fromIndex) Double or delete any closing quote character that may appear at or after the given index, then append the closing quote character.(package private) final void
configure
(Convention convention, org.opengis.metadata.citation.Citation authority, Colors colors, byte toUpperCase, byte longKeywords, byte indentation, int listSizeLimit) Sets the convention, authority, colors and indentation to use for formatting WKT elements.delegateTo
(Object other) Delegates the formatting to anotherFormattableObject
implementation.final Convention
Returns the convention to use for formatting the WKT.getEnclosingElement
(int depth) Returns the enclosing WKT element, ornull
if element being formatted is the root.final Locale
Returns the locale to use for localizingInternationalString
instances.private static String
Returns the name of the GeoAPI interface implemented by the given class.final org.opengis.metadata.citation.Citation
Returns the preferred authority for choosing the projection and parameter names.final Transliterator
Returns a mapper between Java character sequences and the characters to write in WKT.(package private) final Warnings
Returns the warnings, ornull
if none.boolean
hasContextualUnit
(int depth) Returnstrue
if the element at the given depth specified a contextual unit.void
indent
(int amount) Increases or decreases the indentation.boolean
Returnstrue
if the WKT written by this formatter is not strictly compliant to the WKT specification.void
newLine()
Request a line separator before the next element to format.private void
openElement
(boolean newLine, String keyword) Appends a separator if needed, then opens a new element.private void
quote
(String text, ElementKind type) Appends the given string as a quoted text.private void
Appends in the buffer the ANSI escape sequence for resetting the color to the default.void
restoreContextualUnit
(javax.measure.Unit<?> unit, javax.measure.Unit<?> previous) Restores the contextual unit to its previous state before the call toaddContextualUnit(Unit)
.(package private) final void
setBuffer
(StringBuffer buffer) Sets the destination buffer.private void
setColor
(ElementKind type) Appends in the buffer the ANSI escape sequence for the given kind of element.void
setInvalidWKT
(Class<?> unformattable, Exception cause) Marks the current WKT representation of the given class as not strictly compliant with the WKT specification.private void
setInvalidWKT
(String invalidElement, Exception cause) Implementation of publicsetInvalidWKT(…)
methods.void
setInvalidWKT
(org.opengis.referencing.IdentifiedObject unformattable, Exception cause) Marks the current WKT representation of the given object as not strictly compliant with the WKT specification.shortOrLong
(String shortKeyword, String longKeyword) Selects a short or long keyword depending on theKeywordStyle
value.<Q extends javax.measure.Quantity<Q>>
javax.measure.Unit<Q>toContextualUnit
(javax.measure.Unit<Q> unit) Returns the unit to use instead of the given one, orunit
if there is no replacement.toString()
Returns a string representation of this formatter for debugging purpose.toWKT()
Returns the WKT formatted by this object.private Warnings
warnings()
Returns the object where to store warnings.
-
Field Details
-
BBOX_ACCURACY
static final int BBOX_ACCURACYAccuracy of geographic bounding boxes, in number of fraction digits. We use the accuracy recommended by ISO 19162.- See Also:
-
VERTICAL_ACCURACY
private static final int VERTICAL_ACCURACYMaximal accuracy of vertical extents, in number of fraction digits. The value used here is arbitrary and may change in any future SIS version.- See Also:
-
FOREGROUND_DEFAULT
The value ofX364.FOREGROUND_DEFAULT.sequence()
, hard-coded for avoidingX364
class loading.- See Also:
-
BACKGROUND_DEFAULT
The value ofX364.BACKGROUND_DEFAULT.sequence()
, hard-coded for avoidingX364
class loading.- See Also:
-
locale
The locale for the localization of international strings. This is not the same thanSymbols.getLocale()
.- See Also:
-
symbols
The symbols to use for this formatter. -
separatorNewLine
The value ofSymbols.getSeparator()
without trailing spaces, followed by the system line separator. Computed bySymbols.separatorNewLine()
and stored for reuse. -
colors
The colors to use for this formatter, ornull
for no syntax coloring. If non-null, the terminal must be ANSI X3.64 compatible. The default value isnull
. -
convention
The preferred convention for objects or parameter names. This field should never benull
. -
authority
private org.opengis.metadata.citation.Citation authorityThe preferred authority for objects or parameter names. -
transliterator
Transliterator transliteratorTransliterator.IDENTITY
for preserving non-ASCII characters. The default value isTransliterator.DEFAULT
, which causes replacements like "é" → "e" in all elements exceptREMARKS["…"]
. May also be a user supplied transliterator.- See Also:
-
verifyCharacterValidity
boolean verifyCharacterValiditytrue
if thisFormatter
should verify the validity of characters in quoted texts. ISO 19162 restricts quoted texts to ASCII characters with addition of degree symbol (°). -
enclosingElements
The enclosing WKT element being formatted.- See Also:
-
units
The contextual units for writing lengths, angles or other type of measurements. A unit not present in this map means that the "natural" unit of the WKT element shall be used. This value is set for example by"GEOGCS"
, which force its enclosing"PRIMEM"
to take the same units than itself. -
hasContextualUnit
private long hasContextualUnitA bits mask of elements which defined a contextual units. The rightmost bit is for the current element. The bit before the rightmost is for the parent of current element, etc.- See Also:
-
numberFormat
The object to use for formatting numbers. -
dateFormat
The object to use for formatting dates. -
unitFormat
The object to use for formatting unit symbols. -
dummy
Dummy field position. -
buffer
The buffer in which to format. Consider this field as final. The only method to change (indirectly) the value of this field isWKTFormat.format(Object, Appendable)
.- See Also:
-
elementStart
private int elementStartIndex of the first character in the buffer where the element content will be formatted. This is set after the opening bracket and is used for determining if a separator needs to be appended.- See Also:
-
toUpperCase
private byte toUpperCase1
if keywords shall be converted to upper cases, or-1
for lower cases. -
longKeywords
private byte longKeywords-1
for short keywords,+1
for long keywords or 0 for the default. -
listSizeLimit
private int listSizeLimitMaximum number of elements to show in lists, orInteger.MAX_VALUE
if unlimited. If a list is longer than this length, only the first and the last elements will be shown. This limit applies in particular toMathTransform
parameter values ofdouble[]
type, since those parameters may be large interpolation tables. -
colorApplied
private int colorAppliedIncremented whensetColor(ElementKind)
is invoked, and decremented whenresetColor()
is invoked. Used in order to prevent child elements to overwrite the colors decided by enclosing elements. -
indentation
private byte indentationThe amount of spaces to use in indentation, or -1 if indentation is disabled. -
margin
private int marginThe amount of space to write on the left side of each line. This amount is increased byindentation
every time aFormattableObject
is appended in a new indentation level. -
keywordSpaceAt
Indices where to insert additional margin, ornull
if none. The margin to insert will be the the width of the keyword (e.g."BOX"
), which is usually unknown toFormatter
untilFormattableObject
finished to write the element. This field is usuallynull
, unless formatting geometries. -
requestNewLine
private boolean requestNewLinetrue
if a new line were requested during the execution ofappend(FormattableObject)
. This is used to determine if the nextUNIT
andID
elements shall appear on a new line. -
isComplement
private boolean isComplementtrue
if we are in the process of formatting the optional complementary attributes. Those attributes areSCOPE
,AREA
,BBOX
,VERTICALEXTENT
,TIMEEXTENT
,ID
(previously known asAUTHORITY
) andREMARKS
, and have a special treatment: they are written byappend(FormattableObject)
after theformatTo(Formatter)
method returned. -
highlightError
private boolean highlightErrortrue
if the last formatted element was invalid WKT and shall be highlighted with syntactic coloration. This field has no effect ifcolors
is null. This field is reset tofalse
after the invalid part has been processed byappend(FormattableObject)
, in order to highlight only the first erroneous element without clearing thewarnings
value. -
warnings
The warnings that occurred during WKT formatting, ornull
if none.- See Also:
-
errorLocale
The locale for error messages (not for formatting).- See Also:
-
-
Constructor Details
-
Formatter
public Formatter()Creates a new formatter instance with the default configuration. -
Formatter
Creates a new formatter instance with the specified convention, symbols and indentation.- Parameters:
convention
- the convention to use.symbols
- the symbols.indentation
- the amount of spaces to use in indentation for WKT formatting, orWKTFormat.SINGLE_LINE
for formatting the whole WKT on a single line.
-
Formatter
Formatter(Locale locale, Locale errorLocale, Symbols symbols, NumberFormat numberFormat, DateFormat dateFormat, UnitFormat unitFormat) Constructor for private use byWKTFormat
only. This allows to use the number format created byWKTFormat.createFormat(Class)
, which may be overridden by the user.- Parameters:
locale
- the locale for the localization of international strings.errorLocale
- the locale for error messages (not for parsing), ornull
for the system default.symbols
- the symbols to use for this formatter.numberFormat
- the object to use for formatting numbers.dateFormat
- the object to use for formatting dates.unitFormat
- the object to use for formatting unit symbols.
-
-
Method Details
-
setBuffer
Sets the destination buffer. Used byWKTFormat.format(Object, Appendable)
only. -
configure
final void configure(Convention convention, org.opengis.metadata.citation.Citation authority, Colors colors, byte toUpperCase, byte longKeywords, byte indentation, int listSizeLimit) Sets the convention, authority, colors and indentation to use for formatting WKT elements. This method does not validate the argument — validation must be done by the caller.- Parameters:
convention
- the convention, ornull
for the default value.authority
- the authority, ornull
for inferring it from the convention.colors
- the syntax coloring, ornull
if none.toUpperCase
- whether keywords shall be converted to upper cases.longKeywords
--1
for short keywords,+1
for long keywords or 0 for the default.indentation
- the amount of spaces to use in indentation for WKT formatting, orWKTFormat.SINGLE_LINE
.listSizeLimit
- maximum number of elements to show in lists, orInteger.MAX_VALUE
if unlimited.
-
getConvention
Returns the convention to use for formatting the WKT. The default isConvention.WKT2
.- Returns:
- the convention (never
null
). - See Also:
-
getTransliterator
Returns a mapper between Java character sequences and the characters to write in WKT. The intent is to specify how to write characters that are not allowed in WKT strings according ISO 19162 specification. Return values can be:Transliterator.DEFAULT
for performing replacements like "é" → "e" in all WKT elements exceptREMARKS["…"]
.Transliterator.IDENTITY
for preserving non-ASCII characters.- Any other user supplied mapping.
- Returns:
- the mapper between Java character sequences and the characters to write in WKT.
- Since:
- 0.6
- See Also:
-
getNameAuthority
public final org.opengis.metadata.citation.Citation getNameAuthority()Returns the preferred authority for choosing the projection and parameter names.The preferred authority can be set by the
WKTFormat.setNameAuthority(Citation)
method. This is not necessarily the authority who created the object to format.Example: The EPSG name of theEPSG:6326
datum is "World Geodetic System 1984". However if the preferred authority is OGC, then the formatted datum name will rather look like "WGS84" (the exact string depends on the object aliases).- Returns:
- the authority for projection and parameter names.
- See Also:
-
getLocale
Returns the locale to use for localizingInternationalString
instances. This is not the locale for formatting dates and numbers. -
setColor
Appends in the buffer the ANSI escape sequence for the given kind of element. This method does nothing unless syntax coloring has been explicitly enabled. -
resetColor
private void resetColor()Appends in the buffer the ANSI escape sequence for resetting the color to the default. This method does nothing unless syntax coloring has been explicitly enabled. -
newLine
public void newLine()Request a line separator before the next element to format. Invoking this method before anyappend(…)
method call will cause the next element to appear on the next line.This method has no effect in any of the following cases:
- This method has already been invoked before the next
append(…)
. - The indentation is
WKTFormat.SINGLE_LINE
.
- This method has already been invoked before the next
-
indent
public void indent(int amount) Increases or decreases the indentation. A value of+1
increases the indentation by the amount of spaces specified at construction time, and a value of-1
reduces it by the same amount.- Parameters:
amount
- +1 for increasing the indentation, or -1 for decreasing it, or 0 for no-op.
-
shortOrLong
Selects a short or long keyword depending on theKeywordStyle
value. This method can be used byFormattableObject.formatTo(Formatter)
implementations for choosing the return value.- Parameters:
shortKeyword
- the keyword to return if the style isKeywordStyle.SHORT
.longKeyword
- the keyword to return if the style isKeywordStyle.LONG
.- Returns:
- the short or long keyword depending on the keyword style setting.
- Since:
- 0.6
- See Also:
-
appendSeparator
private void appendSeparator()Conditionally appends a separator to the buffer, if needed. This method does nothing if there is currently no element at the buffer end. -
openElement
Appends a separator if needed, then opens a new element.- Parameters:
newLine
-true
for invokingnewLine()
first.keyword
- the element keyword (e.g."DATUM"
,"AXIS"
, etc).
-
closeElement
private void closeElement(boolean newLine) Closes the element opened byopenElement(boolean, String)
.- Parameters:
newLine
-true
for invokingnewLine()
last.
-
append
Appends the givenFormattableObject
. This method performs the following steps:- Invoke
object.formatTo(this)
. - Prepend the keyword returned by the above method call (e.g.
"GEOCS"
). - If the given object is an instance of
IdentifiedObject
, then append complementary information:
Complementary WKT elements WKT 2 element WKT 1 element For types Anchor[…]
Datum
Scope[…]
ReferenceSystem
,Datum
,CoordinateOperation
Area[…]
ReferenceSystem
,Datum
,CoordinateOperation
BBox[…]
ReferenceSystem
,Datum
,CoordinateOperation
VerticalExtent[…]
ReferenceSystem
,Datum
,CoordinateOperation
TimeExtent[…]
ReferenceSystem
,Datum
,CoordinateOperation
Id[…]
Authority[…]
IdentifiedObject
Remarks[…]
ReferenceSystem
,CoordinateOperation
- Parameters:
object
- the formattable object to append to the WKT, ornull
if none.
- Invoke
-
appendComplement
private void appendComplement(org.opengis.referencing.IdentifiedObject object, FormattableObject parent, FormattableObject gp) Appends the optional complementary attributes common to manyIdentifiedObject
subtypes. Those attributes areANCHOR
,SCOPE
,AREA
,BBOX
,VERTICALEXTENT
,TIMEEXTENT
,ID
(previously known asAUTHORITY
) andREMARKS
, and have a special treatment: they are written byappend(FormattableObject)
after theformatTo(Formatter)
method returned.The
For non-internal conventions, all elements other thanID[<name>,<code>,…]
element is normally written only for the root element (unless the convention isINTERNAL
), but there is various exceptions to this rule. If formatted, theID
element will be by default on the same line than the enclosing element (e.g.SPHEROID["Clarke 1866", …, ID["EPSG", 7008]]
). Other example:ID[…]
are formatted only forCoordinateOperation
and rootReferenceSystem
instances, with an exception for remarks ofReferenceSystem
embedded insideCoordinateOperation
. Those restrictions are our interpretation of the following ISO 19162 requirement:(…snip…)
<scope extent identifier remark>
is a collection of four optional attributes which may be applied to a coordinate reference system, a coordinate operation or a boundCRS. (…snip…) Identifier (…snip…) may also be utilised for components of these objects although this is not recommended except for coordinate operation methods (including map projections) and parameters. (…snip…) A<remark>
can be included within the descriptions of source and target CRS embedded within a coordinate transformation as well as within the coordinate transformation itself. -
appendForSubtypes
private void appendForSubtypes(org.opengis.referencing.IdentifiedObject object) Appends the anchor, scope and domain of validity of the given object. Those information are available only forReferenceSystem
,Datum
andCoordinateOperation
objects. -
append
public void append(org.opengis.metadata.extent.GeographicBoundingBox bbox, int fractionDigits) Appends the given geographic bounding box in aBBOX[…]
element. Longitude and latitude values will be formatted in decimal degrees. Longitudes are relative to the Greenwich meridian, with values increasing toward East. Latitudes values are increasing toward North.Numerical precision
The ISO 19162 standards recommends to format those values with only 2 decimal digits. This is becauseGeographicBoundingBox
does not specify the datum, so this box is an approximated information only.- Parameters:
bbox
- the geographic bounding box to append to the WKT, ornull
.fractionDigits
- the number of fraction digits to use. The recommended value is 2.
-
appendVerticalExtent
Appends the given vertical extent, if non-null. This method chooses an accuracy from the vertical span. Examples:- “
VerticalExtent[102, 108, LengthUnit["m", 1]]
” (Δz = 6) - “
VerticalExtent[100.2, 100.8, LengthUnit["m", 1]]
” (Δz = 0.6)
- “
-
appendTemporalExtent
Appends the given temporal extent, if non-null. Examples:- “
TemporalExtent[1980-04-12, 1980-04-18]
” - “
TemporalExtent[1980-04-12T18:00:00.0Z, 1980-04-12T21:00:00.0Z]
”
- “
-
append
public void append(org.opengis.referencing.operation.MathTransform transform) Appends the given math transform, typically (but not necessarily) in aPARAM_MT[…]
element.- Parameters:
transform
- the transform object to append to the WKT, ornull
if none.
-
appendOnNewLine
private void appendOnNewLine(String keyword, org.opengis.util.InternationalString text, ElementKind type) Appends an international text in an element having the given keyword. Since this method is typically invoked for long descriptions, the element will be written on its own line.Example:Scope["Large scale topographic mapping and cadastre."]
Area["Netherlands offshore."]
- Parameters:
keyword
- the camel-case keyword. Example:"Scope"
,"Area"
or"Remarks"
.text
- the text, ornull
if none.type
- the key of the colors to apply if syntax coloring is enabled.
-
append
Appends a character string between quotes. The element separator will be written before the text if needed.- Parameters:
text
- the string to format to the WKT, ornull
if none.type
- the key of the colors to apply if syntax coloring is enabled, ornull
if none.
-
quote
Appends the given string as a quoted text. If the given string contains the closing quote character, that character will be doubled (WKT 2) or deleted (WKT 1). We check for the closing quote only because it is the character that the parser will look for determining the text end. -
closeQuote
private void closeQuote(int fromIndex) Double or delete any closing quote character that may appear at or after the given index, then append the closing quote character. The action taken for the quote character depends on the WKT version:- For WKT 2, double the quote as specified in the standard.
- For WKT 1, conservatively delete the quote because the standard does not said what to do.
-
append
public void append(org.opengis.util.CodeList<?> code) Appends an enumeration or code list value. The element separator will be written before the code list if needed.For the WKT 2 format, this method uses the ISO name if available (for example
"northEast"
). For the WKT 1 format, this method uses the programmatic name instead (for example"NORTH_EAST"
).- Parameters:
code
- the code list to append to the WKT, ornull
if none.
-
append
Appends a date. The element separator will be written before the date if needed.- Parameters:
date
- the date to append to the WKT, ornull
if none.
-
append
public void append(boolean value) Appends a boolean value. The element separator will be written before the boolean if needed.- Parameters:
value
- the boolean to append to the WKT.
-
append
public void append(long number) Appends an integer value. The element separator will be written before the number if needed.- Parameters:
number
- the integer to append to the WKT.
-
append
public void append(double number) Appends an floating point value. The element separator will be written before the number if needed.- Parameters:
number
- the floating point value to append to the WKT.
-
append
Appends rows of numbers. Each number is separated by a space, and each row is separated by a comma. Rows usually have all the same length, but this is not mandatory. This method can be used for formatting geometries or matrix.- Parameters:
rows
- the rows to append, ornull
if none.fractionDigits
- the number of fraction digits for each column in a row, ornull
for default. A precision can be specified for each column because those columns are often different dimensions of a Coordinate Reference System (CRS), each with their own units of measurement. If a row contains more numbers thanfractionDigits.length
, then the last value in this array is repeated for all remaining row numbers.- Since:
- 1.0
-
appendPreset
private void appendPreset(double number) Appends the given number without any change to theNumberFormat
setting. Caller shall ensure that the following method has been invoked prior this method call: -
appendExact
private void appendExact(double number) Appends a number which is assumed to have no rounding error greater than the limit of IEEE 754 accuracy. This method is invoked for formatting the unit conversion factors, which are defined by the Unit library rather than specified by the user. The given number is formatted byDouble.toString(double)
both for accuracy and for automatic usage of scientific notation. If the given number is an integer, then it formatted without the trailing ".0". -
append
public void append(javax.measure.Unit<?> unit) Appends a unit in aUnit[…]
element or one of the specialized elements. Specialized elements areAngleUnit
,LengthUnit
,ScaleUnit
,ParametricUnit
andTimeUnit
. By default, specialized unit keywords are used with the WKT 2 convention.Example:append(Units.KILOMETRE)
will append "LengthUnit["km", 1000]
" to the WKT.- Parameters:
unit
- the unit to append to the WKT, ornull
if none.- See Also:
-
appendAny
Appends an object or an array of objects. This method performs the following choices:- If the given value is
null
, then this method appends the "null
" string (without quotes). - Otherwise if the given value is an array, then this method appends the opening sequence symbol, formats all elements by invoking this method recursively, then appends the closing sequence symbol.
- Otherwise if the value type is assignable to the argument type of one of the
append(…)
methods in this class, then the formatting will be delegated to that method. - Otherwise the given value is appended as a quoted text with its
toString()
representation.
- Parameters:
value
- the value to append to the WKT, ornull
.
- If the given value is
-
appendValue
Tries to append a small unit of information like number, date, boolean, code list, character string or an array of those. The key difference between this method andappendElement(Object)
is that the values formatted by thisappendValue(Object)
method do not have keyword.- Returns:
true
on success, orfalse
if the given type is not recognized.
-
appendElement
Tries to append an object of theKEYWORD[something]
form. The given value is typically, but not necessarily, aFormattableObject
object or an instance of an interface that can be converted toFormattableObject
.- Returns:
true
on success, orfalse
if the given type is not recognized.
-
delegateTo
Delegates the formatting to anotherFormattableObject
implementation. Invoking this method is equivalent to first verifying theother
class, then delegating as below: This method is useful forFormattableObject
which are wrapper around another object. It allows to delegate the WKT formatting to the wrapped object.- Parameters:
other
- the object to format with this formatter.- Returns:
- the value returned by
FormattableObject.formatTo(Formatter)
. - Throws:
UnformattableObjectException
- Since:
- 0.5
-
getEnclosingElement
Returns the enclosing WKT element, ornull
if element being formatted is the root. This method can be invoked by child elements having some aspects that depend on the enclosing element.- Parameters:
depth
- 1 for the immediate parent, 2 for the parent of the parent, etc.- Returns:
- the parent element at the given depth, or
null
.
-
hasContextualUnit
public boolean hasContextualUnit(int depth) Returnstrue
if the element at the given depth specified a contextual unit. This method returnstrue
if the formattable object given bygetEnclosingElement(depth)
has invokedaddContextualUnit(Unit)
with a non-null unit at least once.Note: The main purpose of this method is to allowAXIS[…]
elements to determine if they should inherit the unit specified by the enclosing CRS, or if they should specify their unit explicitly.- Parameters:
depth
- 1 for the immediate parent, 2 for the parent of the parent, etc.- Returns:
- whether the parent element at the given depth has invoked
addContextualUnit(…)
at least once.
-
addContextualUnit
public <Q extends javax.measure.Quantity<Q>> javax.measure.Unit<Q> addContextualUnit(javax.measure.Unit<Q> unit) Adds a unit to use for the next measurements of the quantityQ
. The given unit will apply to all WKT elements containing a value of quantityQ
without their ownUNIT[…]
element, until therestoreContextualUnit(Unit, Unit)
method is invoked.If the given unit is null, then this method does nothing and returns
null
.Special case
If the WKT conventions areWKT1_COMMON_UNITS
, then this method ignores the given unit and returnsnull
. SeeConvention.WKT1_COMMON_UNITS
javadoc for more information.- Type Parameters:
Q
- the unit quantity.- Parameters:
unit
- the contextual unit to add, ornull
if none.- Returns:
- the previous contextual unit for quantity
Q
, ornull
if none.
-
restoreContextualUnit
public void restoreContextualUnit(javax.measure.Unit<?> unit, javax.measure.Unit<?> previous) Restores the contextual unit to its previous state before the call toaddContextualUnit(Unit)
. This method is used in the following pattern:- Parameters:
unit
- the value given in argument toaddContextualUnit(unit)
(can benull
).previous
- the value returned byaddContextualUnit(unit)
(can benull
).- Throws:
IllegalStateException
- if this method has not been invoked in the pattern documented above.- Since:
- 0.6
-
toContextualUnit
public <Q extends javax.measure.Quantity<Q>> javax.measure.Unit<Q> toContextualUnit(javax.measure.Unit<Q> unit) Returns the unit to use instead of the given one, orunit
if there is no replacement. This method searches for a unit specified byaddContextualUnit(Unit)
which is compatible with the given unit.- Type Parameters:
Q
- the quantity of the unit.- Parameters:
unit
- the unit to replace by the contextual unit, ornull
.- Returns:
- a contextual unit compatible with the given unit, or
unit
(which may be null) if no contextual unit has been found.
-
isInvalidWKT
public boolean isInvalidWKT()Returnstrue
if the WKT written by this formatter is not strictly compliant to the WKT specification. This method returnstrue
ifsetInvalidWKT(IdentifiedObject, Exception)
has been invoked at least once. The action to take regarding invalid WKT is caller-dependent. For example,FormattableObject.toString()
will accepts loose WKT formatting and ignore this flag, whileFormattableObject.toWKT()
requires strict WKT formatting and will thrown an exception if this flag is set.- Returns:
true
if the WKT is invalid.
-
warnings
Returns the object where to store warnings. -
setInvalidWKT
Marks the current WKT representation of the given object as not strictly compliant with the WKT specification. This method can be invoked by implementations ofFormattableObject.formatTo(Formatter)
when the object to format is more complex than what the WKT specification allows. Applications can testisInvalidWKT()
later for checking WKT validity.- Parameters:
unformattable
- the object that cannot be formatted,cause
- the cause for the failure to format, ornull
if the cause is not an exception.
-
setInvalidWKT
Marks the current WKT representation of the given class as not strictly compliant with the WKT specification. This method can be used as an alternative tosetInvalidWKT(IdentifiedObject, Exception)
when the problematic object is not an instance ofIdentifiedObject
.- Parameters:
unformattable
- the class of the object that cannot be formatted,cause
- the cause for the failure to format, ornull
if the cause is not an exception.
-
setInvalidWKT
Implementation of publicsetInvalidWKT(…)
methods.Note: the message is stored as anInternationalString
in order to defer the actual message formatting until needed. -
getName
Returns the name of the GeoAPI interface implemented by the given class. If no GeoAPI interface is found, fallback on the class name. -
getWarnings
Returns the warnings, ornull
if none. -
appendWarnings
Appends the warnings after the WKT string. If there are no warnings, then this method does nothing. If this method is invoked, then it shall be the last method beforetoWKT()
.- Throws:
IOException
-
toWKT
Returns the WKT formatted by this object.- Returns:
- the WKT formatted by this formatter.
-
toString
Returns a string representation of this formatter for debugging purpose. -
clear
final void clear()Clears this formatter before formatting a new object. This method clears also the WKT validity flag.
-