File Release Notes
File gedcom4j-2.3.1.jar

v2.3.1 of gedcom4j further improved performance and reduced memory consumption.

  • Issue 106: File parsing and loading into object model is now done line by line on-the-fly, rather than loading the entire file into memory, then parsing the lines of the file.
  • Issue 108: There is now a global options class named Options, in which you can choose whether collections in the object model should be automatically initialized (thus saving you from having to do null checks) or left null (thus saving memory). The getter for each of these collections is overloaded with a getter that takes a boolean argument; when true, the getter will initialize the collection if needed before returning a reference.
File gedcom4j-2.3.0.jar

v2.3.0 of gedcom4j was primarily focused on improving performance for installations with smaller heap sizes and less CPU power available (for whatever reason), including the ability to get progress notification on file load/parse and construct/write operations, as well as introducing the ability to cancel these operations while in progress.

Internally, there was also a change to the AnselReader so that files with lines that exceed the 255 character limit mentioned in the GEDCOM spec continue to be read like they did before, despite the optimizations introduced for this release. AnselReader now uses a fixed-size char array to buffer data rather than a StringBuilder (for performance reasons), but the fixed size of the array introduced problems for lines that exceeded the length of the array. To get around this, the class now internally introduces synthetic CONC tags in long lines during the file read process (as if they had been split properly according to spec), which in most cases get removed during the parse process as strings are concatenated back together (as the CONC tag indicates). Most users won't notice anything has happened, but in case it comes up, there it is.

You may notice that gedcom4j skipped from 2.2.8 to 2.3.0 without a 2.2.9 release. 2.2.9 had snapshots that were built and put in Maven Central, but API-impacting changes were introduced, so 2.2.9 was abandoned as not released, and 2.3.0 was created in keeping with semantic versioning concepts.

The changes to the API are as follows:

  • Exceptions defined in gedcom4j are now all in the org.gedcom4j.exception package, and these are checked exceptions, so you'll probably need to touch up your imports.
  • The GedcomParser now has new methods for registering and unregistering listeners for file read progress and data parsing progress, and to set how frequently your listeners are notified. You can also cancel a load/parse operation in progress using the GedcomParser.cancel() method.
  • The GedcomWriter now has new methods for registering and unregistering listeners for progress updates on constructing string data from GEDCOM data, and for writing the files, and to set how frequently your listeners are notified. You can also cancel a construct/write operation in progress using the GedcomWriter.cancel() method.
  • Several classes were moved to new packages, including some enumerations you might be using (like Encoding) so again, you may need to touch up your imports.
  • Visibility of some classes has also changed (such as the Tag enum), so you may no longer be able to use them.

Issues addressed (see GitHub): #103, #105

File gedcom4j-2.2.8.jar

Fixes an issue where two-digit level numbers were not supported as required by the spec.

File gedcom4j-2.2.7.jar

Performance improvements that make the parser about 20 times faster.

File gedcom4j-2.2.6.jar

This release addresses three issues and an enhancement request.

Two changes involve line breaks embedded within the text value of a tag. The GEDCOM spec directs implementations to split lines using CONT or CONC tags and not to have embedded line-breaks within text strings.

  • The GedcomWriter now properly scans text for line breaks and creates additional CONT lines as the spec requires.
  • Additionally, there is now a new optional switch on the GedcomParser class named strictLineBreaks which relaxes the parser a bit, so when it encounters multi-line text not written with CONT tags, it attempts to parse the file as if it had been written properly with CONT tags (with warnings). Any other lines it cannot treat that way are discarded (also with warnings).
  • This should increase interoperability with reading GEDCOM files written by systems that do not adhere to the spec.


  • Unicode files with byte order marks now load properly and do not throw an exception during parsing.
  • The Individual.getDescendants() method now properly recurses through multiple generations.
  • File gedcom4j-2.2.5.jar

    This release addresses two bugs:

    • Issue 95 was a bug where custom tags were being emitted twice by the GedcomWriter class.
    • Issue 96 was another bug where the GedcomParser class would throw an exception when a root-level NOTE line in the GEDCOM had an XREF definition and text that looked like a cross-reference to another NOTE. The fixed code treats the text as literal text now, and adds a warning to the GedcomParser.warnings collection (since it's most likely a mistake, and not really what the specs call for).
    File gedcom4j-2.2.4.jar

    This release addresses two bugs. The first (Issue 88) is an issue in the default String representation of an individual, where it would not show the death date correctly if the individual also had a birth date. The second (Issue 89) is an issue where custom tags in the data structure were not being emitted by the GedcomWriter.

    File gedcom4j-2.2.3.jar

    This release addresses a situation where a malformed GEDCOM file can cause parsing exceptions that could be handled more gracefully. The specific situation is when a tag of a given level (say a 1 MARR tag) is followed by a line but skips a tag level (e.g., 3 NOTE) without the intervening number (here the level 2 tag is missing). Rather than throwing a GedcomParserException and failing to load anything, the code now notes an error in the GedcomParser's errors collection, ignores the misnumbered tag, and continues. See Issue 87 for more details.

    File gedcom4j-2.2.2.jar

    This release fixes issue #81, where the parser and writer were incorrectly processing combining diacritics.

    File gedcom4j-2.2.1.jar

    This release fixes issue #80, where the parser and writer were using an incorrect tag definition for latitudes in map coordinates.