Package com.senzing.sdk.core

Class SzCoreEngine

java.lang.Object

com.senzing.sdk.core.SzCoreEngine

All Implemented Interfaces:

SzEngine

public class SzCoreEngine
extends Object
implements SzEngine

The package-protected implementation of SzEngine that works with the SzCoreEnvironment class.

Method Summary

Modifier and Type	Method	Description
String	addRecord(SzRecordKey recordKey, String recordDefinition, Set<SzFlag> flags)	Loads the record described by the specified String record definition having the specified data source code and record ID using the specified Set of SzFlag values.
void	closeExport(long exportHandle)	This function closes an export handle of a previously opened export to clean up system resources.
long	countRedoRecords()	Gets the number of redo records pending to be processed.
String	deleteRecord(SzRecordKey recordKey, Set<SzFlag> flags)	Delete a previously loaded record identified by the data source code and record ID from the specified SzRecordKey.
protected static String	encodeDataSources(Set<String> dataSources)	Encodes the Set of String data source codes as JSON.
protected static String	encodeEntityIds(Set<Long> entityIds)	Encodes the Set of Long entity ID's as JSON.
protected static String	encodeRecordKeys(Set<SzRecordKey> recordKeys)	Encodes the Set of SzRecordKey instances as JSON.
long	exportCsvEntityReport(String csvColumnList, Set<SzFlag> flags)	Initiates an export of entity data in CSV format and returns an "export handle" that can be used to read the export data and must be closed when complete.
long	exportJsonEntityReport(Set<SzFlag> flags)	Iniitiates an export of entity data as JSON-lines format and returns an "export handle" that can be used to read the export data and must be closed when complete.
String	fetchNext(long exportHandle)	Fetches the next line of entity data from the export identified by the specified export handle.
String	findNetwork(SzEntityIds entityIds, int maxDegrees, int buildOutDegrees, int buildOutMaxEntities, Set<SzFlag> flags)	Finds a network of entity relationships surrounding the paths between a set of entities identified by one or more entity ID's specified in an instance of SzEntityIds -- which is a Set of non-null Long entity ID's.
String	findNetwork(SzRecordKeys recordKeys, int maxDegrees, int buildOutDegrees, int buildOutMaxEntities, Set<SzFlag> flags)	Finds a network of entity relationships surrounding the paths between a set of entities having the constituent records identified by the data source code and record ID pairs contained in the specified instance of SzRecordKeys -- which is a Set of one or more non-null SzRecordKey instances.
String	findPath(long startEntityId, long endEntityId, int maxDegrees, SzEntityIds avoidEntityIds, Set<String> requiredDataSources, Set<SzFlag> flags)	Finds a relationship path between two entities identified by their entity ID's.
String	findPath(SzRecordKey startRecordKey, SzRecordKey endRecordKey, int maxDegrees, SzRecordKeys avoidRecordKeys, Set<String> requiredDataSources, Set<SzFlag> flags)	Finds a relationship path between two entities identified by the data source codes and record ID's of their constituent records given by the specified start and end SzRecordKey instances.
String	getEntity(long entityId, Set<SzFlag> flags)	This method is used to retrieve information about a specific resolved entity.
String	getEntity(SzRecordKey recordKey, Set<SzFlag> flags)	This method is used to retrieve information about the resolved entity that contains a specific record that is identified by the data source code and record ID associated with the specified SzRecordKey.
String	getRecord(SzRecordKey recordKey, Set<SzFlag> flags)	Retrieves the record identified by the data source code and record ID from the specified SzRecordKey.
String	getRedoRecord()	Retrieves a pending redo record from the reevaluation queue.
String	getStats()	Returns the current internal engine workload statistics for the process.
String	getVirtualEntity(Set<SzRecordKey> recordKeys, Set<SzFlag> flags)	Describes a hypothetically entity that would be composed of the one or more records identified by the data source code and record ID pairs in the specified Set of SzRecordKey instances.
String	howEntity(long entityId, Set<SzFlag> flags)	Deterimes how an entity identified by the specified entity ID was constructed from its constituent records.
protected boolean	isDestroyed()	Checks if this instance has been destroyed by the associated SzCoreEnvironment.
String	preprocessRecord(String recordDefinition, Set<SzFlag> flags)	Performs a hypothetical load of a the record described by the specified String record definition using the specified Set of SzFlag values.
void	primeEngine()	May optionally be called to pre-initialize some of the heavier weight internal resources of the SzEngine.
String	processRedoRecord(String redoRecord, Set<SzFlag> flags)	Processes the specified redo record using the specified flags.
String	reevaluateEntity(long entityId, Set<SzFlag> flags)	Reevaluate a resolved entity identified by the specified entity ID.
String	reevaluateRecord(SzRecordKey recordKey, Set<SzFlag> flags)	Reevaluate the record identified by the data source code and record ID from the specified SzRecordKey.
String	searchByAttributes(String attributes, String searchProfile, Set<SzFlag> flags)	This method searches for entities that match or relate to the provided search attributes using the optionally specified search profile.
String	searchByAttributes(String attributes, Set<SzFlag> flags)	This method is equivalent to calling SzEngine.searchByAttributes(String, String, Set) with a null value for the search profile parameter.
String	whyEntities(long entityId1, long entityId2, Set<SzFlag> flags)	Determines the ways in which two entities identified by the specified entity ID's are related to each other.
String	whyRecordInEntity(SzRecordKey recordKey, Set<SzFlag> flags)	Determines why the record identified by the data source code and record ID in the specified in an SzRecordKey is included in its respective entity.
String	whyRecords(SzRecordKey recordKey1, SzRecordKey recordKey2, Set<SzFlag> flags)	Determines ways in which two records identified by the data source code and record ID pairs from the specified SzRecordKey instances are related to each other.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

