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.

An SzEngine instance is typically obtained from an SzEnvironment instance via the SzEnvironment.getEngine() method as follows:

// How to obtain an SzEngine instance
try {
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = getEnvironment();

    SzEngine engine = env.getEngine();

    ...

} catch (SzException e) {
    // handle or rethrow the exception
    logError("Failed to get SzEngine.", e);
}

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.
  Usage:
  
  // How to prime the SzEngine to expedite subsequent operations try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // prime the engine engine.primeEngine(); // use the primed engine to perform additional tasks ... } catch (SzException e) { // handle or rethrow the exception logError("Failed to prime engine.", e); }
  Throws:
  
  SzException - If a failure occurs.
  
  See Also:
  
  Code Snippet: Engine Priming
- getStats
  
  String getStats() throws SzException
  Returns the current internal engine workload statistics for the process. The counters are reset after each call.
  Usage:
  
  // How to get engine stats after loading records try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // load some records to prime the stats ... // get the stats String statsJson = engine.getStats(); // do something with the stats log(statsJson); } catch (SzException e) { // handle or rethrow the exception logError("Failed to load records with stats.", e); }
  Returns:
  
  The String describing the statistics as JSON.
  
  Throws:
  
  SzException - If a failure occurs.
  
  See Also:
  
  Code Snippet: Load with Stats
- 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.
  Usage:
  
  // How to load a record try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get a record definition (varies by application) String recordDefinition = """ { "DATA_SOURCE": "TEST", "RECORD_ID": "ABC123", "NAME_FULL": "Joe Schmoe", "PHONE_NUMBER": "702-555-1212", "EMAIL_ADDRESS": "joeschmoe@nowhere.com" } """; // add the record to the repository String infoJson = engine.addRecord( SzRecordKey.of("TEST", "ABC123"), recordDefinition, SZ_WITH_INFO_FLAGS); // do something with the "info JSON" (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject(); if (jsonObject.containsKey("AFFECTED_ENTITIES")) { JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES"); for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) { long affectedId = affected.getJsonNumber("ENTITY_ID").longValue(); ... } } } catch (SzUnknownDataSourceException e) { // handle the unknown data source exception logError("Expected data source is not configured.", e); } catch (SzException e) { // handle or rethrow the exception logError("Failed to add record.", e); }
  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
  
  Code Snippet: Load Records
  
  Code Snippet: Load Truth Set "With Info"
  
  Code Snippet: Load via Futures
  
  Code Snippet: Load via Loop
  
  Code Snippet: Load via Queue
  
  Code Snippet: Load "With Info" via Futures
  
  Code Snippet: Load "With Stats" Via Loop
- 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.
  Usage:
  
  // How to pre-process a record try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get a record definition (varies by application) String recordDefinition = """ { "DATA_SOURCE": "TEST", "RECORD_ID": "DEF456", "NAME_FULL": "John Doe", "PHONE_NUMBER": "702-555-1212", "EMAIL_ADDRESS": "johndoe@nowhere.com" } """; // set up flags for the preprocess call (varies by application) Set<SzFlag> flags = EnumSet.of(SZ_ENTITY_INCLUDE_RECORD_FEATURE_DETAILS, SZ_ENTITY_INCLUDE_RECORD_FEATURE_STATS); // preprocess the record String responseJson = engine.preprocessRecord(recordDefinition, flags); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); if (jsonObject.containsKey("FEATURES")) { JsonObject featuresObj = jsonObject.getJsonObject("FEATURES"); featuresObj.forEach((featureName, jsonValue) -> { ... }); } } catch (SzException e) { // handle or rethrow the exception logError("Failed to preprocess record.", e); }
  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
  
  SzFlag.SZ_RECORD_DEFAULT_FLAGS
  
  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.
  Usage:
  
  // How to delete a record try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // delete the record from the repository String infoJson = engine.deleteRecord( SzRecordKey.of("TEST", "ABC123"), SZ_WITH_INFO_FLAGS); // do something with the "info JSON" (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject(); if (jsonObject.containsKey("AFFECTED_ENTITIES")) { JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES"); for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) { long affectedId = affected.getJsonNumber("ENTITY_ID").longValue(); ... } } } catch (SzUnknownDataSourceException e) { // handle the unknown data source exception logError("Expected data source is not configured.", e); } catch (SzException e) { // handle or rethrow the exception logError("Failed to delete record.", e); }
  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
  
  Code Snippet: Delete via Loop
  
  Code Snippet: Delete via Futures
  
  Code Snippet: Delete "With Info" via Futures
