Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## edu.uky.kcr.recordlinkage.engine
Class AbstractLinkageEngine

    java.lang.Object
      edu.uky.kcr.recordlinkage.engine.AbstractLinkageEngine

All Implemented Interfaces:
  LinkageEngine

Direct Known Subclasses:
  ExactMatchLinkageEngine

    public abstract class AbstractLinkageEngine

extends java.lang.Object
implements LinkageEngine

This class provides the most convenient way to create a `LinkageEngine` implementation.

It provides the following features to implementers:

- Implementers focus on implementing a single method that gets called for every secondary record, `getLinkageMatches(LinkageDataSource, DataSourceRecord)`.
- Unblocked records are calculated automatically as a preprocessing step and are accessible through the `getPrimaryUnblocked()` and `getSecondaryUnblocked()` methods.
- A `LinkageResultSet` is created automatically from the returned `LinkageMatch` objects in the `getLinkageMatches(LinkageDataSource, DataSourceRecord)` call.
- The `LinkageConfiguration` object is available from its getter method.

An implementer will first subclass this class and then implement the `getLinkageMatches(LinkageDataSource, DataSourceRecord)` method to perform a linkage operation, returning a `List` of `LinkageMatch` objects.
A typical lifecycle from the point of view of an `AbstractLinkageEngine` implementation:

1. A `LinkageController` creates an `AbstractLinkageEngine` object by reading the `LinkageConfiguration.getLinkageEngineClassName()` value as a the type of class to instantiate. The `LinkageController` then initializes the engine with the `LinkageConfiguration` object and calls `LinkageEngine.findLinkedRecords(LinkageDataSource, LinkageDataSource)`.
2. The `AbstractLinkageEngine` calls `buildUnblockedLists(LinkageDataSource, LinkageDataSource)` to create the lists of primary and secondary unblocked records from the `BlockingConfiguration` objects in `LinkageConfiguration`.
3. The `AbstractLinkageEngine` then iterates through every unblocked record from the secondary data source and calls `getLinkageMatches(LinkageDataSource, DataSourceRecord)` with that record.
4. An implementer will compare the records in the primary `LinkageDataSource` to the passed-in secondary record and create a list of `LinkageMatch` objects with a valid score for each match.
5. From the returned lists of every call to `getLinkageMatches(LinkageDataSource, DataSourceRecord)`, the `AbstractLinkageEngine` will iterate through the `LinkageMatch` objects and compare their `LinkageMatch.getScore()` value with the `LinkageConfiguration.getPositiveMatchCutoffScore()` and `LinkageConfiguration.getNegativeMatchCutoffScore()` to know whether they are positive or indeterminate matches.
6. Once all secondary records have been considered, the `AbstractLinkageEngine` will return a `LinkageResultSet` with the `LinkageMatch` results.

NOTE: You do not need to define any constructors in your subclass of `AbstractLinkageEngine`, but if you define any, you will need to also define the default constructor that takes no arguments. This requirement is related to the way that the `LinkageController` instantiates `LinkageEngine`s by class name.

Author:
  ihands

Constructor Summary
`AbstractLinkageEngine()`

Method Summary
`LinkageResultSet` | `findLinkedRecords(LinkageDataSource primaryDataSource, LinkageDataSource secondaryDataSource)` Primary workhorse method for a linkage operation, this is where deterministic and probabilistic methods are used to match records.
`LinkageConfiguration` | `getLinkageConfiguration()`
`abstract java.util.List<LinkageMatch>` | `getLinkageMatches(LinkageDataSource primaryDataSource, DataSourceRecord secondaryDataSourceRecord)` This method should be the only method that a LinkageEngine implementer needs to implement.
`java.util.Set<DataSourceRecord>` | `getPrimaryUnblocked()`
`java.util.Set<DataSourceRecord>` | `getSecondaryUnblocked()`
`void` | `initialize(LinkageConfiguration linkageConfiguration)` This method is called immediately after the LinkageEngine is created, before `LinkageEngine.findLinkedRecords(LinkageDataSource, LinkageDataSource)` is called.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface edu.uky.kcr.recordlinkage.engine.LinkageEngine
`getName`

Constructor Detail

### AbstractLinkageEngine

    public AbstractLinkageEngine()

Method Detail

### initialize

    public void initialize(LinkageConfiguration linkageConfiguration)

  Description copied from interface: `LinkageEngine`
  This method is called immediately after the LinkageEngine is created, before `LinkageEngine.findLinkedRecords(LinkageDataSource, LinkageDataSource)` is called.

  Specified by:
    `initialize` in interface `LinkageEngine`
  Parameters:
    `linkageConfiguration` - Configuration object containing the `BlockingConfiguration`, `MatchingConfiguration`, and cutoff scores necessary for a LinkageMatch to be determined by this engine.

### getLinkageConfiguration

    public LinkageConfiguration getLinkageConfiguration()

  Returns:
    `LinkageConfiguration` object that was passed into the `LinkageEngine.initialize(LinkageConfiguration)` method.

### getLinkageMatches

    public abstract java.util.List<LinkageMatch> getLinkageMatches(LinkageDataSource primaryDataSource,
                                                                   DataSourceRecord secondaryDataSourceRecord)
                                                            throws LinkageException

  This method should be the only method that a LinkageEngine implementer needs to implement. It is called after the unblocked lists have been populated so that unblocked records are available through `getPrimaryUnblocked()` and `getSecondaryUnblocked()`. An implementer needs to create `LinkageMatch` objects with a valid score for each record-to-record match from the primaryDataSource to the secondaryDataSourceRecord.

  Parameters:
    `primaryDataSource` - Source of data records to match against the secondary record.
    `secondaryDataSourceRecord` - Single record from the secondary data source that should be scored against the primary records.
  Returns:
    List of `LinkageMatch` objects with a valid score.
  Throws:
    `LinkageException`

### findLinkedRecords

    public LinkageResultSet findLinkedRecords(LinkageDataSource primaryDataSource,
                                              LinkageDataSource secondaryDataSource)
                                       throws LinkageException

  Description copied from interface: `LinkageEngine`
  Primary workhorse method for a linkage operation, this is where deterministic and probabilistic methods are used to match records.

  Specified by:
    `findLinkedRecords` in interface `LinkageEngine`
  Parameters:
    `primaryDataSource` - A source of `DataSourceRecord`s to be linked, typically the larger data set.
    `secondaryDataSource` - A second source of `DataSourceRecord`s to be linked, typically the smaller data set.
  Returns:
    An instance of a LinkageResultSet containing the complete list of positive and indeterminate `LinkageMatch` objects, as well as any unmatched records.
  Throws:
    `LinkageException`

### getPrimaryUnblocked

    public java.util.Set<DataSourceRecord> getPrimaryUnblocked()

  Returns:
    A deduplicated `Set` of `DataSourceRecord` objects from the primary data source that have not been blocked by `BlockingConfiguration` objects in the `LinkageConfiguration`.

### getSecondaryUnblocked

    public java.util.Set<DataSourceRecord> getSecondaryUnblocked()

  Returns:
    A deduplicated `Set` of `DataSourceRecord` objects from the secondary data source that have not been blocked by `BlockingConfiguration` objects in the `LinkageConfiguration`.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD