net.sf.marineapi.nmea.parser

Class SentenceFactory

java.lang.Object

net.sf.marineapi.nmea.parser.SentenceFactory

public final class SentenceFactory
extends Object

Factory for creating sentence parsers.

Custom parsers may be implemented and registered in factory as follows:

1. Define a sentence interface by extending the Sentence interface (e.g. com.acme.XYZSentence).
2. Implement the interface in a class that extends SentenceParser, (e.g. com.acme.XYZParser).
3. Use the protected getters and setters in SentenceParser to read and write sentence data.
4. Add a constructor in XYZParser with String parameter, i.e. the sentence to be parsed. Pass this parameter to SentenceParser.SentenceParser(String, String) with expected sentence type (e.g. "XYZ").
5. Add another constructor with TalkerId parameter. Pass this parameter to SentenceParser.SentenceParser(TalkerId, String, int) with sentence type and number of data fields.
6. Register XYZParser in SentenceFactory by using the registerParser(String, Class) method.
7. Use createParser(String) or createParser(TalkerId, String) to obtain an instance of your parser. In addition, SentenceReader will dispatch instances of XYZSentence when "XYZ" sentences are read from data source.

Author:

Kimmo Tuukkanen

Method Summary

Modifier and Type	Method and Description
Sentence	createParser(String nmea) Creates a parser for specified NMEA 0183 sentence String.
Sentence	createParser(TalkerId talker, SentenceId type) Creates a parser for specified talker and sentence type.
Sentence	createParser(TalkerId talker, String type) Creates a parser for specified talker and sentence type.
static SentenceFactory	getInstance() Returns the singleton instance of SentenceFactory.
boolean	hasParser(String type) Tells if the factory is able to create parser for specified sentence type.
List<String>	listParsers() Returns a list of currently parseable sentence types.
void	registerParser(String type, Class<? extends SentenceParser> parser) Register a sentence parser to factory.
void	reset() Resets the factory in it's initial state, i.e. restores and removes all parsers the have been either removed or added.
void	unregisterParser(Class<? extends SentenceParser> parser) Unregisters a parser class, regardless of sentence type(s) it is registered for.

Methods inherited from class java.lang.Object

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

Method Detail

createParser

public Sentence createParser(String nmea)

Creates a parser for specified NMEA 0183 sentence String. The parser implementation is selected from registered parsers according to sentence type. The returned instance must be cast in to correct sentence interface, for which the type should first be checked by using the Sentence.getSentenceId() method.

Parameters:

nmea - NMEA 0183 sentence String

Returns:

Sentence parser instance for specified sentence

Throws:

IllegalArgumentException - If there is no parser registered for the given sentence type

IllegalStateException - If parser is found, but it does not implement expected constructors or is otherwise unusable.

createParser

public Sentence createParser(TalkerId talker,
                             SentenceId type)

Creates a parser for specified talker and sentence type. The returned instance needs to be cast to corresponding sentence interface.

Parameters:

talker - Sentence talker id

type - Sentence type

Returns:

Sentence parser of requested type.

Throws:

IllegalArgumentException - If talker id is null or if there is no parser registered for given sentence type.

IllegalStateException - If parser instantiation fails.

createParser

public Sentence createParser(TalkerId talker,
                             String type)

Creates a parser for specified talker and sentence type. This method is mainly intended to be used when custom parsers have been registered in the factory. The returned instance needs to be cast to corresponding sentence interface.

Parameters:

talker - Talker ID to use in parser

type - Type of the parser to create

Returns:

Sentence parser for requested type

Throws:

IllegalArgumentException - If talker id is null or if there is no parser registered for given sentence type.

IllegalStateException - If parser is found, but it does not implement expected constructors or is otherwise unusable.

hasParser

public boolean hasParser(String type)

Tells if the factory is able to create parser for specified sentence type. All SentenceId enum values should result returning true at all times.

Parameters:

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

Returns:

true if type is supported, otherwise false.

listParsers

public List<String> listParsers()

Returns a list of currently parseable sentence types.

Returns:

List of sentence ids

registerParser

public void registerParser(String type,
                           Class<? extends SentenceParser> parser)

Register a sentence parser to factory. After registration, createParser(String) method can be used to obtain instances of registered parser.

Sentences supported by the library are registered automatically, but they can be overridden simply be registering a new parser implementation for chosen sentence type. That is, each sentence type can have only one parser registered at a time.

Parameters:

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

parser - Class of parser implementation for given type.

unregisterParser

public void unregisterParser(Class<? extends SentenceParser> parser)

Unregisters a parser class, regardless of sentence type(s) it is registered for.

Parameters:

parser - Parser implementation class for type.

See Also:

registerParser(String, Class)

getInstance

public static SentenceFactory getInstance()

Returns the singleton instance of SentenceFactory.

Returns:

SentenceFactory instance

reset

public void reset()

Resets the factory in it's initial state, i.e. restores and removes all parsers the have been either removed or added.