Skip to content

gedcomx-rs-client

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

gedcomx-rs-client

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
README.md
README.md
 
 
pom.xml
pom.xml
 
 
todo.md
todo.md
 
 

README.md

GEDCOM X Java RS Client

On-going support for this client has been discontinued. New functionality added to the GEDCOM X RS Specification will not be supported. Future changes to the GEDCOM X RS Specification may break this client.
This only pertains to this sub-project. The other sub-projects of gedcomx-java will continue to be supported.

This is a Java library that provides support for consuming a genealogical Web service API that conforms to the GEDCOM X RS Specification.

Coordinates

groupId artifactId
org.gedcomx gedcomx-rs-client

See the section on using these libraries.

Use

Consuming a Web service API that uses hypermedia as the engine of application state feels like browsing the web. As such, the RS client feels like using a screen scraper. The process can generally be summarized as follows:

Step 1: Read the "Home" Collection

Web sites have a "home page". GEDCOM X APIs have a "home collection".

Step 2: Follow the Right Link

You get stuff done on a web site by following links to where you want to go. Ditto for a GEDCOM X API.

Step 3: Repeat

Follow more links to get more stuff done.

Examples

Need something to sink your teeth into?

Read a Collection (Start Here)

Before you do anything, you need to start by reading the collection that you want to read or update. Here's how you might read and authenticate to a collection.

//start with the URI to the collection.
URI collectionUri = URI.create("...");

//read the collection.
CollectionState collection = new CollectionState(collectionUri);

//authenticate if you need to.
String username = "...";
String password = "...";
String clientId = "...";
collection.authenticateViaOAuth2Password(username, password, clientId);

Search for Records or Persons

Once you have a collection, you can search it for records or persons.

//the collection to search. 
CollectionState collection = ...;

//put together a search query
GedcomxPersonSearchQueryBuilder query = new GedcomxPersonSearchQueryBuilder()
  //for a John Smith
  .name("John Smith")
  //born 1/1/1900
  .birthDate("1 January 1900")
    //son of Peter.
  .fatherName("Peter Smith");

//search the collection
PersonSearchResultsState results = collection.searchForPersons(query);

//iterate through the results...
List<Entry> entries = results.getResults().getEntries();

//read the record of one of the results.
RecordState record = results.readRecord(entries.get(0));

//or, read the person that was considered a "hit"
PersonState person = results.readPerson(entries.get(0));

Create a Person

Some collections are designed to hold genealogical data to be updated. Here's how you might add a person to a collection.

//the collection to which the person is to be added
CollectionState collection = ...;

//add a person
PersonState person = collection.addPerson(new Person()
  //named John Smith
  .name("John Smith")
  //male
  .gender(GenderType.Male)
  //residing in chicago in 1940
  .fact(new Fact(FactType.Residence, "4 April 1940", "Chicago, Illinois")));

Create Relationships

Here's how you would create relationships between persons in collections where such an operation is supported.

//the collection to which the relationships are to be added.
CollectionState collection = null;

PersonState spouse1 = null;
PersonState spouse2 = null;
PersonState child = null;

RelationshipState coupleRelationship = collection.addSpouseRelationship(spouse1, spouse2);
RelationshipState childRelationship1 = collection.addParentChildRelationship(spouse1, child);
RelationshipState childRelationship2 = collection.addParentChildRelationship(spouse2, child);

Add a Source

Some collections allow you to add descriptions of sources.

//the collection to which the source is to be added
CollectionState collection = ...;

//add a source description
SourceDescriptionState source = collection.addSourceDescription(new SourceDescription()
  //with a title.
  .title("Birth Certificate for John Smith")
  //and a citation
  .citation("Citation for the birth certificate")
);

Add an Artifact

Some collections allow you to upload artifacts such as digital images.

//the collection to which the artifact is to be added
CollectionState collection = ...;
DataSource digitalImage = new FileDataSource("/path/to/img.jpg");

//add an artifact
SourceDescriptionState artifact = collection.addArtifact(new SourceDescription()
  //with a title
  .title("Death Certificate for John Smith")
  //and a citation
  .citation("Citation for the death certificate"), 
  digitalImage
);

Cite a Record or Artifact or Other Source

How you might update a person to cite a record or artifact or other source.

//the person that will be citing the record, source, or artifact.
PersonState person = ...;

RecordState record = ...;
SourceDescriptionState source = ...;
SourceDescriptionState artifact = ...;

