org.geotoolkit.io.wkt
Class WKTFormat

Object
  Format
      WKTFormat

All Implemented Interfaces:

Serializable, Cloneable

public class WKTFormat
extends Format

Parser and formatter for Well Known Text (WKT) objects. This format handles a pair of Parser and Formatter, to be used by parse and format methods respectively.

WKTFormat objects allow the following configuration:

• The symbols to use (curly braces or brackets, etc.)
• The preferred authority of object name to format (see Formatter.getName(IdentifiedObject) for more information)
• Whatever ANSI X3.64 colors are allowed or not (default is not)
• The indentation

String expansion
Because the strings to be parsed by this class are long and tend to contain repetitive substrings, WKTFormat provides a mechanism for performing string substitutions before the parsing take place. Long strings can be assigned short names by calls to the definitions().put(key,value) method. After definitions have been added, any call to a parsing method will replace all occurrences of a short name by the associated long string.

The short names must comply with the rules of Java identifiers. It is recommended, but not required, to prefix the names by some symbol like "$" in order to avoid ambiguity. Note however that this class doesn't replace occurrences between quoted text, so string expansion still relatively safe even when used with non-prefixed identifiers.

In the example below, the $WGS84 substring which appear in the argument given to the parseObject method will be expanded into the full GEOGCS["WGS84", ...] string before the parsing proceed.