isDestroyed

protected boolean isDestroyed()

Checks if this instance has been destroyed by the associated SzCoreEnvironment.

Returns:

true if this instance has been destroyed, otherwise false.

addRecord

public String addRecord(SzRecordKey recordKey,
 String recordDefinition,
 Set<SzFlag> flags)
                 throws SzUnknownDataSourceException,
SzBadInputException,
SzException

Loads the record described by the specified String record definition having the specified data source code and record ID using the specified Set of SzFlag values. If a record already exists with the same data source code and record ID, then it will be replaced.

The specified JSON data may optionally contain the DATA_SOURCE and RECORD_ID properties, but, if so, they must match the specified parameters.

The specified Set of SzFlag instances may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_MODIFY group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

addRecord in interface SzEngine

Parameters:

recordKey - The non-null SzRecordKey that specifies the data source code and record ID of the record being added.

recordDefinition - The String that defines the record, typically in JSON format.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_MODIFY group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS. Specify SzFlag.SZ_WITH_INFO_FLAGS for an INFO response.

Returns:

The JSON String result produced by adding the record to the repository (depending on the specified flags).

Throws:

SzUnknownDataSourceException - If an unrecognized data source code is specified.

SzBadInputException - If the specified record definition has a data source or record ID value that conflicts with the specified data source code and/or record ID values.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_WITH_INFO_FLAGS
• SzFlagUsageGroup.SZ_MODIFY

preprocessRecord

public String preprocessRecord(String recordDefinition,
 Set<SzFlag> flags)
                        throws SzException

Performs a hypothetical load of a the record described by the specified String record definition using the specified Set of SzFlag values.

The specified Set of SzFlag instances may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_RECORD group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

preprocessRecord in interface SzEngine

Parameters:

recordDefinition - The String that defines the record, typically in JSON format.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_RECORD group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_RECORD_DEFAULT_FLAGS.

Returns:

The JSON String result produced by preprocessing the record (depending on the specified flags).

Throws:

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_ENTITY_INCLUDE_INTERNAL_FEATURES
• SzFlag.SZ_ENTITY_INCLUDE_RECORD_FEATURE_DETAILS
• SzFlag.SZ_ENTITY_INCLUDE_RECORD_FEATURE_STATS
• SzFlagUsageGroup.SZ_RECORD

closeExport

public void closeExport(long exportHandle)
                 throws SzException

This function closes an export handle of a previously opened export to clean up system resources. This function is idempotent and may be called for an export that has already been closed.

Implemented to call the underlying native API.

Specified by:

closeExport in interface SzEngine

Parameters:

exportHandle - The export handle of the export to close.

Throws:

SzException - If a failure occurs.

See Also:

• SzEngine.exportCsvEntityReport(String, Set)
• SzEngine.exportJsonEntityReport(Set)
• SzEngine.fetchNext(long)

countRedoRecords

public long countRedoRecords()
                      throws SzException

Gets the number of redo records pending to be processed.

Implemented to call the underlying native API.

Specified by:

countRedoRecords in interface SzEngine

Returns:

The number of redo records pending to be processed.

Throws:

SzException - If a failure occurs.

See Also:

• SzEngine.processRedoRecord(String, Set)
• SzEngine.getRedoRecord()

deleteRecord

public String deleteRecord(SzRecordKey recordKey,
 Set<SzFlag> flags)
                    throws SzUnknownDataSourceException,
SzException

Delete a previously loaded record identified by the data source code and record ID from the specified SzRecordKey. This method is idempotent, meaning multiple calls this method with the same method will all succeed regardless of whether or not the record is found in the repository.

