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 class for all NMEA 0183 sentence parsers. Contains generic methods such as data field setters and getters, data formatting, validation etc.

NMEA 0183 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 comma separated data fields, optional checksum and a carriage return/line feed terminator (CR/LF). Sentence may contain up to 82 characters including the CR/LF. If data for certain field is not available, the field value 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 Revealed by Eric S. Raymond.

This class can also be used to implement and integrate parsers not provided by in the library. See SentenceFactory for more instructions.

Author:

Kimmo Tuukkanen

Field Summary

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

ALTERNATIVE_BEGIN_CHAR, BEGIN_CHAR, CHECKSUM_DELIMITER, FIELD_DELIMITER, MAX_LENGTH, TERMINATOR

Constructor Summary

protected	SentenceParser(char begin, TalkerId talker, String type, int size) Creates a new empty sentence with specified begin character, talker and sentence IDs.
	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)
char	getBeginChar() Get the sentence begin character.
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.
void	reset() Resets the sentence contents, i.e. removes all existing values from data fields.
void	setBeginChar(char ch) Set the sentence begin character.
protected void	setCharValue(int index, char value) Set a character in specified field.
protected void	setDegreesValue(int index, double deg) Set degrees value, e.g. course or heading.
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	setFieldCount(int size) Sets the number of sentence data fields.
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.
String	toSentence(int maxLength) Formats and validates the sentence like Sentence.toSentence(), but checks also that resulting String does not exceed specified length.
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(char begin,
                         TalkerId talker,
                         String type,
                         int size)

Creates a new empty sentence with specified begin character, talker and sentence IDs.

Parameters:

begin - The begin character, e.g. '$' or '!'

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

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

size - Number of data fields

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

getBeginChar

public final char getBeginChar()

Description copied from interface: Sentence

Get the sentence begin character. Although most of the sentences start with '$', some of them use '!' as begin character.

Specified by:

getBeginChar in interface Sentence

Returns:

Sentence begin char, e.g. "$" or "!".

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.

reset

public final void reset()

Description copied from interface: Sentence

Resets the sentence contents, i.e. removes all existing values from data fields. After resetting, address field remains as is and checksum is calculated according to empty data fields.

Specified by:

reset in interface Sentence

setBeginChar

public void setBeginChar(char ch)

Description copied from interface: Sentence

Set the sentence begin character. Although most of the sentences start with '$', some of them use '!' as begin character.

Specified by:

setBeginChar in interface Sentence

Parameters:

ch - Sentence begin char to set ('$' or '!')

See Also:

Sentence.BEGIN_CHAR, Sentence.ALTERNATIVE_BEGIN_CHAR

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. Throws an exception if result is not considered a valid sentence. As validation is done by SentenceValidator, notice that resulting sentence length is not checked. To also validate the length, use Sentence.toSentence(int).

Specified by:

toSentence in interface Sentence

Returns:

Sentence as String, equal to toString().

See Also:

Sentence.toString()

toSentence

public final String toSentence(int maxLength)

Description copied from interface: Sentence

Formats and validates the sentence like Sentence.toSentence(), but checks also that resulting String does not exceed specified length.

Specified by:

toSentence in interface Sentence

Returns:

Sentence as String, equal to toString().

See Also:

Sentence.toSentence(), Sentence.MAX_LENGTH

toString

public String toString()

Description copied from interface: Sentence

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 Sentence.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

setDegreesValue

protected final void setDegreesValue(int index,
                                     double deg)

Set degrees value, e.g. course or heading.

Parameters:

index - Field index where to insert value

deg - The degrees value to set

Throws:

IllegalArgumentException - If degrees value out of range [0..360]

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)

setFieldCount

protected final void setFieldCount(int size)

Sets the number of sentence data fields. Increases or decreases the fields array, values in fields not affected by the change remain unchanged. Does nothing if specified new size is equal to count returned by getFieldCount().

Parameters:

size - Number of data fields, must be greater than zero.

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