definitions().put("$WGS84", "GEOGCS[\"WGS84\", DATUM[ ...etc... ]]);
Object crs = parseObject("PROJCS[\"Mercator_1SP\", $WGS84, PROJECTION[ ...etc... ]]");

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

Since:

3.00

Version:

3.00

Author:

Martin Desruisseaux (IRD, Geomatys), Rémi Eve (IRD)

See Also:

Serialized Form

Module:

referencing/geotk-referencing (download)

View source code for this class

Nested Class Summary

Nested classes/interfaces inherited from class Format

Format.Field

Constructor Summary

WKTFormat()
Constructs a format using the default factories.

WKTFormat(Hints hints)
Constructs a format using the given factories for creating parsed objects.

Method Summary

Map<String,String>	definitions() Returns a map of short identifiers to substitute by WKT string before parsing.
StringBuffer	format(Object object, StringBuffer toAppendTo, FieldPosition pos) Formats the specified object as a Well Know Text.
Citation	getAuthority() Returns the preferred authority for formatting WKT entities.
static Class<?>	getClassOf(String element) Returns the class of the specified WKT element.
Colors	getColors() Returns the set of colors to use for syntax coloring, or null if none.
int	getIndentation() Returns the current indentation to be used for formatting objects.
static String	getNameOf(Class<?> type) Returns the WKT name of the specified object type.
Symbols	getSymbols() Returns the symbols used for parsing and formatting WKT.
String	getWarning() If a warning occurred during the last WKT formatting, returns the warning.
<T> T	parse(String text, int offset, Class<T> type) Parses the specified text and ensures that the resulting object is of the specified type.
Object	parseObject(String text) Parses the specified Well Know Text (WKT).
Object	parseObject(String text, ParsePosition position) Parses the specified Well Know Text starting at the specified position.
void	printDefinitions(Writer out) Prints to the specified stream a table of all definitions.
void	reformat(Reader in, Writer out, PrintWriter err) Reads WKT strings from an input stream and reformats them to the specified output stream.
void	setAuthority(Citation authority) Sets the preferred authority for formatting WKT entities.
void	setColors(Colors colors) Sets the colors to use for syntax coloring on ANSI X3.64 (aka ECMA-48 and ISO/IEC 6429) compatible terminal.
void	setIndentation(int indentation) Sets a new indentation to be used for formatting objects.
void	setSymbols(Symbols symbols) Sets the symbols used for parsing and formatting WKT.

Methods inherited from class Format

clone, format, formatToCharacterIterator

Methods inherited from class Object

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

Constructor Detail

WKTFormat

public WKTFormat()

Constructs a format using the default factories.

WKTFormat

public WKTFormat(Hints hints)

Constructs a format using the given factories for creating parsed objects.

Parameters:

hints - The hints to be used for fetching the factories, or null for the system-wide default hints.

Method Detail

getSymbols

public Symbols getSymbols()

Returns the symbols used for parsing and formatting WKT.

Returns:

The current set of symbols used for parsing and formatting WKT.

setSymbols

public void setSymbols(Symbols symbols)

Sets the symbols used for parsing and formatting WKT.

Parameters:

symbols - The new set of symbols to use for parsing and formatting WKT.

getColors

public Colors getColors()

Returns the set of colors to use for syntax coloring, or null if none. If non-null, the set of colors are escape sequences for ANSI X3.64 (aka ECMA-48 and ISO/IEC 6429) compatible terminal. By default there is no syntax coloring.

Returns:

The set of colors for syntax coloring, or null if none.

setColors

public void setColors(Colors colors)

Sets the colors to use for syntax coloring on ANSI X3.64 (aka ECMA-48 and ISO/IEC 6429) compatible terminal. This apply only when formatting text.

Newly created WKTFormat have no syntax coloring. If the DEFAULT set of colors is given to this method, then the format method tries to highlight most of the elements that are relevant to CRS.equalsIgnoreMetadata(java.lang.Object, java.lang.Object).

Parameters:

colors - The set of colors for syntax coloring, or null if none.

getAuthority

public Citation getAuthority()

Returns the preferred authority for formatting WKT entities. The format method will use the name specified by this authority, if available. See the Formatter javadoc for more information.

Returns:

The expected authority.

See Also:

Formatter.getName(IdentifiedObject)

setAuthority

public void setAuthority(Citation authority)

Sets the preferred authority for formatting WKT entities. The format method will use the name specified by this authority, if available. See the Formatter javadoc for more information.

Parameters:

authority - The new authority.

See Also:

Formatter.getName(IdentifiedObject)

getIndentation

public int getIndentation()

Returns the current indentation to be used for formatting objects. The 0 value means that the whole WKT is to be formatted on a single line.

Returns:

The current indentation.

setIndentation

public void setIndentation(int indentation)

Sets a new indentation to be used for formatting objects. The 0 value means that the whole WKT is to be formatted on a single line.

Parameters:

indentation - The new indentation to use.

definitions

public Map<String,String> definitions()

Returns a map of short identifiers to substitute by WKT string before parsing. See the "String expansion" section in class javadoc for details.

Entries added in the definitions map will have immediate effect in this WKTFormat object. They must obey the following constraints:

• Keys must be valid identifiers according Java rules.
• Values must be valid WKT strings - they will be parsed.

Any attempt to put an illegal key or value in the definitions map will result in an IllegalArgumentException being thrown.

Returns:

A live map of (identifiers, WKT) entries.

printDefinitions

public void printDefinitions(Writer out)
                      throws IOException

Prints to the specified stream a table of all definitions. The table content is inferred from the values added to the definitions map. This method does nothing if the definitions map is empty.

Parameters:

out - writer The output stream where to write the table.

Throws:

IOException - if an error occurred while writing to the output stream.

parse

public <T> T parse(String text,
                   int offset,
                   Class<T> type)
        throws ParseException

Parses the specified text and ensures that the resulting object is of the specified type. If the given text is a valid identifier and this identifier was registered in the definitions map, then the associated object will be returned. Otherwise the given text is parsed as a WKT.

Type Parameters:

T - The expected type of the object to be parsed.

Parameters:

text - The WKT to parse, or an identifier given to the definitions map.

offset - The index of the first character to parse in the given text. This information is explicitly given instead than expecting the caller to compute text.substring(offset) in order to provide more accurate error offset in case of ParseException.

type - The expected type of the object to be parsed (usually a CoordinateReferenceSystem.class or MathTransform.class).

Returns:

The parsed object.

Throws:

ParseException - if the string can't be parsed.

parseObject

public Object parseObject(String text)
                   throws ParseException

Parses the specified Well Know Text (WKT). The default implementation delegates the work to parse(text, 0, Object.class).

Overrides:

parseObject in class Format

Parameters:

text - The text to be parsed.

Returns:

The parsed object.

Throws:

ParseException - if the string can't be parsed.

parseObject

public Object parseObject(String text,
                          ParsePosition position)

Parses the specified Well Know Text starting at the specified position. The default implementation delegates the work to parseObject(wkt.substring(position.getIndex())).

Note: The other way around (parseObject(String) invoking parseObject(String,ParsePosition) as in the default Format implementation) is not pratical in the context of WKTFormat. Among other problems, it doesn't provide any accurate error message.

Specified by:

parseObject in class Format

Parameters:

text - The text to parse.

position - The index of the first character to parse.

Returns:

The parsed object, or null in case of failure.

format

public StringBuffer format(Object object,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

Formats the specified object as a Well Know Text. Formatting will uses the same set of symbols than the one used for parsing.

Specified by:

format in class Format

Parameters:

object - The object to format.

toAppendTo - Where the text is to be appended.

pos - An identification of a field in the formatted text.

See Also:

getWarning()

reformat

public void reformat(Reader in,
                     Writer out,
                     PrintWriter err)
              throws IOException

Reads WKT strings from an input stream and reformats them to the specified output stream. WKT strings are read until the the end-of-stream, or until an unparsable WKT has been hit. In this later case, an error message is formatted to the specified error stream.

This method is useful for changing the indentation, rewriting the WKT using parameter names specified by a different authority, for adding syntax coloring, expanding the WKT strings according the definitions, etc.

Parameters:

in - The input stream.

out - The output stream.

err - The error stream.

Throws:

IOException - if an error occurred while reading from the input stream or writing to the output stream.

getWarning

public String getWarning()

If a warning occurred during the last WKT formatting, returns the warning. Otherwise returns null. The warning is cleared every time a new object is formatted.

Returns:

The last warning, or null if none.

getClassOf

public static Class<?> getClassOf(String element)

Returns the class of the specified WKT element. For example this method returns ProjectedCRS.class for element "PROJCS".

This method is the converse of getNameOf(java.lang.Class).

Parameters:

element - The WKT element name.

Returns:

The GeoAPI class of the specified element, or null if unknown.

getNameOf

public static String getNameOf(Class<?> type)

Returns the WKT name of the specified object type. For example this method returns "PROJCS" for type ProjectedCRS.class.

This method is the converse of getClassOf(java.lang.String).

Parameters:

type - The GeoAPI class of the specified element.

Returns:

The WKT element name, or null if unknown.