The specified Set of SzFlag instances may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_MODIFY group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

deleteRecord in interface SzEngine

Parameters:

recordKey - The non-null SzRecordKey that specifies the data source code and record Id of the record to delete.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_MODIFY group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS. Specify SzFlag.SZ_WITH_INFO_FLAGS for an INFO response.

Returns:

The JSON String result produced by deleting the record from the repository (depending on the specified flags).

Throws:

SzUnknownDataSourceException - If an unrecognized data source code is specified.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_WITH_INFO_FLAGS
• SzFlagUsageGroup.SZ_MODIFY

exportCsvEntityReport

public long exportCsvEntityReport(String csvColumnList,
 Set<SzFlag> flags)
                           throws SzException

Initiates an export of entity data in CSV format and returns an "export handle" that can be used to read the export data and must be closed when complete. The first exported line contains the CSV header and each subsequent line contains the exported entity data for a single resolved entity.

Implemented to call the underlying native API.

Specified by:

exportCsvEntityReport in interface SzEngine

Parameters:

csvColumnList - Specify "*" to indicate "all columns", specify empty-string to indicate the "standard columns", otherwise specify a comma-sepatated list of column names.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_EXPORT group to control how the operation is performed and the content of the export, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_EXPORT_DEFAULT_FLAGS for the default recommended flags.

Returns:

The export handle to use for retrieving the export data.

Throws:

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_EXPORT_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_EXPORT
• SzEngine.fetchNext(long)
• SzEngine.closeExport(long)
• SzEngine.exportJsonEntityReport(Set)

exportJsonEntityReport

public long exportJsonEntityReport(Set<SzFlag> flags)
                            throws SzException

Iniitiates an export of entity data as JSON-lines format and returns an "export handle" that can be used to read the export data and must be closed when complete. Each output line contains the exported entity data for a single resolved entity.

The optionally specified Set of SzFlag instances that not only control how the operation is performed but also the level of detail provided for the entity and record being analyzed. The Set may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_EXPORT group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

exportJsonEntityReport in interface SzEngine

Parameters:

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_EXPORT group to control how the operation is performed and the content of the export, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_EXPORT_DEFAULT_FLAGS for the default recommended flags.

Returns:

The export handle to use for retrieving the export data.

Throws:

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_EXPORT_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_EXPORT
• SzEngine.fetchNext(long)
• SzEngine.closeExport(long)
• SzEngine.exportCsvEntityReport(String, Set)

fetchNext

public String fetchNext(long exportHandle)
                 throws SzException

Fetches the next line of entity data from the export identified by the specified export handle. The specified export handle can be obtained from SzEngine.exportJsonEntityReport(Set) or SzEngine.exportCsvEntityReport(String, Set).

Implemented to call the underlying native API.

Specified by:

fetchNext in interface SzEngine

Parameters:

exportHandle - The export handle to identify the export from which to retrieve the next line of data.

Returns:

The next line of export data whose format depends on which function was used to initiate the export, or null if there is no more data to be exported via the specified handle.

Throws:

SzException - If a failure occurs.

See Also:

• SzEngine.exportCsvEntityReport(String, Set)
• SzEngine.exportJsonEntityReport(Set)
• SzEngine.closeExport(long)

encodeEntityIds

protected static String encodeEntityIds(Set<Long> entityIds)

Encodes the Set of Long entity ID's as JSON. The JSON is formatted as:

   {
     "ENTITIES": [
        { "ENTITY_ID": <entity_id1> },
        { "ENTITY_ID": <entity_id2> },
        . . .
        { "ENTITY_ID": <entity_idN> }
     ]
   }
 

Parameters:

entityIds - The non-null Set of non-null Long entity ID's.

Returns:

The encoded JSON string of entity ID's.

encodeRecordKeys

protected static String encodeRecordKeys(Set<SzRecordKey> recordKeys)

Encodes the Set of SzRecordKey instances as JSON. The JSON is formatted as:

   {
     "RECORDS": [
        {
          "DATA_SOURCE": "<data_source1>",
          "RECORD_ID":  "<record_id1>"
        },
        {
          "DATA_SOURCE": "<data_source2>",
          "RECORD_ID":  "<record_id2>"
        },
        . . .
        {
          "DATA_SOURCE": "<data_sourceN>",
          "RECORD_ID":  "<record_idN>"
        }
     ]
   }
 

Parameters:

recordKeys - The non-null Set of non-null SzRecordKey instances.

Returns:

The encoded JSON string of record keys.

encodeDataSources

protected static String encodeDataSources(Set<String> dataSources)

