Integrating your own parsers & contributing

Although marine-api already provides support for variety of sentences, you may also add additional parsers yourself. Notice that this does not require compiling the whole library and that your parsers do not need to be in net.sf.marineapi namespace - unless you wish to contribute them in marine-api. The preferred way of merging changes in main codebase is forking and creating pull requests.

Here's how:

1. First, study the source code of provided parsers to get a general idea.

2. Define an interface for your sentence by extending net.sf.marineapi.nmea.sentence.Sentence.

3. Implement this interface in a class that extends net.sf.marineapi.nmea.parser.SentenceParser.

4. Write a constructor with single String parameter and pass it to SentenceParser.SentenceParser(String, String) together with expected sentence ID.

5. Write another constructor with net.sf.marineapi.nmea.sentence.TalkerId parameter and pass it to SentenceParser.SentenceParser(TalkerId, String, int) together with sentence ID and sentence field count.

6. Implement the methods required by your sentence interface by using the protected getters and setters in SentenceParser.

7. Register your parser in net.sf.marineapi.nmea.parser.SentenceFactory by using registerParser(String, Class) method. This should be done only once, preferably during the application init phase.

8. net.sf.marineapi.nmea.io.SentenceReader should now dispatch instances of your parser whenever it reads a matching sentence. Also, factory methods createParser(String) and createParser(TalkerId, String) can be used to parse sentences without the reader.

9. If you wish to contribute your code in marine-api, please add unit tests with reasonable coverage under src/test/java, in package net.sf.marineapi.nmea.parser.