- 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.
  Usage:
  
  // How to reevaluate a record try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // reevaluate a record in the repository String infoJson = engine.reevaluateRecord( SzRecordKey.of("TEST", "ABC123"), SZ_WITH_INFO_FLAGS); // do something with the "info JSON" (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject(); if (jsonObject.containsKey("AFFECTED_ENTITIES")) { JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES"); for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) { long affectedId = affected.getJsonNumber("ENTITY_ID").longValue(); ... } } } catch (SzUnknownDataSourceException e) { // handle the unknown data source exception logError("Expected data source is not configured.", e); } catch (SzException e) { // handle or rethrow the exception logError("Failed to reevaluate record.", e); }
  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.
  Usage:
  
  // How to reevaluate an entity try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get the ID of an entity to reevaluate (varies by application) long entityId = getEntityId(); // reevaluate an entity in the repository String infoJson = engine.reevaluateEntity(entityId, SZ_WITH_INFO_FLAGS); // do something with the "info JSON" (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject(); if (jsonObject.containsKey("AFFECTED_ENTITIES")) { JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES"); for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) { long affectedId = affected.getJsonNumber("ENTITY_ID").longValue(); ... } } } catch (SzException e) { // handle or rethrow the exception logError("Failed to reevaluate entity.", e); }
  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.
  Usage:
  
  // How to search for entities matching criteria using a search profile try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get the search attributes (varies by application) String searchAttributes = """ { "NAME_FULL": "Joe Schmoe", "PHONE_NUMBER": "702-555-1212", "EMAIL_ADDRESS": "joeschmoe@nowhere.com" } """; // get a search profile (varies by application) String searchProfile = getSearchProfile(); // search for matching entities in the repository String responseJson = engine.searchByAttributes( searchAttributes, searchProfile, SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); if (jsonObject.containsKey("RESOLVED_ENTITIES")) { JsonArray resultsArr = jsonObject.getJsonArray("RESOLVED_ENTITIES"); for (JsonObject result : resultsArr.getValuesAs(JsonObject.class)) { // get the match info for the result JsonObject matchInfo = result.getJsonObject("MATCH_INFO"); ... // get the entity for the result JsonObject entityInfo = result.getJsonObject("ENTITY"); JsonObject entity = entityInfo.getJsonObject("RESOLVED_ENTITY"); long entityId = entity.getJsonNumber("ENTITY_ID").longValue(); ... } } } catch (SzException e) { // handle or rethrow the exception logError("Failed to search for entities.", e); }
  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
  
  Code Snippet: Search Records
  
  Code Snippet: Search via Futures
- 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.
  Usage:
  
  // How to search for entities matching criteria try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get the search attributes (varies by application) String searchAttributes = """ { "NAME_FULL": "Joe Schmoe", "PHONE_NUMBER": "702-555-1212", "EMAIL_ADDRESS": "joeschmoe@nowhere.com" } """; // search for matching entities in the repository String responseJson = engine.searchByAttributes( searchAttributes, SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); if (jsonObject.containsKey("RESOLVED_ENTITIES")) { JsonArray resultsArr = jsonObject.getJsonArray("RESOLVED_ENTITIES"); for (JsonObject result : resultsArr.getValuesAs(JsonObject.class)) { // get the match info for the result JsonObject matchInfo = result.getJsonObject("MATCH_INFO"); ... // get the entity for the result JsonObject entityInfo = result.getJsonObject("ENTITY"); JsonObject entity = entityInfo.getJsonObject("RESOLVED_ENTITY"); long entityId = entity.getJsonNumber("ENTITY_ID").longValue(); ... } } } catch (SzException e) { // handle or rethrow the exception logError("Failed to search for entities.", e); }
  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
  
  Code Snippet: Search Records
  
  Code Snippet: Search via Futures