Encodes the Set of String data source codes as JSON. The JSON is formatted as:

    { "DATA_SOURCES": [
        "<data_source_code1>",
        "<data_source_code2>",
        . . .
        "<data_source_codeN>"
      ]
    }
 

Parameters:

dataSources - The Set of String data source codes.

Returns:

The encoded JSON string of record keys.

findNetwork

public String findNetwork(SzEntityIds entityIds,
 int maxDegrees,
 int buildOutDegrees,
 int buildOutMaxEntities,
 Set<SzFlag> flags)
                   throws SzNotFoundException,
SzException

Finds a network of entity relationships surrounding the paths between a set of entities identified by one or more entity ID's specified in an instance of SzEntityIds -- which is a Set of non-null Long entity ID's.

Additionally, the maximum degrees of separation for the paths between entities must be specified so as to prevent the network growing beyond the desired size. Further, a non-zero number of degrees to build out the network may be specified to find other related entities. If build out is specified, it can be limited to a maximum total number of build-out entities for the whole network.

The optionally specified Set of SzFlag instances not only control how the operation is performed but also the level of detail provided for the network and the entities on the network. The Set may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_FIND_NETWORK group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

findNetwork in interface SzEngine

Parameters:

entityIds - The SzEntityIds describing the Set of non-null Long entity ID's identifying the entities for which to build the network.

maxDegrees - The maximum number of degrees for the path search between the specified entities.

buildOutDegrees - The number of relationship degrees to build out from each of the found entities on the network, or zero to prevent network build-out.

buildOutMaxEntities - The maximum number of entities to build out for the entire network.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_FIND_NETWORK group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_FIND_NETWORK_DEFAULT_FLAGS for the default recommended flags.

Returns:

The JSON String describing the resultant entity network and the entities on the network.

Throws:

SzNotFoundException - If any of the entities for the specified entity ID's cannot be found.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_FIND_NETWORK_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_FIND_NETWORK
• SzEngine.findNetwork(SzRecordKeys,int,int,int,Set)

findNetwork

public String findNetwork(SzRecordKeys recordKeys,
 int maxDegrees,
 int buildOutDegrees,
 int buildOutMaxEntities,
 Set<SzFlag> flags)
                   throws SzUnknownDataSourceException,
SzNotFoundException,
SzException

Finds a network of entity relationships surrounding the paths between a set of entities having the constituent records identified by the data source code and record ID pairs contained in the specified instance of SzRecordKeys -- which is a Set of one or more non-null SzRecordKey instances.

Additionally, the maximum degrees of separation for the paths between entities must be specified so as to prevent the network growing beyond the desired size. Further, a non-zero number of degrees to build out the network may be specified to find other related entities. If build out is specified, it can be limited to a maximum total number of build-out entities for the whole network.

The optionally specified Set of SzFlag instances not only control how the operation is performed but also the level of detail provided for the network and the entities on the network. The Set may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_FIND_NETWORK group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

findNetwork in interface SzEngine

Parameters:

recordKeys - The SzRecordKeys describing the Set of non-null SzRecordKey instances providing the data source code and record ID pairs for the consituent records of the entities for which to build the network.

maxDegrees - The maximum number of degrees for the path search between the specified entities.

buildOutDegrees - The number of relationship degrees to build out from each of the found entities on the network, or zero to prevent network build-out.

buildOutMaxEntities - The maximum number of entities to build out for the entire network.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_FIND_NETWORK group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_FIND_NETWORK_DEFAULT_FLAGS for the default recommended flags.

Returns:

The JSON String describing the resultant entity network and the entities on the network.

Throws:

SzUnknownDataSourceException - If an unrecognized data source code is specified.

SzNotFoundException - If any of the records for the specified data source code and record ID pairs cannot be found.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_FIND_NETWORK_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_FIND_NETWORK
• SzEngine.findNetwork(SzEntityIds,int,int,int,Set)

findPath

public String findPath(long startEntityId,
 long endEntityId,
 int maxDegrees,
 SzEntityIds avoidEntityIds,
 Set<String> requiredDataSources,
 Set<SzFlag> flags)
                throws SzNotFoundException,
SzUnknownDataSourceException,
SzException

Finds a relationship path between two entities identified by their entity ID's.

Entities to be avoided when finding the path may optionally be specified as a non-null SzEntityIds instance describing a Set of Long entity ID's. If specified as non-null, then the avoidance SzEntityIds contains the non-null Long entity ID's that identify entities to be avoided. By default the specified entities will be avoided unless absolutely neccessary to find the path. To strictly avoid the specified entities specify the SzFlag.SZ_FIND_PATH_STRICT_AVOID flag.

