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.

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 Details Link icon

    • primeEngine Link icon

      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:

    • getStats Link icon

      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:

    • addRecord Link icon

      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_ADD_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 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_ADD_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_WITH_INFO_FLAGS for an INFO response. SzFlag.SZ_ADD_RECORD_DEFAULT_FLAGS is also available if you desire to use recommended defaults.
      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:

    • addRecord Link icon

      default String addRecord(SzRecordKey recordKey, String recordDefinition) throws SzUnknownDataSourceException, SzBadInputException, SzException
      Convenience method for calling addRecord(SzRecordKey, String, Set) using SzFlag.SZ_ADD_RECORD_DEFAULT_FLAGS as the value for the flags parameter. See the addRecord(SzRecordKey, String, Set) documentation for details.

      NOTE: The String return type is still used despite the fact that in the current version this will always return null due to SzFlag.SZ_ADD_RECORD_DEFAULT_FLAGS being equivalent to SzFlag.SZ_NO_FLAGS. However, having a void return type would cause incompatibilities if a future release introduced a different value for SzFlag.SZ_ADD_RECORD_DEFAULT_FLAGS that did trigger a non-null return value.

      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
    engine.addRecord(
        SzRecordKey.of("TEST", "ABC123"),
        recordDefinition);

} 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.
      Returns:
      The JSON String result produced by adding the record to the repository, which will always be null in the current version (see above).
      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:

    • preprocessRecord Link icon

      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_PREPROCESS_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"
            }
            """;

    // preprocess the record
    String responseJson = engine.preprocessRecord(
        recordDefinition, SZ_PREPROCESS_RECORD_DEFAULT_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_PREPROCESS_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_PREPROCESS_RECORD_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The JSON String result produced by preprocessing the record (depending on the specified flags).
      Throws:
      SzException - If a failure occurs.
      See Also:

    • preprocessRecord Link icon

      default String preprocessRecord(String recordDefinition) throws SzException
      Convenience method for calling preprocessRecord(String, Set) using SzFlag.SZ_PREPROCESS_RECORD_DEFAULT_FLAGS as the value for the flags parameter. See the preprocessRecord(String, Set) documentation for details.

      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"
            }
            """;

    // preprocess the record
    String responseJson = engine.preprocessRecord(recordDefinition);

    // 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.
      Returns:
      The JSON String result produced by preprocessing the record using the default flags.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • deleteRecord Link icon

      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_DELETE_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 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_DELETE_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_WITH_INFO_FLAGS for an INFO response. SzFlag.SZ_DELETE_RECORD_DEFAULT_FLAGS is also available if you desire to use recommended defaults.
      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:

    • deleteRecord Link icon

      default String deleteRecord(SzRecordKey recordKey) throws SzUnknownDataSourceException, SzException
      Convenience method for calling deleteRecord(SzRecordKey, Set) using SzFlag.SZ_DELETE_RECORD_DEFAULT_FLAGS as the value for the flags parameter. See the deleteRecord(SzRecordKey, Set) documentation for details.

      NOTE: The String return type is still used despite the fact that in the current version this will always return null due to SzFlag.SZ_DELETE_RECORD_DEFAULT_FLAGS being equivalent to SzFlag.SZ_NO_FLAGS. However, having a void return type would cause incompatibilities if a future release introduced a different value for SzFlag.SZ_DELETE_RECORD_DEFAULT_FLAGS that did trigger a non-null return value.

      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
    engine.deleteRecord(
        SzRecordKey.of("TEST", "ABC123"));

} 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.
      Returns:
      The JSON String result produced by deleting the record from the repository, which will always be null in the current version (see above).
      Throws:
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzException - If a failure occurs.
      See Also:

    • reevaluateRecord Link icon

      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_REEVALUATE_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 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_REEVALUATE_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_WITH_INFO_FLAGS for an INFO response. SzFlag.SZ_REEVALUATE_RECORD_DEFAULT_FLAGS is also available if you desire to use recommended defaults.
      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:

    • reevaluateRecord Link icon

      default String reevaluateRecord(SzRecordKey recordKey) throws SzUnknownDataSourceException, SzException
      Convenience method for calling reevaluateRecord(SzRecordKey, Set) using SzFlag.SZ_REEVALUATE_RECORD_DEFAULT_FLAGS as the value for the flags parameter. See the reevaluateRecord(SzRecordKey, Set) documentation for details.

      NOTE: The String return type is still used despite the fact that in the current version this will always return null due to SzFlag.SZ_REEVALUATE_RECORD_DEFAULT_FLAGS being equivalent to SzFlag.SZ_NO_FLAGS. However, having a void return type would cause incompatibilities if a future release introduced a different value for SzFlag.SZ_REEVALUATE_RECORD_DEFAULT_FLAGS that did trigger a non-null return value.

      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
    engine.reevaluateRecord(
        SzRecordKey.of("TEST", "ABC123"));

} 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.
      Returns:
      The JSON String result produced by reevaluating the record in the repository, which will always be null in the current version (see above).
      Throws:
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzException - If a failure occurs.
      See Also:

    • reevaluateEntity Link icon

      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_REEVALUATE_ENTITY_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_REEVALUATE_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_WITH_INFO_FLAGS for an INFO response. SzFlag.SZ_REEVALUATE_ENTITY_DEFAULT_FLAGS is also available if you desire to use recommended defaults.
      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:

    • reevaluateEntity Link icon

      default String reevaluateEntity(long entityId) throws SzException
      Convenience method for calling reevaluateEntity(long, Set) using SzFlag.SZ_REEVALUATE_ENTITY_DEFAULT_FLAGS as the value for the flags parameter. See the reevaluateEntity(long, Set) documentation for details.

      NOTE: The String return type is still used despite the fact that in the current version this will always return null due to SzFlag.SZ_REEVALUATE_ENTITY_DEFAULT_FLAGS being equivalent to SzFlag.SZ_NO_FLAGS. However, having a void return type would cause incompatibilities if a future release introduced a different value for SzFlag.SZ_REEVALUATE_ENTITY_DEFAULT_FLAGS that did trigger a non-null return value.

      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
    engine.reevaluateEntity(entityId);

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

      Parameters:
      entityId - The ID of the resolved entity to reevaluate.
      Returns:
      The JSON String result produced by reevaluating the entity in the repository, which will always be null in the current version (see above).
      Throws:
      SzException - If a failure occurs.
      See Also:

    • searchByAttributes Link icon

      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 Link icon

      default String searchByAttributes(String attributes, String searchProfile) throws SzException
      Convenience method for calling searchByAttributes(String, String, Set) using SzFlag.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS as the value for the flags parameter. See the searchByAttributes(String, String, Set) documentation for details.

      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);

    // 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.
      Returns:
      The resulting JSON String describing the result of the search.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • searchByAttributes Link icon

      default String searchByAttributes(String attributes, Set<SzFlag> flags) throws SzException
      Convenience method for calling searchByAttributes(String, String, Set) with a null value for the search profile parameter. See the 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 Link icon

      default String searchByAttributes(String attributes) throws SzException
      Convenience method for calling searchByAttributes(String, String, Set) with a null value for the search profile parameter and SzFlag.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS as the value for the flags parameter. See the 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);

    // 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.
      Returns:
      The resulting JSON String describing the result of the search.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • whySearch Link icon

      String whySearch(String attributes, long entityId, String searchProfile, Set<SzFlag> flags) throws SzNotFoundException, SzException
      Compares the specified search attribute criteria against the entity identified by the specified entity ID to determine why that entity was or was not included in the results of a "search by attributes" operation.

      The specified search attributes are treated as a hypothetical single-record entity and the result of this operation is the "why analysis" of the entity identified by the specified entity ID against that hypothetical entity. The details included in the response are determined by 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 candidate determination. 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_WHY_SEARCH_FLAGS group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags to supported flags).

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

      Usage: 

      // How to determine why an entity was excluded from search results
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();

    // get the entities on which to operate (varies by application)
    long entityId = getWhySearchEntityId();

    // determine how the entities are related
    String responseJson = engine.whySearch(searchAttributes,
                                           entityId,
                                           searchProfile,
                                           SZ_WHY_SEARCH_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();

        ...
    }

} catch (SzNotFoundException e) {
    // handle the not-found exception
    logError("Entity not found for entity ID.", e);

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

      Parameters:
      attributes - The search attributes defining the hypothetical record to match and/or relate to in order to obtain the search results.
      entityId - The entity ID identifying the entity to analyze against the search attribute criteria.
      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_WHY_SEARCH_FLAGS group t 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_SEARCH_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The resulting JSON String describing the result of the why analysis against the search criteria.
      Throws:
      SzNotFoundException - If no entity could be found with the specified entity ID.
      SzException - If a failure occurs.
      See Also:

    • whySearch Link icon

      default String whySearch(String attributes, long entityId, String searchProfile) throws SzNotFoundException, SzException
      Convenience method for calling whySearch(String, long, String, Set) using SzFlag.SZ_WHY_SEARCH_DEFAULT_FLAGS as the value for the flags parameter. See the whySearch(String, long, String, Set) documentation for details.

      Usage: 

      // How to determine why an entity was excluded from search results
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 the entities on which to operate (varies by application)
    long entityId = getWhySearchEntityId();

    // determine how the entities are related
    String responseJson = engine.whySearch(searchAttributes, entityId);

    // 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();

        ...
    }

} catch (SzNotFoundException e) {
    // handle the not-found exception
    logError("Entity not found for entity ID.", e);

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

      Parameters:
      attributes - The search attributes defining the hypothetical record to match and/or relate to in order to obtain the search results.
      entityId - The entity ID identifying the entity to analyze against the search attribute criteria.
      searchProfile - The optional search profile identifier, or null if the default search profile should be used for the search.
      Returns:
      The resulting JSON String describing the result of the why analysis against the search criteria.
      Throws:
      SzNotFoundException - If no entity could be found with the specified entity ID.
      SzException - If a failure occurs.
      See Also:

    • whySearch Link icon

      default String whySearch(String attributes, long entityId, Set<SzFlag> flags) throws SzNotFoundException, SzException
      Convenience method for calling whySearch(String, long, String, Set) with a null value for the search profile parameter. See the whySearch(String, long, String, Set) documentation for details.

      Usage: 

      // How to determine why an entity was excluded from search results
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 the entities on which to operate (varies by application)
    long entityId = getWhySearchEntityId();

    // determine how the entities are related
    String responseJson = engine.whySearch(searchAttributes,
                                           entityId,
                                           SZ_WHY_SEARCH_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();

        ...
    }

} catch (SzNotFoundException e) {
    // handle the not-found exception
    logError("Entity not found for entity ID.", e);

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

      Parameters:
      attributes - The search attributes defining the hypothetical record to match and/or relate to in order to obtain the search results.
      entityId - The entity ID identifying the entity to analyze against the search attribute criteria.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_WHY_SEARCH_FLAGS group t 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_SEARCH_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The resulting JSON String describing the result of the why analysis against the search criteria.
      Throws:
      SzNotFoundException - If no entity could be found with the specified entity ID.
      SzException - If a failure occurs.
      See Also:

    • whySearch Link icon

      default String whySearch(String attributes, long entityId) throws SzNotFoundException, SzException
      Convenience method for calling whySearch(String, long, String, Set) with a null value for the search profile parameter and SzFlag.SZ_WHY_SEARCH_DEFAULT_FLAGS as the value for the flags parameter. See the whySearch(String, long, String, Set) documentation for details.

      Usage: 

      // How to determine why an entity was excluded from search results
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 the entities on which to operate (varies by application)
    long entityId = getWhySearchEntityId();

    // determine how the entities are related
    String responseJson = engine.whySearch(searchAttributes, entityId);

    // 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();

        ...
    }

} catch (SzNotFoundException e) {
    // handle the not-found exception
    logError("Entity not found for entity ID.", e);

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

      Parameters:
      attributes - The search attributes defining the hypothetical record to match and/or relate to in order to obtain the search results.
      entityId - The entity ID identifying the entity to analyze against the search attribute criteria.
      Returns:
      The resulting JSON String describing the result of the why analysis against the search criteria.
      Throws:
      SzNotFoundException - If no entity could be found with the specified entity ID.
      SzException - If a failure occurs.
      See Also:

    • getEntity Link icon

      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:

    • getEntity Link icon

      default String getEntity(long entityId) throws SzNotFoundException, SzException
      Convenience method for calling getEntity(long,Set) using SzFlag.SZ_ENTITY_DEFAULT_FLAGS as the value for theflags parameter. See the getEntity(long, Set) documentation for details.

      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);

    // 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.
      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:

    • getEntity Link icon

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

    • getEntity Link icon

      default String getEntity(SzRecordKey recordKey) throws SzUnknownDataSourceException, SzNotFoundException, SzException
      Convenience method for calling getEntity(SzRecordKey,Set) using SzFlag.SZ_ENTITY_DEFAULT_FLAGS as the value for the flags parameter. See the getEntity(SzRecordKey, Set) documentation for details.

      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"));

    // 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 constituent record for the entity to retrieve.
      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:

    • findInterestingEntities Link icon

      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 only flags belonging to the SzFlagUsageGroup.SZ_FIND_INTERESTING_ENTITIES_FLAGS group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags to supported flags).

      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_FIND_INTERESTING_ENTITIES_DEFAULT_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 belonging to the SzFlagUsageGroup.SZ_FIND_INTERESTING_ENTITIES_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_INTERESTING_ENTITIES_DEFAULT_FLAGS for the default recommended flags.
      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.
      See Also:

    • findInterestingEntities Link icon

      default String findInterestingEntities(long entityId) throws SzNotFoundException, SzException
      Convenience method for calling findInterestingEntities(long, Set) with SzFlag.SZ_FIND_INTERESTING_ENTITIES_DEFAULT_FLAGS as the value for the flags parameter. See the findInterestingEntities(long, Set) documentation for details.

      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);

    // 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.
      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.
      See Also:

    • findInterestingEntities Link icon

      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 only flags belonging to the SzFlagUsageGroup.SZ_FIND_INTERESTING_ENTITIES_FLAGS group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags to supported flags).

      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_FIND_INTERESTING_ENTITIES_DEFAULT_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 constituent record for the entity that is the focus for the interesting entities to be returned.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_FIND_INTERESTING_ENTITIES_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_INTERESTING_ENTITIES_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The JSON String describing the interesting entities.
      Throws:
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzNotFoundException - If no record could be found with the specified record ID.
      SzException - If a failure occurs.
      See Also:

    • findInterestingEntities Link icon

      default String findInterestingEntities(SzRecordKey recordKey) throws SzUnknownDataSourceException, SzNotFoundException, SzException
      Convenience method for calling findInterestingEntities(SzRecordKey, Set) with SzFlag.SZ_FIND_INTERESTING_ENTITIES_DEFAULT_FLAGS as the value for the flags parameter. See the findInterestingEntities(SzRecordKey, Set) documentation for details.

      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"));

    // 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 constituent record for the entity that is the focus for the interesting entities to be returned.
      Returns:
      The JSON String describing the interesting entities.
      Throws:
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzNotFoundException - If no record could be found with the specified record ID.
      SzException - If a failure occurs.
      See Also:

    • findPath Link icon

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

    • findPath Link icon

      default String findPath(long startEntityId, long endEntityId, int maxDegrees, SzEntityIds avoidEntityIds, Set<String> requiredDataSources) throws SzNotFoundException, SzUnknownDataSourceException, SzException
      Convenience method for calling findPath(long, long, int, SzEntityIds, Set, Set) using SzFlag.SZ_FIND_PATH_DEFAULT_FLAGS as the value for the flags parameter. See the findPath(long, long, int, SzEntityIds, Set, Set) documentation for details.

      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);

    // 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.
      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:

    • findPath Link icon

      default String findPath(long startEntityId, long endEntityId, int maxDegrees, Set<SzFlag> flags) throws SzNotFoundException, SzUnknownDataSourceException, SzException
      Convenience method for calling findPath(long, long, int, SzEntityIds, Set, Set) using null as the value for both the "avoid entity ID's" and the "required data sources" parameters. See the findPath(long, long, int, SzEntityIds, Set, Set) documentation for details.

      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;

    // retrieve the entity path using the entity ID's
    String responseJson = engine.findPath(startEntityId,
                                          endEntityId,
                                          maxDegrees,
                                          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.
      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:

    • findPath Link icon

      default String findPath(long startEntityId, long endEntityId, int maxDegrees) throws SzNotFoundException, SzUnknownDataSourceException, SzException
      Convenience method for calling findPath(long, long, int, SzEntityIds, Set, Set) using null as the value for both the "avoid entity ID's" and the "required data sources" parameters and SzFlag.SZ_FIND_PATH_DEFAULT_FLAGS as the value for the flags parameter. See the findPath(long, long, int, SzEntityIds, Set, Set) documentation for details.

      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;

    // retrieve the entity path using the entity ID's
    String responseJson = engine.findPath(startEntityId,
                                          endEntityId,
                                          maxDegrees);

    // 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.
      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:

    • findPath Link icon

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

    • findPath Link icon

      default String findPath(SzRecordKey startRecordKey, SzRecordKey endRecordKey, int maxDegrees, SzRecordKeys avoidRecordKeys, Set<String> requiredDataSources) throws SzNotFoundException, SzUnknownDataSourceException, SzException
      Convenience method for calling findPath(SzRecordKey, SzRecordKey, int, SzRecordKeys, Set, Set) using SzFlag.SZ_FIND_PATH_DEFAULT_FLAGS as the value for the flags parameter. See the findPath(SzRecordKey, SzRecordKey, int, SzRecordKeys, Set, Set) documentation for details.

      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);

    // 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.
      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:

    • findPath Link icon

      default String findPath(SzRecordKey startRecordKey, SzRecordKey endRecordKey, int maxDegrees, Set<SzFlag> flags) throws SzNotFoundException, SzUnknownDataSourceException, SzException
      Convenience method for calling findPath(SzRecordKey, SzRecordKey, int, SzRecordKeys, Set, Set) using null as the value for both the "avoid record keys" and the "required data sources" parameters. See the findPath(SzRecordKey, SzRecordKey, int, SzRecordKeys, Set, Set) documentation for details.

      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;

    // retrieve the entity path using the record keys
    String responseJson = engine.findPath(startRecordKey,
                                          endRecordKey,
                                          maxDegrees,
                                          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.
      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:

    • findPath Link icon

      default String findPath(SzRecordKey startRecordKey, SzRecordKey endRecordKey, int maxDegrees) throws SzNotFoundException, SzUnknownDataSourceException, SzException
      Convenience method for calling findPath(SzRecordKey, SzRecordKey, int, SzRecordKeys, Set, Set) using null as the value for both the "avoid record keys" and the "required data sources" parameters and SzFlag.SZ_FIND_PATH_DEFAULT_FLAGS as the value for the flags parameter. See the findPath(SzRecordKey, SzRecordKey, int, SzRecordKeys, Set, Set) documentation for details.

      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;

    // retrieve the entity path using the record keys
    String responseJson = engine.findPath(startRecordKey,
                                          endRecordKey,
                                          maxDegrees);

    // 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.
      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:

    • findNetwork Link icon

      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:

    • findNetwork Link icon

      default String findNetwork(SzEntityIds entityIds, int maxDegrees, int buildOutDegrees, int buildOutMaxEntities) throws SzNotFoundException, SzException
      Convenience method for calling findNetwork(SzEntityIds, int, int, int, Set) with SzFlag.SZ_FIND_NETWORK_DEFAULT_FLAGS as the value for the flags parameter. See the findNetwork(SzEntityIds, int, int, int, Set) documentation for details.

      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);

    // 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.
      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:

    • findNetwork Link icon

      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 network 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 constituent 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:

    • findNetwork Link icon

      default String findNetwork(SzRecordKeys recordKeys, int maxDegrees, int buildOutDegrees, int buildOutMaxEntities) throws SzUnknownDataSourceException, SzNotFoundException, SzException
      Convenience method for calling findNetwork(SzRecordKeys, int, int, int, Set) with SzFlag.SZ_FIND_NETWORK_DEFAULT_FLAGS as the value for the flags parameter. See the findNetwork(SzRecordKeys, int, int, int, Set) documentation for details.

      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 network using the record keys
    String responseJson = engine.findNetwork(SzRecordKeys.of(recordKeys),
                                             maxDegrees,
                                             buildOutDegrees,
                                             buildOutMaxEntities);

    // 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 constituent 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.
      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:

    • whyRecordInEntity Link icon

      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_RECORD_IN_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 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_RECORD_IN_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_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:

    • whyRecordInEntity Link icon

      default String whyRecordInEntity(SzRecordKey recordKey) throws SzUnknownDataSourceException, SzNotFoundException, SzException
      Convenience method for calling whyRecordInEntity(SzRecordKey, Set) with SzFlag.SZ_WHY_RECORD_IN_ENTITY_DEFAULT_FLAGS as the value for the flags parameter. See the whyRecordInEntity(SzRecordKey, Set) documentation for details.

      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"));

    // 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.
      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:

    • whyRecords Link icon

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

    • whyRecords Link icon

      default String whyRecords(SzRecordKey recordKey1, SzRecordKey recordKey2) throws SzUnknownDataSourceException, SzNotFoundException, SzException
      Convenience method for calling whyRecords(SzRecordKey, SzRecordKey, Set) with SzFlag.SZ_WHY_RECORDS_DEFAULT_FLAGS as the value for the flags parameter. See the whyRecordInEntity(SzRecordKey, Set) documentation for details.

      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);

    // 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.
      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:

    • whyEntities Link icon

      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_ENTITIES_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 entity ID.", e);

} catch (SzException e) {
    // handle or rethrow the exception
    logError("Failed to perform why entities.", 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_ENTITIES_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:

    • whyEntities Link icon

      default String whyEntities(long entityId1, long entityId2) throws SzNotFoundException, SzException
      Convenience method for calling whyEntities(long, long, Set) with SzFlag.SZ_WHY_ENTITIES_DEFAULT_FLAGS as the value for the flags parameter. See the whyEntities(long, long, Set) documentation for details.

      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);

    // 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 entity ID.", e);

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

      Parameters:
      entityId1 - The entity ID of the first entity.
      entityId2 - The entity ID of the second entity.
      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:

    • howEntity Link icon

      String howEntity(long entityId, Set<SzFlag> flags) throws SzNotFoundException, SzException
      Determines 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:

    • howEntity Link icon

      default String howEntity(long entityId) throws SzNotFoundException, SzException
      Convenience method for calling howEntity(long, Set) using SzFlags.SZ_HOW_ENTITY_DEFAULT_FLAGS as the value for the flags parameter. See the howEntity(long, Set) documentation for details.

      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);

    // 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.
      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:

    • getVirtualEntity Link icon

      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:

    • getVirtualEntity Link icon

      default String getVirtualEntity(Set<SzRecordKey> recordKeys) throws SzNotFoundException, SzException
      Convenience method for calling getVirtualEntity(Set, Set) using SzFlag.SZ_VIRTUAL_ENTITY_DEFAULT_FLAGS as the value for the flags parameter. See the getVirtualEntity(Set, Set) documentation for details.

      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);

    // 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.
      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:

    • getRecord Link icon

      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:

    • getRecord Link icon

      default String getRecord(SzRecordKey recordKey) throws SzUnknownDataSourceException, SzNotFoundException, SzException
      Convenience method for calling getRecord(SzRecordKey, Set) using SzFlag.SZ_RECORD_DEFAULT_FLAGS as the value for the flags parameter.

      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"));

    // 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.
      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:

    • exportJsonEntityReport Link icon

      long exportJsonEntityReport(Set<SzFlag> flags) throws SzException
      Initiates 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 perform JSON export.", 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:

    • exportJsonEntityReport Link icon

      default long exportJsonEntityReport() throws SzException
      Convenience method for calling exportJsonEntityReport(Set) using SzFlag.SZ_EXPORT_DEFAULT_FLAGS as the value for the flags parameter. See the exportJsonEntityReport(Set) documentation for details.

      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();

    // 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 perform JSON export.", e);
}

      Returns:
      The export handle to use for retrieving the export data.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • exportCsvEntityReport Link icon

      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 perform CSV export.", e);
}

      Parameters:
      csvColumnList - Specify "*" to indicate "all columns", specify empty-string to indicate the "standard columns", otherwise specify a comma-separated 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:

    • exportCsvEntityReport Link icon

      default long exportCsvEntityReport(String csvColumnList) throws SzException
      Convenience method for calling exportCsvEntityReport(String, Set) using SzFlag.SZ_EXPORT_DEFAULT_FLAGS as the value for the flags parameter. See the exportCsvEntityReport(String, Set) documentation for details.

      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("*");

    // 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 perform CSV export.", e);
}

      Parameters:
      csvColumnList - Specify "*" to indicate "all columns", specify empty-string to indicate the "standard columns", otherwise specify a comma-separated list of column names.
      Returns:
      The export handle to use for retrieving the export data.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • fetchNext Link icon

      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 perform JSON export.", 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 perform CSV export.", 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:

    • closeExport Link icon

      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 perform JSON export.", 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 perform CSV export.", e);
}

      Parameters:
      exportHandle - The export handle of the export to close.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • processRedoRecord Link icon

      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_REDO_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_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 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_REDO_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_WITH_INFO_FLAGS for an INFO response. SzFlag.SZ_REDO_DEFAULT_FLAGS is also available if you desire to use the recommended defaults.
      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:

    • processRedoRecord Link icon

      default String processRedoRecord(String redoRecord) throws SzException
      Convenience method for calling processRedoRecord(String, Set) using SzFlag.SZ_REDO_DEFAULT_FLAGS as the value for the flags parameter.

      NOTE: The String return type is still used despite the fact that in the current version this will always return null due to SzFlag.SZ_REDO_DEFAULT_FLAGS being equivalent to SzFlag.SZ_NO_FLAGS. However, having a void return type would cause incompatibilities if a future release introduced a different value for SzFlag.SZ_REDO_DEFAULT_FLAGS that did trigger a non-null return value.

      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
                engine.processRedoRecord(redoRecord);

            } 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.
      Returns:
      The JSON String result produced by processing the redo record in the repository, which will always be null in the current version (see above).
      Throws:
      SzException - If a failure occurs.
      See Also:

    • getRedoRecord Link icon

      String getRedoRecord() throws SzException
      Retrieves a pending redo record from the reevaluation queue. If no redo records are available 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_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 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:

    • countRedoRecords Link icon

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