net.sf.marineapi.nmea.parser
Class SentenceParser

java.lang.Object
  net.sf.marineapi.nmea.parser.SentenceParser

All Implemented Interfaces:

Sentence

public class SentenceParser
extends Object
implements Sentence

Base sentence parser for all NMEA sentence types. Provides general services such as sentence validation and data field setters and getters with formatting.

NMEA data is transmitted in form of ASCII Strings that are called sentences. Each sentence starts with a '$', a two letter talker ID, a three letter sentence ID, followed by a number of data fields separated by commas, and terminated by an optional checksum, and a carriage return/line feed. A sentence may contain up to 82 characters including the '$' and CR/LF. If data for a field is not available, the field is simply omitted, but the commas that would delimit it are still sent, with no space between them.

Sentence structure:
$<id>,<field #0>,<field #1>,...,<field #n>*<checksum>(CR/LF)

For more details, see NMEA FAQ by Peter Bennett or NMEA Revealed by Eric S. Raymond. Java Marine API is based mostly on these documents.

Version:

$Revision: 100 $

Author:

Kimmo Tuukkanen

Field Summary

Fields inherited from interface net.sf.marineapi.nmea.sentence.Sentence

ADDRESS_FIELD, BEGIN_CHAR, CHECKSUM_DELIMITER, FIELD_DELIMITER, MAX_LENGTH, TERMINATOR

Constructor Summary

	SentenceParser(String nmea) Creates a new instance of SentenceParser.
protected	SentenceParser(String nmea, String type) Creates a new instance of SentenceParser.
protected	SentenceParser(TalkerId talker, String type, int size) Creates a new empty sentence with specified talker and sentence IDs.

Method Summary

boolean	equals(Object obj)
protected char	getCharValue(int index) Parse a single character from the specified sentence field.
protected double	getDoubleValue(int index) Parse double value from the specified sentence field.
int	getFieldCount() Returns the current number of data fields in sentence, excluding ID field and checksum.
protected int	getIntValue(int index) Parse integer value from the specified sentence field.
String	getSentenceId() Get the sentence ID that specifies the sentence type and data it holds.
protected String	getStringValue(int index) Get contents of a data field as a String.
TalkerId	getTalkerId() Gets the talker ID of the sentence.
int	hashCode()
protected boolean	hasValue(int index) Tells is if the field specified by the given index contains a value.
boolean	isProprietary() Tells if the sentence is of proprietary format.
boolean	isValid() Tells if the sentence formatting matches NMEA 0183 format.
protected void	setCharValue(int index, char value) Set a character in specified field.
protected void	setDoubleValue(int index, double value) Set double value in specified field.
protected void	setDoubleValue(int index, double value, int leading, int decimals) Set double value in specified field, with given number of digits before and after the decimal separator ('.').
protected void	setIntValue(int index, int value) Set integer value in specified field.
protected void	setIntValue(int index, int value, int leading) Set integer value in specified field, with specified minimum number of digits.
protected void	setStringValue(int index, String value) Set String value in specified data field.
protected void	setStringValues(int first, String[] newFields) Replace multiple fields with given String array, starting at the specified index.
void	setTalkerId(TalkerId id) Set the talker ID of the sentence.
String	toSentence() Formats and validates the String representation of sentence without the line terminator CR/LF.
String	toString() Returns the String representation of the sentence (without line terminator CR/LR).

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SentenceParser

public SentenceParser(String nmea)

Creates a new instance of SentenceParser. Validates the input String and resolves talker id and sentence type.

Parameters:

nmea - A valid NMEA 0183 sentence

Throws:

IllegalArgumentException - If the specified sentence is invalid or if sentence type is not supported.

SentenceParser

protected SentenceParser(String nmea,
                         String type)

Creates a new instance of SentenceParser. Parser may be constructed only if parameter nmea contains a valid NMEA 0183 sentence of the specified type.

For example, GGA sentence parser should specify "GGA" as the type.

Parameters:

nmea - NMEA 0183 sentence String

type - Expected type of the sentence in nmea parameter

Throws:

IllegalArgumentException - If the specified sentence is not a valid or is not of expected type.

SentenceParser

protected SentenceParser(TalkerId talker,
                         String type,
                         int size)

Creates a new empty sentence with specified talker and sentence IDs.

Parameters:

talker - Talker type Id, e.g. "GP" or "LC".

type - Sentence type Id, e.g. "GGA or "GLL".

size - Number of data fields

Method Detail

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

getFieldCount

public final int getFieldCount()

Description copied from interface: Sentence

Returns the current number of data fields in sentence, excluding ID field and checksum.

Specified by:

getFieldCount in interface Sentence

Returns:

Data field count

getSentenceId

public final String getSentenceId()

Description copied from interface: Sentence

Get the sentence ID that specifies the sentence type and data it holds. ID is the last three characters in address field. For example, in case of $GPGGA the method returns SentenceId.GGA.

Specified by:

getSentenceId in interface Sentence

Returns:

Sentence id String, e.g. "GLL" or "GGA".

See Also:

SentenceId

getTalkerId

public final TalkerId getTalkerId()

Description copied from interface: Sentence

Gets the talker ID of the sentence. Talker ID is the next two characters after $ in sentence address field. For example, in case of $GPGGA, the method returns TalkerId.GP.

Specified by:

getTalkerId in interface Sentence

Returns:

Talker id enum.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

isProprietary

public boolean isProprietary()

Description copied from interface: Sentence

Tells if the sentence is of proprietary format.

Specified by:

isProprietary in interface Sentence

Returns:

True if proprietary, otherwise false.

isValid

public boolean isValid()

Description copied from interface: Sentence

Tells if the sentence formatting matches NMEA 0183 format.

Specified by:

isValid in interface Sentence

Returns:

True if validly formatted, otherwise false.

setTalkerId

public final void setTalkerId(TalkerId id)

Description copied from interface: Sentence

Set the talker ID of the sentence. Typically, the ID might be changed if the sentence is to be sent from a computer to an NMEA device.

Specified by:

setTalkerId in interface Sentence

Parameters:

id - TalkerId to set

toSentence

public final String toSentence()

Description copied from interface: Sentence

Formats and validates the String representation of sentence without the line terminator CR/LF. If formatting results in invalid sentence, e.g. 82 character limit exceeds due too long values set in fields, an exception is thrown.

Specified by:

toSentence in interface Sentence

Returns:

A valid NMEA sentence String

See Also:

Sentence.toString()

toString

public String toString()

Returns the String representation of the sentence (without line terminator CR/LR). Checksum is calculated and appended at the end of the sentence, but no validation is done. Use toSentence() to also validate the result.

Specified by:

toString in interface Sentence

Overrides:

toString in class Object

Returns:

String representation of sentence

getCharValue

protected final char getCharValue(int index)

Parse a single character from the specified sentence field.

Parameters:

index - Data field index in sentence

Returns:

Character contained in the field

Throws:

ParseException - If field contains more than one character

getDoubleValue

protected final double getDoubleValue(int index)

Parse double value from the specified sentence field.

Parameters:

index - Data field index in sentence

Returns:

Field as parsed by Double.parseDouble(String)

getIntValue

protected final int getIntValue(int index)

Parse integer value from the specified sentence field.

Parameters:

index - Field index in sentence

Returns:

Field parsed by Integer.parseInt(String)

getStringValue

protected final String getStringValue(int index)

Get contents of a data field as a String. Field indexing is zero-based. The address field (e.g. $GPGGA) and checksum at the end are not considered as a data fields and cannot therefore be fetched with this method.

Field indexing, let i = 1:
$<id>,<i>,<i+1>,<i+2>,...,<i+n>*<checksum>

Parameters:

index - Field index

Returns:

Field value as String

Throws:

DataNotAvailableException - If the field is empty

hasValue

protected final boolean hasValue(int index)

Tells is if the field specified by the given index contains a value.

Parameters:

index - Field index

Returns:

True if field contains value, otherwise false.

setCharValue

protected final void setCharValue(int index,
                                  char value)

Set a character in specified field.

Parameters:

index - Field index

value - Value to set

setDoubleValue

protected final void setDoubleValue(int index,
                                    double value)

Set double value in specified field. Value is set "as-is" without any formatting or rounding.

Parameters:

index - Field index

value - Value to set

See Also:

setDoubleValue(int, double, int, int)

setDoubleValue

protected final void setDoubleValue(int index,
                                    double value,
                                    int leading,
                                    int decimals)

Set double value in specified field, with given number of digits before and after the decimal separator ('.'). When necessary, the value is padded with leading zeros and/or rounded to meet the requested number of digits.

Parameters:

index - Field index

value - Value to set

leading - Number of digits before decimal separator

decimals - Maximum number of digits after decimal separator

See Also:

setDoubleValue(int, double)

setIntValue

protected final void setIntValue(int index,
                                 int value)

Set integer value in specified field.

Parameters:

index - Field index

value - Value to set

setIntValue

protected final void setIntValue(int index,
                                 int value,
                                 int leading)

Set integer value in specified field, with specified minimum number of digits. Leading zeros are added to value if when necessary.

Parameters:

index - Field index

value - Value to set

leading - Number of digits to use.

setStringValue

protected final void setStringValue(int index,
                                    String value)

Set String value in specified data field.

Parameters:

index - Field index

value - String to set, null converts to empty String.

setStringValues

protected final void setStringValues(int first,
                                     String[] newFields)

Replace multiple fields with given String array, starting at the specified index. If parameter first is zero, all sentence fields are replaced.

If the length of newFields does not fit in the sentence field count or it contains less values, fields are removed or added accordingly. As the result, total number of fields may increase or decrease. Thus, if the sentence field count must not change, you may need to add empty Strings to newFields in order to preserve the original number of fields. Also, all existing values after first are lost.

Parameters:

first - Index of first field to set

newFields - Array of Strings to set