Further, a JSON required data sources Set of String data source codes may optionally be specified. If specified as non-null, then the required data sources Set contains non-null String data source codes that identify data sources for which a record from at least one must exist on the path.

The optionally specified Set of SzFlag instances not only control how the operation is performed but also the level of detail provided for the path and the entities on the path. The Set may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_FIND_PATH group will be recognized (other SzFlag instance will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

findPath in interface SzEngine

Parameters:

startEntityId - The entity ID of the first entity.

endEntityId - The entity ID of the second entity.

maxDegrees - The maximum number of degrees for the path search.

avoidEntityIds - The optional SzEntityIds describing the Set of non-null Long entity ID's identifying entities to be avoided when finding the path, or null if no entities identified by are to be avoided.

requiredDataSources - The optional Set of non-null String data source codes identifying the data sources for which at least one record must be included on the path, or null if none are required.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_FIND_PATH group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_FIND_PATH_DEFAULT_FLAGS for the default recommended flags.

Returns:

The JSON String describing the resultant entity path which may be an empty path if no path exists between the two entities given the path parameters.

Throws:

SzNotFoundException - If either the path-start or path-end entities for the specified entity ID's cannot be found.

SzUnknownDataSourceException - If an unrecognized required data source is specified.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_FIND_PATH_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_FIND_PATH
• SzEngine.findPath(SzRecordKey,SzRecordKey,int,SzRecordKeys,Set,Set)

findPath

public String findPath(SzRecordKey startRecordKey,
 SzRecordKey endRecordKey,
 int maxDegrees,
 SzRecordKeys avoidRecordKeys,
 Set<String> requiredDataSources,
 Set<SzFlag> flags)
                throws SzNotFoundException,
SzUnknownDataSourceException,
SzException

Finds a relationship path between two entities identified by the data source codes and record ID's of their constituent records given by the specified start and end SzRecordKey instances.

Entities to be avoided when finding the path may be optionally specified as a non-null SzRecordKeys describing a Set of SzRecordKey instances. If specified as non-null, then the avoidance SzRecordKeys contains the non-null SzRecordKey instances providing the data source code and record ID pairs that identify the constituent records of entities to be avoided. By default the associated entities will be avoided unless absolutely neccessary to find the path. To strictly avoid the associated entities specify the SzFlag.SZ_FIND_PATH_STRICT_AVOID flag.

Further, a JSON required data sources Set of String data source codes may optionally be specified. If specified as non-null, then the required data sources Set contains non-null String data source codes that identify data sources for which a record from at least one must exist on the path.

The optionally specified Set of SzFlag instances not only control how the operation is performed but also the level of detail provided for the path and the entities on the path. The Set may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_FIND_PATH group will be recognized (other SzFlag instance will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

findPath in interface SzEngine

Parameters:

startRecordKey - The SzRecordKey containing the data source code and record ID identifying the record at the start of the path.

endRecordKey - The SzRecordKey containing the data source code and record ID identifying the record at the end of the path.

maxDegrees - The maximum number of degrees for the path search.

avoidRecordKeys - The optional SzRecordKeys describing the Set of non-null SzRecordKey instances providing the data source code and record ID pairs of the records whose entities are to be avoided when finding the path, or null if no entities identified by are to be avoided.

requiredDataSources - The optional Set of non-null String data source codes identifying the data sources for which at least one record must be included on the path, or null if none are required.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_FIND_PATH group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_FIND_PATH_DEFAULT_FLAGS for the default recommended flags.

Returns:

The JSON String describing the resultant entity path which may be an empty path if no path exists between the two entities given the path parameters.

Throws:

SzNotFoundException - If either the path-start or path-end records for the specified data source code and record ID pairs cannot be found.

SzUnknownDataSourceException - If an unrecognized data source code is specified.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_FIND_PATH_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_FIND_PATH
• SzEngine.findPath(long,long,int,SzEntityIds,Set,Set)

getEntity

public String getEntity(long entityId,
 Set<SzFlag> flags)
                 throws SzNotFoundException,
SzException

This method is used to retrieve information about a specific resolved entity. The result is returned as a JSON document describing the entity. The level of detail provided for the entity depends upon the specified Set of SzFlag instances.

The specified Set of SzFlag instances may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_ENTITY group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

getEntity in interface SzEngine

Parameters:

entityId - The entity ID identifying the entity to retrieve.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_ENTITY group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_ENTITY_DEFAULT_FLAGS for the default recommended flags.

Returns:

The JSON String describing the entity.

Throws:

SzNotFoundException - If no enitty could be found with the specified entity ID.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_ENTITY_DEFAULT_FLAGS
• SzFlag.SZ_ENTITY_BRIEF_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_ENTITY

getEntity

public String getEntity(SzRecordKey recordKey,
 Set<SzFlag> flags)
                 throws SzUnknownDataSourceException,
SzNotFoundException,
SzException

This method is used to retrieve information about the resolved entity that contains a specific record that is identified by the data source code and record ID associated with the specified SzRecordKey. The result is returned as a JSON document describing the entity. The level of detail provided for the entity depends upon the specified Set of SzFlag instances.

The specified Set of SzFlag instances may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_ENTITY group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

getEntity in interface SzEngine

Parameters:

recordKey - The non-null SzRecordKey that specifies the data source code and record Id of the consituent record for the entity to retrieve.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_ENTITY group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_ENTITY_DEFAULT_FLAGS for the default recommended flags.

Returns:

The JSON String describing the entity.

Throws:

SzUnknownDataSourceException - If an unrecognized data source code is specified.

SzNotFoundException - If no enitty could be found with the specified entity ID.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_ENTITY_DEFAULT_FLAGS
• SzFlag.SZ_ENTITY_BRIEF_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_ENTITY

getRecord

public String getRecord(SzRecordKey recordKey,
 Set<SzFlag> flags)
                 throws SzUnknownDataSourceException,
SzNotFoundException,
SzException

Retrieves the record identified by the data source code and record ID from the specified SzRecordKey.

The optionally specified Set of SzFlag instances that not only control how the operation is performed but also the level of detail provided for the entity and record being analyzed. The Set may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_RECORD group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

getRecord in interface SzEngine

Parameters:

recordKey - The non-null SzRecordKey providing the data source code and record ID that identify the record to retrieve.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_RECORD group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_RECORD_DEFAULT_FLAGS for the default recommended flags.

Returns:

The JSON String describing the record.

Throws:

SzUnknownDataSourceException - If an unrecognized data source code is specified.

SzNotFoundException - If the record for the specified data source code and record ID pairs cannot be found.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_RECORD_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_RECORD

getRedoRecord

public String getRedoRecord()
                     throws SzException

Retrieves a pending redo record from the reevaluation queue. If no redo records are availbale then this returns an null.

Implemented to call the underlying native API.

Specified by:

getRedoRecord in interface SzEngine

Returns:

The retrieved redo record or null if there were no pending redo records.

Throws:

SzException - If a failure occurs.

See Also:

• SzEngine.processRedoRecord(String, Set)
• SzEngine.countRedoRecords()

getStats

public String getStats()
                throws SzException

Returns the current internal engine workload statistics for the process. The counters are reset after each call.

Implemented to call the underlying native API.

Specified by:

getStats in interface SzEngine

Returns:

The String describing the statistics as JSON.

Throws:

SzException - If a failure occurs.

getVirtualEntity

public String getVirtualEntity(Set<SzRecordKey> recordKeys,
 Set<SzFlag> flags)
                        throws SzNotFoundException,
SzException

Describes a hypothetically entity that would be composed of the one or more records identified by the data source code and record ID pairs in the specified Set of SzRecordKey instances.

The optionally specified Set of SzFlag instances that not only control how the operation is performed but also the level of detail provided for the entity and record being analyzed. The Set may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_VIRTUAL_ENTITY group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

getVirtualEntity in interface SzEngine

Parameters:

recordKeys - The non-null non-empty Set of non-null SzRecordKey instances that identify the records to use to build the virtual entity.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_VIRTUAL_ENTITY group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_VIRTUAL_ENTITY_DEFAULT_FLAGS for the default recommended flags.

Returns:

The JSON String describing the virtual entity having the specified constituent records.

Throws:

SzNotFoundException - If any of the records for the specified data source code and record ID pairs cannot be found.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_HOW_ENTITY_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_HOW
• SzEngine.howEntity(long, Set)

howEntity

public String howEntity(long entityId,
 Set<SzFlag> flags)
                 throws SzNotFoundException,
SzException

Deterimes how an entity identified by the specified entity ID was constructed from its constituent records.

The optionally specified Set of SzFlag instances that not only control how the operation is performed but also the level of detail provided for the entity and record being analyzed. The Set may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_HOW group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

howEntity in interface SzEngine

Parameters:

entityId - The entity ID of the entity.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_HOW group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_HOW_ENTITY_DEFAULT_FLAGS for the default recommended flags.

Returns:

The JSON String describing the how the entity was constructed.

Throws:

SzNotFoundException - If the entity for the specified entity ID could not be found.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_HOW_ENTITY_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_HOW
• SzEngine.getVirtualEntity(Set, Set)

primeEngine

public void primeEngine()
                 throws SzException

May optionally be called to pre-initialize some of the heavier weight internal resources of the SzEngine.

Implemented to call the underlying native API.

Specified by:

primeEngine in interface SzEngine

Throws:

SzException - If a failure occurs.

processRedoRecord

public String processRedoRecord(String redoRecord,
 Set<SzFlag> flags)
                         throws SzException

Processes the specified redo record using the specified flags. The redo record can be retrieved from SzEngine.getRedoRecord().

The optionally specified Set of SzFlag instances that not only control how the operation is performed but also the level of detail provided for the entity and record being analyzed. The Set may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_MODIFY group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

processRedoRecord in interface SzEngine

Parameters:

redoRecord - The redorecord to be processed.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_MODIFY group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS. Specify SzFlag.SZ_WITH_INFO_FLAGS for an INFO response.

Returns:

The JSON String result produced by adding the record to the repository (depending on the specified flags).

Throws:

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_WITH_INFO_FLAGS
• SzFlagUsageGroup.SZ_MODIFY
• SzEngine.getRedoRecord()
• SzEngine.countRedoRecords()

reevaluateEntity

public String reevaluateEntity(long entityId,
 Set<SzFlag> flags)
                        throws SzException

Reevaluate a resolved entity identified by the specified entity ID. If the entity is not found then this method does nothing.

If the entity for the entity ID is not found, then the operation silently does nothing with no exception. This is to ensure consistent behavior in case of a race condition with entity re-resolve or unresolve. To ensure that the entity was found, specify the SzFlag.SZ_WITH_INFO flag and check the returned INFO document for affected entities.

The specified Set of SzFlag instances may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_MODIFY group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

reevaluateEntity in interface SzEngine

Parameters:

entityId - The ID of the resolved entity to reevaluate.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_MODIFY group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS. Specify SzFlag.SZ_WITH_INFO_FLAGS for an INFO response.

Returns:

The JSON String result produced by reevaluating the entity in the repository (depending on the specified flags).

Throws:

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_WITH_INFO_FLAGS
• SzFlagUsageGroup.SZ_MODIFY

reevaluateRecord

public String reevaluateRecord(SzRecordKey recordKey,
 Set<SzFlag> flags)
                        throws SzUnknownDataSourceException,
SzException

Reevaluate the record identified by the data source code and record ID from the specified SzRecordKey.

If the data source code is not recognized then an SzUnknownDataSourceException is thrown but if the record for the record ID is not found, then the operation silently does nothing with no exception. This is to ensure consistent behavior in case of a race condition with record deletion. To ensure that the record was found, specify the SzFlag.SZ_WITH_INFO flag and check the returned INFO document for affected entities.

The specified Set of SzFlag instances may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_MODIFY group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

reevaluateRecord in interface SzEngine

Parameters:

recordKey - The non-null SzRecordKey that specifies the data source code and record Id of the record to reevaluate.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_MODIFY group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS. Specify SzFlag.SZ_WITH_INFO_FLAGS for an INFO response.

Returns:

The JSON String result produced by reevaluating the record in the repository (depending on the specified flags).

Throws:

SzUnknownDataSourceException - If an unrecognized data source code is specified.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_WITH_INFO_FLAGS
• SzFlagUsageGroup.SZ_MODIFY

searchByAttributes

public String searchByAttributes(String attributes,
 String searchProfile,
 Set<SzFlag> flags)
                          throws SzException

This method searches for entities that match or relate to the provided search attributes using the optionally specified search profile. The specified search attributes are treated as a hypothetical record and the search results are those entities that would match or relate to that hypothetical record on some level (depending on the specified flags).

If the specified search profile is null then the default generic thresholds from the default search profile will be used for the search (alternatively, use SzEngine.searchByAttributes(String, Set) to omit the parameter). If your search requires different behavior using alternate generic thresholds, please contact support@senzing.com for details on configuring a custom search profile.

The specified Set of SzFlag instances may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_SEARCH group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

searchByAttributes in interface SzEngine

Parameters:

attributes - The search attributes defining the hypothetical record to match and/or relate to in order to obtain the search results.

searchProfile - The optional search profile identifier, or null if the default search profile should be used for the search.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_SEARCH group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS for the default recommended flags.

Returns:

The resulting JSON String describing the result of the search.

Throws:

SzException - If a failure occurs.

See Also:

• SzEngine.searchByAttributes(String, Set)
• SzFlag.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS
• SzFlag.SZ_SEARCH_BY_ATTRIBUTES_ALL
• SzFlag.SZ_SEARCH_BY_ATTRIBUTES_STRONG
• SzFlag.SZ_SEARCH_BY_ATTRIBUTES_MINIMAL_ALL
• SzFlag.SZ_SEARCH_BY_ATTRIBUTES_MINIMAL_STRONG
• SzFlagUsageGroup.SZ_SEARCH

searchByAttributes

public String searchByAttributes(String attributes,
 Set<SzFlag> flags)
                          throws SzException

This method is equivalent to calling SzEngine.searchByAttributes(String, String, Set) with a null value for the search profile parameter. See SzEngine.searchByAttributes(String, String, Set) documentation for details.

Implemented to call the underlying native API.

Specified by:

searchByAttributes in interface SzEngine

Parameters:

attributes - The search attributes defining the hypothetical record to match and/or relate to in order to obtain the search results.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_SEARCH group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS for the default recommended flags.

Returns:

The resulting JSON String describing the result of the search.

Throws:

SzException - If a failure occurs.

See Also:

• SzEngine.searchByAttributes(String, String, Set)
• SzFlag.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS
• SzFlag.SZ_SEARCH_BY_ATTRIBUTES_ALL
• SzFlag.SZ_SEARCH_BY_ATTRIBUTES_STRONG
• SzFlag.SZ_SEARCH_BY_ATTRIBUTES_MINIMAL_ALL
• SzFlag.SZ_SEARCH_BY_ATTRIBUTES_MINIMAL_STRONG
• SzFlagUsageGroup.SZ_SEARCH

whyEntities

public String whyEntities(long entityId1,
 long entityId2,
 Set<SzFlag> flags)
                   throws SzNotFoundException,
SzException

Determines the ways in which two entities identified by the specified entity ID's are related to each other.

The optionally specified Set of SzFlag instances that not only control how the operation is performed but also the level of detail provided for the entity and record being analyzed. The Set may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_WHY group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

whyEntities in interface SzEngine

Parameters:

entityId1 - The entity ID of the first entity.

entityId2 - The entity ID of the second entity.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_WHY group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_WHY_ENTITIES_DEFAULT_FLAGS for the default recommended flags.

Returns:

The JSON String describing the ways in which the entities are related to one another.

Throws:

SzNotFoundException - If either of the entities for the specified entity ID's could not be found.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_WHY_ENTITIES_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_WHY
• SzEngine.whyRecords(SzRecordKey, SzRecordKey, Set)
• SzEngine.whyRecordInEntity(SzRecordKey, Set)

whyRecordInEntity

public String whyRecordInEntity(SzRecordKey recordKey,
 Set<SzFlag> flags)
                         throws SzUnknownDataSourceException,
SzNotFoundException,
SzException

Determines why the record identified by the data source code and record ID in the specified in an SzRecordKey is included in its respective entity.

The optionally specified Set of SzFlag instances that not only control how the operation is performed but also the level of detail provided for the entity and record being analyzed. The Set may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_WHY group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

whyRecordInEntity in interface SzEngine

Parameters:

recordKey - The SzRecordKey that has the data source code and record ID identifying the record.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_WHY group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_WHY_RECORD_IN_ENTITY_DEFAULT_FLAGS for the default recommended flags.

Returns:

The JSON String describing why the record is included in its respective entity.

Throws:

SzUnknownDataSourceException - If an unrecognized data source code is specified.

SzNotFoundException - If any of the records for the specified data source code and record ID pairs cannot be found.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_WHY_RECORD_IN_ENTITY_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_WHY
• SzEngine.whyEntities(long, long, Set)
• SzEngine.whyRecords(SzRecordKey, SzRecordKey, Set)

whyRecords

public String whyRecords(SzRecordKey recordKey1,
 SzRecordKey recordKey2,
 Set<SzFlag> flags)
                  throws SzUnknownDataSourceException,
SzNotFoundException,
SzException

Determines ways in which two records identified by the data source code and record ID pairs from the specified SzRecordKey instances are related to each other.

The optionally specified Set of SzFlag instances that not only control how the operation is performed but also the level of detail provided for the entity and record being analyzed. The Set may contain any SzFlag value, but only flags belonging to the SzFlagUsageGroup.SZ_WHY group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Implemented to call the underlying native API.

Specified by:

whyRecords in interface SzEngine

Parameters:

recordKey1 - The non-null SzRecordKey providing the data source code and record ID for the first record.

recordKey2 - The non-null SzRecordKey providing the data source code and record ID for the second record.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_WHY group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_WHY_RECORDS_DEFAULT_FLAGS for the default recommended flags.

Returns:

The JSON String describing the ways in which the records are related to one another.

Throws:

SzUnknownDataSourceException - If an unrecognized data source code is specified.

SzNotFoundException - If either of the records for the specified data source code and record ID pairs cannot be found.

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_WHY_RECORDS_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_WHY
• SzEngine.whyRecordInEntity(SzRecordKey, Set)
• SzEngine.whyEntities(long, long, Set)