person.addSourceReference(record); //cite the record.
person.addSourceReference(source); //cite the source.
person.addSourceReference(artifact); //cite the artifact.

Extract Information From a Source

Some collections might allow you to extract information about a person (i.e. "persona") from an artifact or other source.

//the artifact from which a persona will be extracted.
SourceDescriptionState artifact = ...;

//add the persona
PersonState persona = artifact.addPersona(new Person()
  //named John Smith
  .name("John Smith")
  //male
  .gender(GenderType.Male)
  //residing in chicago in 1940
  .fact(new Fact(FactType.Residence, "4 April 1940", "Chicago, Illinois")));

Add a Persona Reference

How you might add a reference from a person to a persona.

//the person that will be referencing the persona.
PersonState person = ...;

//the persona that was extracted from a record or artifact.
PersonState persona = ...;

//add the persona reference.
person.addPersonaReference(persona);

Attach a Photo to a Person

Some collections might allow you to add a photo to a person.

//the person to which the photo will be attached.
PersonState person = ...;
DataSource digitalImage = new FileDataSource("/path/to/img.jpg");

//add an artifact
SourceDescriptionState artifact = person.addArtifact(new SourceDescription()
  //with a title
  .title("Portrait of John Smith"), 
  digitalImage
);

Attach a Photo to Multiple Persons

Here's how you would attach a single photo to multiple persons.

//the collection to which the artifact is to be added
CollectionState collection = ...;

//the persons to which the photo will be attached.
PersonState person1 = ...;
PersonState person2 = ...;
PersonState person3 = ...;
DataSource digitalImage = new FileDataSource("/path/to/img.jpg");

//add an artifact
SourceDescriptionState artifact = collection.addArtifact(new SourceDescription()
  //with a title
  .title("Family of John Smith"), 
  digitalImage
);

person1.addMediaReference(artifact); //attach to person1
person2.addMediaReference(artifact); //attach to person2
person3.addMediaReference(artifact); //attach to person3

Read the Person for the Current User

The current authentication user may have a person record in a collection.

//the collection containing the person for the current user.
CollectionState collection = ...;

PersonState person = collection.readPersonForCurrentUser();

Read Source References

//the person on which to read the source references.
PersonState person = null;

//load the source references for the person.
person.loadSourceReferences();

//read the source references.
List<SourceReference> sourceRefs = person.getPerson().getSources();

Read Evidence References

//the person on which to read the persona references.
PersonState person = null;

//load the persona references for the person.
person.loadPersonaReferences();

//read the persona references.
List<EvidenceReference> personaRefs = person.getPerson().getEvidence();

Read Notes

//the person on which to read the notes.
PersonState person = null;

//load the notes for the person.
person.loadNotes();

//read the discussion references.
List<Note> notes = person.getPerson().getNotes();

Read Parents, Spouses, or Children

//the person for which to read the parents, spouses, children
PersonState person = ...;

PersonChildrenState children = person.readChildren(); //read the children
PersonParentsState parents = person.readParents(); //read the parents
PersonSpousesState spouses = person.readSpouses(); //read the spouses

Read Ancestry or Descendancy

Some collections support queries that allows you to read the ancestry or descendancy of a person.

//the person for which to read the ancestry or descendancy
PersonState person = ...;

person.readAncestry(); //read the ancestry
person.readAncestry(generations(8)); //read 8 generations of the ancestry
person.readDescendancy(); //read the descendancy
person.readDescendancy(generations(3)); //read 3 generations of the descendancy

Add a Name, Gender, or Fact

How to add a name, gender, or facts to a person.

//the person to which to add the name, gender, or fact.
PersonState person = ...;

person.addName(new Name("Johnny Smith")); //add name
person.addGender(new Gender(GenderType.Male)); //add gender
person.addFact(new Fact(FactType.Death, "date", "place")); //add death fact

Update a Name, Gender, or Fact

How to update and existing name, gender, or facts of a person.

//the person to which to update the name, gender, or fact.
//the person to which to update the name, gender, or fact.
PersonState person = ...;

Name name = person.getName();
name.getNameForm().setFullText("Joanna Smith");
person.updateName(name); //update name

Gender gender = person.getGender();
gender.setKnownType(GenderType.Female);
person.updateGender(gender); //update gender

Fact death = person.getPerson().getFirstFactOfType(FactType.Death);
death.setDate(new Date().original("new date"));
person.updateFact(death);