Package org.gedcomx.util

Class FieldMap

  • public class FieldMap
extends Object
    Class for helping to deal with connecting field values with record descriptors for historical records and image browse data. Historical records have both structured data (persons with names, gender, facts; and relationships with facts) and 'fields'. A field often represents what was actually stated within some area of text on a historical document (or what was strongly implied by that document, such as the male gender of a father in a birth record). Each field has a list of field values, which can be of FieldValueType.Original, meaning what the document originally said (or structurally implied); or FieldValueType.Interpreted, meaning that a user or system interpreted. For example, a 'gender' field might have an original field value of "M", which, because it is in a Mexican census, means "Mujer", which means "Female". So the "Interpreted" field value might say "Mujer", or might say "Female"; or it is possible that both are included, since it is a list. These field values will be found within a Field of type "http://gedcomx.org/Gender", and that field will be found inside of the gender inside of the person it applies to. That gender will have a conclusional 'type' (e.g., "http://gedcomx.org/Female") that software will typically use. The 'structured data' of the record is typically used when dealing with what the record 'meant' or in displaying genealogical data to be used in copying over to a conclusion tree. The 'fields' of a record are typically used when display what the record originally 'said', in order to help communicate to a user some of the genealogical nuances that each record can have, including some that don't translate directly into the standardized conclusional structure that GedcomX supports. Having structured data with embedded fields (plus a list of fields at the person, relationship and record level) allows general-purpose genealogical use of 'what the record is telling us' (via the structure) as well as preservation of the special-purpose nuances of a particular record type (via the fields). A GedcomX document that represents a historical record will often have a SourceDescription that has a record 'descriptor' reference, which is the URL of a GedcomX document that represents the Collection that the record is found in, along with a "#" and local id of the record descriptor withing that collection's document, that describes the display labels to be used for displaying a field-value pair view of the record's field data. This class takes two GedcomX documents: a record and its collection (or, equivalently, the DocMap for both) and walks the structure of the record to find all of the field values, and builds the maps necessary to find all the field labelIds, the localized display labels for each labelId, and the values for each labelId found in the record. (Note that because a Field can have multiple FieldValues of the same type (original or interpreted), then each labelId can map to a list of values). Also, Census records are different from other records in that each person in a census household can have the same list of fields, so when displaying field values from census data, it must be done one person at a time. Therefore, each record will either support getValues(labelId) [i.e., for non-census] or getValues(person, labelId) [census], but not both. User: Randy Wilson Date: 7/31/2014 Time: 11:07 AM

    • Constructor Detail

      • FieldMap

        public FieldMap​(Gedcomx record,
                Gedcomx collection)
        Constructor for a collection and record GedcomX document.
        Parameters:
        record - - GedcomX document for a record (which is in the given collection).
        collection - - GedcomX document for a collection (which contains the RecordDescriptor for the record).

      • FieldMap

        public FieldMap​(DocMap recordDocMap,
                DocMap collectionDocMap)
        Constructor using a DocMap for a collection and record. Use this constructor if you've already built a DocMap for the record and/or collection.
        Parameters:
        recordDocMap - - DocMap for a GedcomX document for a record (which is in the given collection)
        collectionDocMap - - DocMap for a GedcomX document for a collection (which contains the RecordDescriptor for the record).

    • Method Detail

      • getCollectionDocMap

        public DocMap getCollectionDocMap()
        Get the DocMap for the collection that the record is found in.
        Returns:
        DocMap for the collection that the record is found in.

      • getRecordDocMap

        public DocMap getRecordDocMap()
        Get the DocMap for the record.
        Returns:
        DocMap for the record.

      • getCollection

        public Gedcomx getCollection()
        Get the GedcomX document for the collection that the record is found in.
        Returns:
        GedcomX document for the collection that the record is found in.

      • getRecord

        public Gedcomx getRecord()
        Get the GedcomX document for the record.
        Returns:
        GedcomX document for the record.

      • getDisplayLabel

        public String getDisplayLabel​(String labelId,
                              String language)
        Get the display label for the given labelId in the closest language available to the one given.
        Parameters:
        labelId - labelId to get the display value for (e.g., "PR_NAME")
        language - Preferred language to get the display label in. If null use "en-US".
        Returns:
        Display label to use for the labelId, or null if there is not one.

      • getValues

        public List<String> getValues​(String labelId)
        Get a list of values that had the given labelId in the record. Must be a non-census record, or else the person must be specified.
        Parameters:
        labelId - - LabelId to get the values for
        Returns:
        List of values for the given labelId, or null if none.

      • getValues

        public List<String> getValues​(Person person,
                              String labelId)
        Get a list of values that had the given labelId in the record for the given person. Must be a census record.
        Parameters:
        person - person to get values for (if null, get record-level values for the given labelId, if any)
        labelId - LabelId to get the values for
        Returns:
        List of values for the given labelId, or null if none.

      • getFieldValueDescriptor

        public FieldValueDescriptor getFieldValueDescriptor​(String labelId)
        Get the FieldValueDescriptor for the given field value label ID.
        Parameters:
        labelId - - Label ID to find the FieldValueDescriptor for.
        Returns:
        FieldValueDescriptor with the given label ID, or null if not found.

      • getPersonLabelValueMap

        public Map<String,​List<String>> getPersonLabelValueMap​(Person person)
        Get a map of labelId to list of values for that labelId for the given person. Used only with census collections.
        Parameters:
        person - - Person to get the map for
        Returns:
        map of labelId to list of values for that labelId for the given person.

      • getLabelValueMap

        public Map<String,​List<String>> getLabelValueMap()
        Get a map of labelId to list of values for that labelId. Used only with non-census collections.
        Returns:
        map of labelId to list of values for that labelId for the given person.

      • getLabelFieldValueDescriptorMap

        public Map<String,​FieldValueDescriptor> getLabelFieldValueDescriptorMap()
        Get the map of labelId to FieldValueDescriptor used by this FieldMap.
        Returns:
        map of labelId to FieldValueDescriptor used by this FieldMap, or null if there were no FieldDescriptors.

      • getRecordDescriptor

        public RecordDescriptor getRecordDescriptor()
        Get the RecordDescriptor that goes with this record.
        Returns:
        RecordDescriptor that goes with this record.

      • getRecordDescriptor

        public static RecordDescriptor getRecordDescriptor​(DocMap collectionDocMap,
                                                   DocMap recordDocMap)
        Find the RecordDescriptor from the collection document that is referenced by the main source description from the record document, i.e., find the record's record descriptor in the collection.
        Parameters:
        collectionDocMap - - DocMap for the collection GedcomX document.
        recordDocMap - - DocMap for the record GedcomX document.
        Returns:
        Record's RecordDescriptor, or null if not found.

      • getLabelFieldValueDescriptorMap

        public static Map<String,​FieldValueDescriptor> getLabelFieldValueDescriptorMap​(RecordDescriptor recordDescriptor)
        Get a map of labelId to FieldValueDescriptor for that label id.
        Parameters:
        recordDescriptor - - RecordDescriptor to build the map from.
        Returns:
        Map of labelId to FieldValueDescriptor, or null if the RecordDescriptor had no fields.

      • getPersonFieldMap

        public static Map<Person,​List<Field>> getPersonFieldMap​(Gedcomx record)
        Get a map of Person to the list of Fields for that person. A 'null' person is also included if there are any record-level fields.
        Parameters:
        record - - record to get field map from
        Returns:
        map of Person (or null for record-level fields) to the list of fields for that person.

      • getAllFields

        public static List<Field> getAllFields​(Gedcomx record)
        Create a list of all of the fields occurring in the given GedcomX record, including those found within the various values. Note that this is a flat list that can't distinguish between the fields with the same label that belong to different persons, so only call when you're sure there will be no duplicates (as with a non-census record or a mapping Template).
        Parameters:
        record - - GedcomX to get fields for.
        Returns:
        list of fields occurring in the GedcomX record.

      • getLabelValuesMap

        public static Map<String,​List<String>> getLabelValuesMap​(List<Field> fields)
        Get a map of labelId to values from all of the FieldValues that appear in the given list of Fields. If two FieldValues have the same labelId, then they are put into the same list.
        Parameters:
        fields - - list of Fields to look in for FieldValues.
        Returns:
        map of labelId to FieldValue values.

      • isCensus

        public static boolean isCensus​(Gedcomx record)
        Tell whether the given record is a Census record, i.e., if it has a SourceDescription with a Coverage with a RecordType of Census.
        Parameters:
        record - - GedcomX record to examine
        Returns:
        true if this is a census record, false otherwise.

      • isCensus

        public static boolean isCensus​(DocMap recordDocMap)
        Tell whether the record with the given DocMap is a Census record, i.e., if it has a SourceDescription with a Coverage with a RecordType of Census.
        Parameters:
        recordDocMap - - DocMap of the GedcomX record to examine
        Returns:
        true if this is a census record, false otherwise.

      • isCensus

        public static boolean isCensus​(SourceDescription sourceDescription)
        Tell whether the given SourceDescription has 'coverage' with a RecordType of census.
        Parameters:
        sourceDescription - - SourceDescription to examine for coverage.
        Returns:
        true if this is a census record, false otherwise.