gedcomx-java

Welcome

This project hosts the Java implementation of the GEDCOM X project and serves as the reference implementation of GEDCOM X. The modules of this project each address specific aspects of the GEDCOM X Specification Set, including:

• Readers and writers for the GEDCOM X XML Serialization Format.
• Readers and writers for the GEDCOM X JSON Serialization Format.
• Readers and writers for the GEDCOM X File Format.
• Client-side libraries for reading and writing a GEDCOM X Web service API that conforms to the GEDCOM X RS Specification.

Reading and Writing XML and JSON

The gedcomx-model subproject provides Java classes that correspond to the data types defined by the GEDCOM X Conceptual Model. These classes are instrumented such that they can be used to read and write both XML and JSON.

For more information about reading and writing GEDCOM X XML and JSON, see the gedcomx-model module.

GEDCOM X Web Services

The gedcomx-rs-client module provides support for reading from and writing to a GEDCOM X Web service API that conforms to the GEDCOM X RS Specification.

GEDCOM X File Format

The gedcomx-fileformat subproject provides support for reading and writing the GEDCOM X File Format.

GEDCOM X Extensions

The extensions module provides a place for extensions to GEDCOM X. FamilySearch has defined a set of extensions to the GEDCOM X Conceptual Model and to the GEDCOM X RS specification that comprise the definition of the FamilySearch API.

The FamilySearch API Client comprises the developer SDK for the FamilySearch API.

Use

Here's how you might use this project.

Maven Repositories

The GEDCOM X Java artifacts are provided via a Maven repository structure. Most Java-based build systems (Ant, Maven, Gradle, etc.) have support for Maven repositories.

Here's some snippets of what the dependency declarations might look like in some of the most common build systems. Note that these snippets declare a dependency on the gedcomx-model artifact, but you may want to declare dependencies on gedcomx-fileformat or gedcomx-rs-client or whatever.

Finding the Latest Version

To find the latest version of the libraries, read the Maven Metadata and use the "release" version.

Maven

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>org.gedcomx</groupId>
      <artifactId>gedcomx-model</artifactId>
      <version>${gedcomx.version}</version>
    </dependency>
    ...
  </dependencies>
  ...
</project>

Apache Ivy

<ivy-module>
...
  <dependencies>
    ...
    <dependency org="org.gedcomx" name="gedcomx-model" rev="${gedcomx.version}"/>
    ...
  </dependencies>
...
</ivy-module>

Gradle

...
dependencies {
  runtime group: 'org.gedcomx', name: 'gedcomx-model', version: gedcomxVersion
}
...

Apache Buildr

...
compile.with transitive('org.gedcomx:gedcomx-model:#{gedcomx-version}')
...

Build

Here's how you build this project from source:

git clone https://github.com/FamilySearch/gedcomx-java.git
cd gedcomx-java
mvn install

The build for this project is automated via Travis CI, which automatically validates any updates to the code. When a release is needed, a Jenkins build server generously hosted by CloudBees is used to perform the release.