org.geotoolkit.io.wkt
Class Formatter

Object
  Formatter

@Visitor(value=Formattable.class)
public class Formatter
extends Object

Formats formattable objects as Well Known Text (WKT). A formatter is constructed with a specified set of symbols. The locale associated with the symbols is used for querying authority titles.

For example in order to format an object with curly brackets instead of square ones and the whole text on the same line (no indentation), use the following:

Formatter formatter = new Formatter(Symbols.CURLY_BRACKETS, null, WKTFormat.SINGLE_LINE);
formatter.append(theObject);
String wkt = formatter.toString();

// Following is needed only if you want to reuse
// the formatter again for other objects.
formatter.clear();

Formatters are not synchronized. It is recommended to create separate formatter instances for each thread. If multiple threads access a formatter concurrently, it must be synchronized externally.

Since:

2.0

Version:

3.20

Author:

Martin Desruisseaux (IRD, Geomatys)

Module:

referencing/geotk-referencing (download)

View source code for this class

Constructor Summary

Formatter()
Creates a new instance of the formatter with the default symbols, no syntax coloring and the default indentation.

Formatter(int indentation)
Creates a new instance of the formatter with the default symbols, no syntax coloring and the given indentation.

Formatter(Symbols symbols, Colors colors, int indentation)
Creates a new instance of the formatter with the specified indentation.

Method Summary

void	append(CodeList<?> code) Appends a code list.
void	append(double number) Appends a floating point number.
void	append(Formattable formattable) Appends the given Formattable object.
void	append(GeneralParameterValue parameter) Appends a parameter in WKT form.
void	append(IdentifiedObject info) Appends the specified OpenGIS's IdentifiedObject object.
void	append(long number) Appends an integer number.
void	append(MathTransform transform) Appends the specified math transform.
void	append(String text) Appends a character string.
void	append(Unit<?> unit) Appends a unit in WKT form.
void	clear() Clears this formatter.
Unit<Angle>	getAngularUnit() The angular unit for formatting measures, or null for the "natural" unit of each WKT element.
Convention	getConvention() Returns the convention to use for formatting the WKT.
Identifier	getIdentifier(IdentifiedObject info) Returns the preferred identifier for the specified object.
Unit<Length>	getLinearUnit() The linear unit for formatting measures, or null for the "natural" unit of each WKT element.
String	getName(IdentifiedObject info) Returns the preferred name for the specified object.
boolean	isInvalidWKT() Returns true if the WKT in this formatter is not strictly compliant to the WKT specification.
void	setAngularUnit(Unit<Angle> unit) Sets the angular unit for formatting measures.
void	setInvalidWKT(Class<?> unformattable) Set a flag marking the current WKT as not strictly compliant to the WKT specification.
void	setLinearUnit(Unit<Length> unit) Sets the unit for formatting linear measures.
String	toString() Returns the WKT in its current state.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Formatter

public Formatter()

Creates a new instance of the formatter with the default symbols, no syntax coloring and the default indentation.

Formatter

public Formatter(int indentation)

Creates a new instance of the formatter with the default symbols, no syntax coloring and the given indentation.

Parameters:

indentation - The amount of spaces to use in indentation for WKT formatting, or -1 for formatting the whole WKT on a single line.

Since:

3.20

Formatter

public Formatter(Symbols symbols,
                 Colors colors,
                 int indentation)

Creates a new instance of the formatter with the specified indentation. The WKT can be formatted on many lines, and the indentation will have the value specified to this constructor. If the specified indentation is -1, then the whole WKT will be formatted on a single line.

Parameters:

symbols - The symbols.

colors - The syntax coloring, or null if none.

indentation - The amount of spaces to use in indentation for WKT formatting, or -1 for formatting the whole WKT on a single line.

Since:

3.00

Method Detail

append

public void append(Formattable formattable)

Appends the given Formattable object. This method will automatically append the keyword (e.g. "GEOCS"), the name and the authority code, and will invokes formattable.formatWKT(this) for completing the inner part of the WKT.

Parameters:

formattable - The formattable object to append to the WKT.

append

public void append(IdentifiedObject info)

Appends the specified OpenGIS's IdentifiedObject object.

Parameters:

info - The info object to append to the WKT.

append

public void append(MathTransform transform)

Appends the specified math transform.

Parameters:

transform - The transform object to append to the WKT.

append

public void append(CodeList<?> code)

Appends a code list.

Parameters:

code - The code list to append to the WKT.

append

public void append(GeneralParameterValue parameter)

