Package com.senzing.sdk

Interface SzEngine

public interface SzEngine

Defines the Java interface to the Senzing engine functions. The Senzing engine functions primarily provide means of working with identity data records, entities and their relationships.

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.
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	findInterestingEntities(long entityId, Set<SzFlag> flags)	An experimental method to obtain interesting entities pertaining to the entity identified by the specified entity ID using the specified Set of SzFlag instances.
String	findInterestingEntities(SzRecordKey recordKey, Set<SzFlag> flags)	An experimental method to obtain interesting entities pertaining to the entity that contains a specific record that is identified by the data source code and record ID associated with the specified SzRecordKey using the specified Set of SzFlag instances.
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.
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 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.

Method Details

primeEngine

void primeEngine()
          throws SzException

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

Throws:

SzException - If a failure occurs.

getStats

String getStats()
         throws SzException

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

Returns:

The String describing the statistics as JSON.

Throws:

SzException - If a failure occurs.

addRecord

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_FLAGS group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

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_FLAGS 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, or null if the specified flags do not indicate that an INFO message should be returned.

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_FLAGS

preprocessRecord

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_FLAGS group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

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_FLAGS 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_FLAGS

deleteRecord

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 parameters 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_FLAGS group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

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_FLAGS 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, or null if the specified flags do not indicate that an INFO message should be returned.

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_FLAGS

reevaluateRecord

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_FLAGS group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

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_FLAGS 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, or null if the specified flags do not indicate that an INFO message should be returned.

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_FLAGS

reevaluateEntity

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

Reevaluate a resolved entity identified by the specified entity ID.

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_FLAGS group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

Parameters:

entityId - The ID of the resolved entity to reevaluate.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_MODIFY_FLAGS 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, or null if the specified flags do not indicate that an INFO message should be returned.

Throws:

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_WITH_INFO_FLAGS
• SzFlagUsageGroup.SZ_MODIFY_FLAGS

searchByAttributes

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 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_FLAGS 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.

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_FLAGS 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:

• 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_FLAGS

searchByAttributes

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

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

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_FLAGS 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:

• 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_FLAGS

getEntity

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_FLAGS 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.

Parameters:

entityId - The entity ID identifying the entity to retrieve.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_ENTITY_FLAGS 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 entity 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_FLAGS

getEntity

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_FLAGS 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.

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_FLAGS 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 entity 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_FLAGS

findInterestingEntities

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

An experimental method to obtain interesting entities pertaining to the entity identified by the specified entity ID using the specified Set of SzFlag instances.

The specified Set of SzFlag instances may contain any SzFlag value, but currenlty no flags are specifically defined for this experimental method. Flags that are not applicable to this method will simply be ignored.

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

Parameters:

entityId - The entity ID identifying the entity that will be the focus for the interesting entities to be returned.

flags - The optional Set of SzFlag instances for the operation, though no flags are currently defined for this experimental method.

Returns:

The JSON String describing the interesting entities.

Throws:

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

SzException - If a failure occurs.

findInterestingEntities

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

An experimental method to obtain interesting entities pertaining to the entity that contains a specific record that is identified by the data source code and record ID associated with the specified SzRecordKey using the specified Set of SzFlag instances.

The specified Set of SzFlag instances may contain any SzFlag value, but currenlty no flags are specifically defined for this experimental method. Flags that are not applicable to this method will simply be ignored.

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

Parameters:

recordKey - The non-null SzRecordKey that specifies the data source code and record Id of the consituent record for the entity that is the focus for the interesting entities to be returned.

flags - The optional Set of SzFlag instances for the operation, though no flags are currently defined for this experimental method.

Returns:

The JSON String describing the interesting entities.

Throws:

SzUnknownDataSourceException - If an unrecognized data source code is specified.

SzNotFoundException - If no reord could be found with the specified record ID.

SzException - If a failure occurs.

findPath

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 Set of String data source codes may optionally be specified to identify required data sources. 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_FLAGS 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.

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 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_FLAGS 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_FLAGS
• findPath(SzRecordKey,SzRecordKey,int,SzRecordKeys,Set,Set)

findPath

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 "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_FLAGS 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.

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_FLAGS 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_FLAGS
• findPath(long,long,int,SzEntityIds,Set,Set)

findNetwork

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_FLAGS 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.

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_FLAGS 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_FLAGS
• findNetwork(SzRecordKeys,int,int,int,Set)

findNetwork

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_FLAGS 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.

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_FLAGS 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_FLAGS
• findNetwork(SzEntityIds,int,int,int,Set)

whyRecordInEntity

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_FLAGS 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.

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_FLAGS 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_FLAGS
• whyEntities(long, long, Set)
• whyRecords(SzRecordKey, SzRecordKey, Set)

whyRecords

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_FLAGS 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.

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_FLAGS 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_FLAGS
• whyRecordInEntity(SzRecordKey, Set)
• whyEntities(long, long, Set)

whyEntities

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_FLAGS 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.

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_FLAGS 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_FLAGS
• whyRecords(SzRecordKey, SzRecordKey, Set)
• whyRecordInEntity(SzRecordKey, Set)

howEntity

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_FLAGS 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.

Parameters:

entityId - The entity ID of the entity.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_HOW_FLAGS 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_FLAGS
• getVirtualEntity(Set, Set)

getVirtualEntity

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_FLAGS 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.

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_FLAGS 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_VIRTUAL_ENTITY_DEFAULT_FLAGS
• SzFlagUsageGroup.SZ_VIRTUAL_ENTITY_FLAGS
• howEntity(long, Set)

getRecord

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_FLAGS 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.

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_FLAGS 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_FLAGS

exportJsonEntityReport

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_FLAGS 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.

Parameters:

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_EXPORT_FLAGS 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_FLAGS
• fetchNext(long)
• closeExport(long)
• exportCsvEntityReport(String, Set)

exportCsvEntityReport

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.

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_FLAGS 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.

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_FLAGS 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_FLAGS
• fetchNext(long)
• closeExport(long)
• exportJsonEntityReport(Set)

fetchNext

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 exportJsonEntityReport(Set) or exportCsvEntityReport(String, Set).

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:

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

closeExport

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.

Parameters:

exportHandle - The export handle of the export to close.

Throws:

SzException - If a failure occurs.

See Also:

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

processRedoRecord

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 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_FLAGS 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.

Parameters:

redoRecord - The redo record to be processed.

flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_MODIFY_FLAGS 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 processing the redo record in the repository, or null if the specified flags do not indicate that an INFO message should be returned.

Throws:

SzException - If a failure occurs.

See Also:

• SzFlag.SZ_WITH_INFO_FLAGS
• SzFlagUsageGroup.SZ_MODIFY_FLAGS
• getRedoRecord()
• countRedoRecords()

getRedoRecord

String getRedoRecord()
              throws SzException

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

Returns:

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

Throws:

SzException - If a failure occurs.

See Also:

• processRedoRecord(String, Set)
• countRedoRecords()

countRedoRecords

long countRedoRecords()
               throws SzException

Gets the number of redo records pending to be processed.

Returns:

The number of redo records pending to be processed.

Throws:

SzException - If a failure occurs.

See Also:

• processRedoRecord(String, Set)
• getRedoRecord()