- 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.
  Usage:
  
  // How to retrieve an entity via its entity ID try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get the ID of an entity to retrieve (varies by application) long entityId = getEntityId(); // retrieve the entity by entity ID String responseJson = engine.getEntity(entityId, SZ_ENTITY_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); JsonObject entity = jsonObject.getJsonObject("RESOLVED_ENTITY"); String entityName = entity.getString("ENTITY_NAME"); ... if (jsonObject.containsKey("RECORDS")) { JsonArray recordArr = jsonObject.getJsonArray("RECORDS"); for (JsonObject record : recordArr.getValuesAs(JsonObject.class)) { String dataSource = record.getString("DATA_SOURCE"); String recordId = record.getString("RECORD_ID"); ... } } } catch (SzNotFoundException e) { // handle the not-found exception logError("Entity not found for entity ID.", e); } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve entity by entity ID.", e); }
  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.
  Usage:
  
  // How to retrieve an entity via its record key try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // retrieve the entity by record key String responseJson = engine.getEntity( SzRecordKey.of("TEST", "ABC123"), SZ_ENTITY_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); JsonObject entity = jsonObject.getJsonObject("RESOLVED_ENTITY"); String entityName = entity.getString("ENTITY_NAME"); ... if (jsonObject.containsKey("RECORDS")) { JsonArray recordArr = jsonObject.getJsonArray("RECORDS"); for (JsonObject record : recordArr.getValuesAs(JsonObject.class)) { String dataSource = record.getString("DATA_SOURCE"); String recordId = record.getString("RECORD_ID"); ... } } } catch (SzUnknownDataSourceException e) { // handle the unknown data source exception logError("Expected data source is not configured.", e); } catch (SzNotFoundException e) { // handle the not-found exception logError("Entity not found for record key.", e); } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve entity by record key.", e); }
  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.
  Usage:
  
  // How to find interesting entities related to an entity via entity ID try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get the ID of an entity to retrieve (varies by application) long entityId = getEntityId(); // find the interesting entities by entity ID String responseJson = engine.findInterestingEntities(entityId, SZ_NO_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); ... } catch (SzNotFoundException e) { // handle the not-found exception logError("Entity not found for entity ID.", e); } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to find interesting entities by entity ID.", e); }
  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.
  Usage:
  
  // How to find interesting entities related to an entity via record key try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // retrieve the entity by record key String responseJson = engine.findInterestingEntities( SzRecordKey.of("TEST", "ABC123"), SZ_NO_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); ... } catch (SzUnknownDataSourceException e) { // handle the unknown data source exception logError("Expected data source is not configured.", e); } catch (SzNotFoundException e) { // handle the not-found exception logError("Entity not found for record key.", e); } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to find interesting entities by record key.", e); }
  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.
  Usage:
  
  // How to find an entity path using entity ID's try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get entity ID's for the path endpoints (varies by application) long startEntityId = getPathStartEntityId(); long endEntityId = getPathEndEntityId(); // determine the maximum path degrees (varies by application) int maxDegrees = 4; // determine any entities to be avoided (varies by application) Set<Long> avoidEntities = getPathAvoidEntityIds(); // determine any data sources to require in the path (varies by application) Set<String> requiredSources = null; // retrieve the entity path using the entity ID's String responseJson = engine.findPath(startEntityId, endEntityId, maxDegrees, SzEntityIds.of(avoidEntities), requiredSources, SZ_FIND_PATH_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); JsonArray pathArr = jsonObject.getJsonArray("ENTITY_PATHS"); for (JsonObject path : pathArr.getValuesAs(JsonObject.class)) { JsonArray entityIds = path.getJsonArray("ENTITIES"); for (JsonNumber number : entityIds.getValuesAs(JsonNumber.class)) { long entityId = number.longValue(); ... } } } catch (SzUnknownDataSourceException e) { // handle the unknown data source exception logError("Expected data source is not configured.", e); } catch (SzNotFoundException e) { // handle the not-found exception logError("Entity not found for entity ID.", e); } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve entity path by entity ID.", e); }
  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.
  Usage:
  
  // How to find an entity path using record keys try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get entity ID's for the path endpoints (varies by application) SzRecordKey startRecordKey = getPathStartRecordKey(); SzRecordKey endRecordKey = getPathEndRecordKey(); // determine the maximum path degrees (varies by application) int maxDegrees = 4; // determine any records to be avoided (varies by application) Set<SzRecordKey> avoidRecords = getPathAvoidRecordKeys(); // determine any data sources to require in the path (varies by application) Set<String> requiredSources = null; // retrieve the entity path using the record keys String responseJson = engine.findPath(startRecordKey, endRecordKey, maxDegrees, SzRecordKeys.of(avoidRecords), requiredSources, SZ_FIND_PATH_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); JsonArray pathArr = jsonObject.getJsonArray("ENTITY_PATHS"); for (JsonObject path : pathArr.getValuesAs(JsonObject.class)) { JsonArray entityIds = path.getJsonArray("ENTITIES"); for (JsonNumber number : entityIds.getValuesAs(JsonNumber.class)) { long entityId = number.longValue(); ... } } } catch (SzUnknownDataSourceException e) { // handle the unknown data source exception logError("Expected data source is not configured.", e); } catch (SzNotFoundException e) { // handle the not-found exception logError("Entity not found for record key.", e); } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve entity path by record key.", e); }
  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.
  Usage:
  
  // How to find an entity network using entity ID's try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get entity ID's for the path endpoints (varies by application) Set<Long> entityIds = getNetworkEntityIds(); // determine the maximum path degrees (varies by application) int maxDegrees = 3; // determine the degrees to build-out the network (varies by application) int buildOutDegrees = 0; // determine the max entities to build-out (varies by application) int buildOutMaxEntities = 10; // retrieve the entity network using the entity ID's String responseJson = engine.findNetwork(SzEntityIds.of(entityIds), maxDegrees, buildOutDegrees, buildOutMaxEntities, SZ_FIND_NETWORK_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); JsonArray pathArr = jsonObject.getJsonArray("ENTITY_PATHS"); for (JsonObject path : pathArr.getValuesAs(JsonObject.class)) { long startEntityId = path.getJsonNumber("START_ENTITY_ID").longValue(); long endEntityId = path.getJsonNumber("END_ENTITY_ID").longValue(); JsonArray entityPathIds = path.getJsonArray("ENTITIES"); for (JsonNumber number : entityPathIds.getValuesAs(JsonNumber.class)) { long entityId = number.longValue(); ... } } } catch (SzNotFoundException e) { // handle the not-found exception logError("Entity not found for entity ID.", e); } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve entity network.", e); }
  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.
  Usage:
  
  // How to find an entity network using record keys try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get entity ID's for the path endpoints (varies by application) Set<SzRecordKey> recordKeys = getNetworkRecordKeys(); // determine the maximum path degrees (varies by application) int maxDegrees = 3; // determine the degrees to build-out the network (varies by application) int buildOutDegrees = 0; // determine the max entities to build-out (varies by application) int buildOutMaxEntities = 10; // retrieve the entity newtwork using the record keys String responseJson = engine.findNetwork(SzRecordKeys.of(recordKeys), maxDegrees, buildOutDegrees, buildOutMaxEntities, SZ_FIND_NETWORK_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); JsonArray pathArr = jsonObject.getJsonArray("ENTITY_PATHS"); for (JsonObject path : pathArr.getValuesAs(JsonObject.class)) { long startEntityId = path.getJsonNumber("START_ENTITY_ID").longValue(); long endEntityId = path.getJsonNumber("END_ENTITY_ID").longValue(); JsonArray entityPathIds = path.getJsonArray("ENTITIES"); for (JsonNumber number : entityPathIds.getValuesAs(JsonNumber.class)) { long entityId = number.longValue(); ... } } } catch (SzUnknownDataSourceException e) { // handle the unknown data source exception logError("Expected data source is not configured.", e); } catch (SzNotFoundException e) { // handle the not-found exception logError("Entity not found for record key.", e); } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve entity network.", e); }
  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.
  Usage:
  
  // How to determine why a record is a member of its respective entity try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // determine why the record is part of its entity String responseJson = engine.whyRecordInEntity( SzRecordKey.of("TEST", "ABC123"), SZ_WHY_RECORD_IN_ENTITY_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); JsonArray resultsArr = jsonObject.getJsonArray("WHY_RESULTS"); for (JsonObject result : resultsArr.getValuesAs(JsonObject.class)) { long entityId = result.getJsonNumber("ENTITY_ID").longValue(); ... } } catch (SzUnknownDataSourceException e) { // handle the unknown data source exception logError("Expected data source is not configured.", e); } catch (SzNotFoundException e) { // handle the not-found exception logError("Entity not found for record key.", e); } catch (SzException e) { // handle or rethrow the exception logError("Failed to reevaluate record.", e); }
  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.
  Usage:
  
  // How to determine how two records are related try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get the records on which to operate (varies by application) SzRecordKey recordKey1 = getWhyRecordsKey1(); SzRecordKey recordKey2 = getWhyRecordsKey2(); // determine how the records are related String responseJson = engine.whyRecords(recordKey1, recordKey2, SZ_WHY_RECORDS_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); JsonArray resultsArr = jsonObject.getJsonArray("WHY_RESULTS"); for (JsonObject result : resultsArr.getValuesAs(JsonObject.class)) { long entityId1 = result.getJsonNumber("ENTITY_ID").longValue(); long entityId2 = result.getJsonNumber("ENTITY_ID_2").longValue(); ... } } catch (SzUnknownDataSourceException e) { // handle the unknown data source exception logError("Expected data source is not configured.", e); } catch (SzNotFoundException e) { // handle the not-found exception logError("Entity not found for record key.", e); } catch (SzException e) { // handle or rethrow the exception logError("Failed to reevaluate record.", e); }
  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.
  Usage:
  
  // How to determine how two entities are related try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get the entities on which to operate (varies by application) long entityId1 = getWhyEntitiesId1(); long entityId2 = getWhyEntitiesId2(); // determine how the entities are related String responseJson = engine.whyEntities(entityId1, entityId2, SZ_WHY_ENTITIES_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); JsonArray resultsArr = jsonObject.getJsonArray("WHY_RESULTS"); for (JsonObject result : resultsArr.getValuesAs(JsonObject.class)) { long whyEntityId1 = result.getJsonNumber("ENTITY_ID").longValue(); long whyEntityId2 = result.getJsonNumber("ENTITY_ID_2").longValue(); ... } } catch (SzNotFoundException e) { // handle the not-found exception logError("Entity not found for record key.", e); } catch (SzException e) { // handle or rethrow the exception logError("Failed to reevaluate record.", e); }
  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.
  Usage:
  
  // How to retrieve the "how analysis" for an entity via its entity ID try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get the entity ID on which to operate (varies by application) long entityId = getEntityId(); // determine how the entity was formed String responseJson = engine.howEntity(entityId, SZ_HOW_ENTITY_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); JsonObject howResults = jsonObject.getJsonObject("HOW_RESULTS"); JsonArray stepsArr = howResults.getJsonArray("RESOLUTION_STEPS"); for (JsonObject step : stepsArr.getValuesAs(JsonObject.class)) { JsonObject matchInfo = step.getJsonObject("MATCH_INFO"); ... } } catch (SzNotFoundException e) { // handle the not-found exception logError("Entity not found for entity ID.", e); } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve how analysis.", e); }
  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.
  Usage:
  
  // How to retrieve a virtual entity via a set of record keys try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get the records to operate on (varies by application) Set<SzRecordKey> recordKeys = getVirtualEntityRecordKeys(); // retrieve the virtual entity for the record keys String responseJson = engine.getVirtualEntity(recordKeys, SZ_VIRTUAL_ENTITY_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); JsonObject entity = jsonObject.getJsonObject("RESOLVED_ENTITY"); String entityName = entity.getString("ENTITY_NAME"); ... if (jsonObject.containsKey("RECORDS")) { JsonArray recordArr = jsonObject.getJsonArray("RECORDS"); for (JsonObject record : recordArr.getValuesAs(JsonObject.class)) { String dataSource = record.getString("DATA_SOURCE"); String recordId = record.getString("RECORD_ID"); ... } } } catch (SzUnknownDataSourceException e) { // handle the unknown data source exception logError("Expected data source is not configured.", e); } catch (SzNotFoundException e) { // handle the not-found exception logError("Specified record key was not found.", e); } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve virtual entity.", e); }
  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.
  Usage:
  
  // How to retrieve a record via its record key try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // retrieve the entity by record key String responseJson = engine.getRecord( SzRecordKey.of("TEST", "ABC123"), SZ_ENTITY_DEFAULT_FLAGS); // do something with the response JSON (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject(); String dataSource = jsonObject.getString("DATA_SOURCE"); String recordId = jsonObject.getString("RECORD_ID"); ... } catch (SzUnknownDataSourceException e) { // handle the unknown data source exception logError("Expected data source is not configured.", e); } catch (SzNotFoundException e) { // handle the not-found exception logError("Record not found for record key.", e); } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve record by record key.", e); }
  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.
  Usage:
  
  // How to export entity data in JSON format try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // export the JSON data long exportHandle = engine.exportJsonEntityReport(SZ_EXPORT_DEFAULT_FLAGS); // read the data try { // fetch the first JSON record String jsonData = engine.fetchNext(exportHandle); while (jsonData != null) { // parse the JSON data JsonObject jsonObject = Json.createReader(new StringReader(jsonData)).readObject(); // do something with the parsed data (varies by application) processJsonRecord(jsonObject); // fetch the next JSON record jsonData = engine.fetchNext(exportHandle); } } finally { // close the export handle engine.closeExport(exportHandle); } } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve record by record key.", e); }
  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.
  Usage:
  
  // How to export entity data in CSV format try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // export the JSON data long exportHandle = engine.exportCsvEntityReport("*", SZ_EXPORT_DEFAULT_FLAGS); // read the data try { // fetch the CSV header line from the exported data String csvHeaders = engine.fetchNext(exportHandle); // process the CSV headers (varies by application) processCsvHeaders(csvHeaders); // fetch the first CSV record from the exported data String csvRecord = engine.fetchNext(exportHandle); while (csvRecord != null) { // do something with the exported record (varies by application) processCsvRecord(csvRecord); // fetch the next exported CSV record csvRecord = engine.fetchNext(exportHandle); } } finally { // close the export handle engine.closeExport(exportHandle); } } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve record by record key.", e); }
  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).
  Usage (JSON export):
  
  // How to export entity data in JSON format try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // export the JSON data long exportHandle = engine.exportJsonEntityReport(SZ_EXPORT_DEFAULT_FLAGS); // read the data try { // fetch the first JSON record String jsonData = engine.fetchNext(exportHandle); while (jsonData != null) { // parse the JSON data JsonObject jsonObject = Json.createReader(new StringReader(jsonData)).readObject(); // do something with the parsed data (varies by application) processJsonRecord(jsonObject); // fetch the next JSON record jsonData = engine.fetchNext(exportHandle); } } finally { // close the export handle engine.closeExport(exportHandle); } } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve record by record key.", e); }
  
  Usage (CSV export):
  
  // How to export entity data in CSV format try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // export the JSON data long exportHandle = engine.exportCsvEntityReport("*", SZ_EXPORT_DEFAULT_FLAGS); // read the data try { // fetch the CSV header line from the exported data String csvHeaders = engine.fetchNext(exportHandle); // process the CSV headers (varies by application) processCsvHeaders(csvHeaders); // fetch the first CSV record from the exported data String csvRecord = engine.fetchNext(exportHandle); while (csvRecord != null) { // do something with the exported record (varies by application) processCsvRecord(csvRecord); // fetch the next exported CSV record csvRecord = engine.fetchNext(exportHandle); } } finally { // close the export handle engine.closeExport(exportHandle); } } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve record by record key.", e); }
  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.
  Usage (JSON export):
  
  // How to export entity data in JSON format try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // export the JSON data long exportHandle = engine.exportJsonEntityReport(SZ_EXPORT_DEFAULT_FLAGS); // read the data try { // fetch the first JSON record String jsonData = engine.fetchNext(exportHandle); while (jsonData != null) { // parse the JSON data JsonObject jsonObject = Json.createReader(new StringReader(jsonData)).readObject(); // do something with the parsed data (varies by application) processJsonRecord(jsonObject); // fetch the next JSON record jsonData = engine.fetchNext(exportHandle); } } finally { // close the export handle engine.closeExport(exportHandle); } } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve record by record key.", e); }
  
  Usage (CSV export):
  
  // How to export entity data in CSV format try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // export the JSON data long exportHandle = engine.exportCsvEntityReport("*", SZ_EXPORT_DEFAULT_FLAGS); // read the data try { // fetch the CSV header line from the exported data String csvHeaders = engine.fetchNext(exportHandle); // process the CSV headers (varies by application) processCsvHeaders(csvHeaders); // fetch the first CSV record from the exported data String csvRecord = engine.fetchNext(exportHandle); while (csvRecord != null) { // do something with the exported record (varies by application) processCsvRecord(csvRecord); // fetch the next exported CSV record csvRecord = engine.fetchNext(exportHandle); } } finally { // close the export handle engine.closeExport(exportHandle); } } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to retrieve record by record key.", e); }
  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.
  Usage:
  
  // How to check for and process redo records try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get the redo count long redoCount = engine.countRedoRecords(); // check if we have redo records if (redoCount > 0L) { // get the next redo record String redoRecord = engine.getRedoRecord(); // loop while we still have redo records while (redoRecord != null) { try { // process the redo record String infoJson = engine.processRedoRecord(redoRecord, SZ_ENTITY_DEFAULT_FLAGS); // do something with the "info JSON" (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject(); if (jsonObject.containsKey("AFFECTED_ENTITIES")) { JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES"); for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) { long affectedId = affected.getJsonNumber("ENTITY_ID").longValue(); ... } } } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to process redo record: " + redoRecord, e); } // get the next redo record redoRecord = engine.getRedoRecord(); } } } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to process redos.", e); }
  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()
  
  Code Snippet: Processing Redos while Loading
  
  Code Snippet: Continuous Redo Processing
  
  Code Snippet: Continuous Redo Processing via Futures
  
  Code Snippet: Continuous Redo "With Info" Processing