Appends a parameter in WKT form. If the supplied parameter is actually a parameter group, all contained parameters will flattened in a single list.

Parameters:

parameter - The parameter to append to the WKT.

append

public void append(long number)

Appends an integer number. A comma (or any other 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 a floating point number. A comma (or any other element separator) will be written before the number if needed.

Parameters:

number - The floating point value to append to the WKT.

append

public void append(Unit<?> unit)

Appends a unit in WKT form. For example append(SI.KILO(SI.METRE)) will append "UNIT["km", 1000]" to the WKT.

Parameters:

unit - The unit to append to the WKT.

append

public void append(String text)

Appends a character string. The string will be written between quotes. A comma (or any other element separator) will be written before the string if needed.

Parameters:

text - The string to format to the WKT.

getIdentifier

public Identifier getIdentifier(IdentifiedObject info)

Returns the preferred identifier for the specified object. If the specified object contains an identifier from the preferred authority (usually Open Geospatial), then this identifier is returned. Otherwise, the first identifier is returned. If the specified object contains no identifier, then this method returns null.

Parameters:

info - The object to looks for a preferred identifier.

Returns:

The preferred identifier, or null if none.

Since:

2.3

getName

public String getName(IdentifiedObject info)

Returns the preferred name for the specified object. If the specified object contains a name from the preferred authority (usually Open Geospatial), then this name is returned. Otherwise, the first name found is returned.

The preferred authority can be set by the WKTFormat.setAuthority(Citation) method. This is not necessarily the authority of the given object name.

Example: The EPSG name of the EPSG:6326 datum is "World Geodetic System 1984". However if the preferred authority is OGC (which is the case by default), then this method usually returns "WGS84" (the exact string to be returned depends on the list of declared aliases).

Parameters:

info - The object to looks for a preferred name.

Returns:

The preferred name, or null if the given object has no name.

See Also:

WKTFormat.getAuthority(), IdentifiedObjects.getName(IdentifiedObject, Citation)

getLinearUnit

public Unit<Length> getLinearUnit()

The linear unit for formatting measures, or null for the "natural" unit of each WKT element.

Returns:

The unit for linear measurement. Default value is null.

setLinearUnit

public void setLinearUnit(Unit<Length> unit)
                   throws IllegalArgumentException

Sets the unit for formatting linear measures.

Parameters:

unit - The new unit, or null.

Throws:

IllegalArgumentException - If the given unit is not null and not a linear unit.

getAngularUnit

public Unit<Angle> getAngularUnit()

The angular unit for formatting measures, or null for the "natural" unit of each WKT element. This value is set for example when parsing the "GEOGCS" element, in which case the enclosed "PRIMEM" element shall use the unit of the enclosing "GEOGCS".

Returns:

The unit for angle measurement. Default value is null.

setAngularUnit

public void setAngularUnit(Unit<Angle> unit)
                    throws IllegalArgumentException

Sets the angular unit for formatting measures.

Parameters:

unit - The new unit, or null.

Throws:

IllegalArgumentException - If the given unit is not null and not an angular unit.

getConvention

public Convention getConvention()

Returns the convention to use for formatting the WKT. The default convention is OGC. A different convention will usually result in different parameter names, but may also change the WKT syntax.

Returns:

The convention (never null).

Since:

3.20

See Also:

WKTFormat.setConvention(Convention), FormattableObject.toWKT(Convention, int)

isInvalidWKT

public boolean isInvalidWKT()

Returns true if the WKT in this formatter is not strictly compliant to the WKT specification. This method returns true if setInvalidWKT(java.lang.Class) 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, while FormattableObject.toWKT() requires strict WKT formatting and will thrown an exception if this flag is set.

Returns:

true if the WKT is invalid.

setInvalidWKT

public void setInvalidWKT(Class<?> unformattable)

Set a flag marking the current WKT as not strictly compliant to the WKT specification. This method is invoked by FormattableObject.formatWKT(Formatter) methods when the object to format is more complex than what the WKT specification allows. For example this method is invoked when an engineering CRS uses different unit for each axis, An application can tests isInvalidWKT() later for checking WKT validity.

Parameters:

unformattable - The type of the component that can't be formatted, for example EngineeringCRS.

Since:

2.4

See Also:

UnformattableObjectException.getUnformattableClass()

toString

public String toString()

Returns the WKT in its current state.

Overrides:

toString in class Object

clear

public void clear()

Clears this formatter. All properties (including unit and WKT validity flag are reset to their default value. After this method call, this Formatter object is ready for formatting a new object.