- 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.
  Usage:
  
  // How to check for and process redo records try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get the redo count long redoCount = engine.countRedoRecords(); // check if we have redo records if (redoCount > 0L) { // get the next redo record String redoRecord = engine.getRedoRecord(); // loop while we still have redo records while (redoRecord != null) { try { // process the redo record String infoJson = engine.processRedoRecord(redoRecord, SZ_ENTITY_DEFAULT_FLAGS); // do something with the "info JSON" (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject(); if (jsonObject.containsKey("AFFECTED_ENTITIES")) { JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES"); for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) { long affectedId = affected.getJsonNumber("ENTITY_ID").longValue(); ... } } } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to process redo record: " + redoRecord, e); } // get the next redo record redoRecord = engine.getRedoRecord(); } } } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to process redos.", e); }
  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()
  
  Code Snippet: Processing Redos while Loading
  
  Code Snippet: Continuous Redo Processing
  
  Code Snippet: Continuous Redo Processing via Futures
  
  Code Snippet: Continuous Redo "With Info" Processing
- countRedoRecords
  
  long countRedoRecords() throws SzException
  Gets the number of redo records pending to be processed.
  Usage:
  
  // How to check for and process redo records try { // obtain the SzEnvironment (varies by application) SzEnvironment env = getEnvironment(); // get the engine SzEngine engine = env.getEngine(); // get the redo count long redoCount = engine.countRedoRecords(); // check if we have redo records if (redoCount > 0L) { // get the next redo record String redoRecord = engine.getRedoRecord(); // loop while we still have redo records while (redoRecord != null) { try { // process the redo record String infoJson = engine.processRedoRecord(redoRecord, SZ_ENTITY_DEFAULT_FLAGS); // do something with the "info JSON" (varies by application) JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject(); if (jsonObject.containsKey("AFFECTED_ENTITIES")) { JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES"); for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) { long affectedId = affected.getJsonNumber("ENTITY_ID").longValue(); ... } } } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to process redo record: " + redoRecord, e); } // get the next redo record redoRecord = engine.getRedoRecord(); } } } catch (SzException e) { // handle or rethrow the other exceptions logError("Failed to process redos.", e); }
  Returns:
  
  The number of redo records pending to be processed.
  
  Throws:
  
  SzException - If a failure occurs.
  
  See Also:
  
  processRedoRecord(String, Set)
  
  getRedoRecord()
  
  Code Snippet: Processing Redos while Loading
  
  Code Snippet: Continuous Redo Processing
  
  Code Snippet: Continuous Redo Processing via Futures
  
  Code Snippet: Continuous Redo "With Info" Processing

Interface SzEngine

Method Summary

Method Details

primeEngine

getStats

addRecord

preprocessRecord

deleteRecord

reevaluateRecord

reevaluateEntity

searchByAttributes

searchByAttributes

getEntity

getEntity

findInterestingEntities

findInterestingEntities

findPath

findPath

findNetwork

findNetwork

whyRecordInEntity

whyRecords

whyEntities

howEntity

getVirtualEntity

getRecord

exportJsonEntityReport

exportCsvEntityReport

fetchNext

closeExport

processRedoRecord

getRedoRecord

countRedoRecords