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

      Usage:

      // How to load a record
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get a record definition (varies by application)
          String recordDefinition =
                  """
                  {
                      "DATA_SOURCE": "TEST",
                      "RECORD_ID": "ABC123",
                      "NAME_FULL": "Joe Schmoe",
                      "PHONE_NUMBER": "702-555-1212",
                      "EMAIL_ADDRESS": "joeschmoe@nowhere.com"
                  }
                  """;
      
          // add the record to the repository
          String infoJson = engine.addRecord(
              SzRecordKey.of("TEST", "ABC123"),
              recordDefinition,
              SZ_WITH_INFO_FLAGS);
      
          // do something with the "info JSON" (varies by application)
          JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject();
          if (jsonObject.containsKey("AFFECTED_ENTITIES")) {
              JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES");
              for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) {
                  long affectedId = affected.getJsonNumber("ENTITY_ID").longValue();
      
                  ...
              }
          }
      
      } catch (SzUnknownDataSourceException e) {
          // handle the unknown data source exception
          logError("Expected data source is not configured.", e);
      
      } catch (SzException e) {
          // handle or rethrow the exception
          logError("Failed to add record.", e);
      }
      

      Parameters:
      recordKey - The non-null SzRecordKey that specifies the data source code and record ID of the record being added.
      recordDefinition - The String that defines the record, typically in JSON format.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_MODIFY_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS. Specify SzFlag.SZ_WITH_INFO_FLAGS for an INFO response.
      Returns:
      The JSON String result produced by adding the record to the repository, or null if the specified flags do not indicate that an INFO message should be returned.
      Throws:
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzBadInputException - If the specified record definition has a data source or record ID value that conflicts with the specified data source code and/or record ID values.
      SzException - If a failure occurs.
      See Also:
    • 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_RECORD_FLAGS group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

      Usage:

      // How to pre-process a record
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get a record definition (varies by application)
          String recordDefinition =
                  """
                  {
                      "DATA_SOURCE": "TEST",
                      "RECORD_ID": "DEF456",
                      "NAME_FULL": "John Doe",
                      "PHONE_NUMBER": "702-555-1212",
                      "EMAIL_ADDRESS": "johndoe@nowhere.com"
                  }
                  """;
      
          // set up flags for the preprocess call (varies by application)
          Set<SzFlag> flags = EnumSet.of(SZ_ENTITY_INCLUDE_RECORD_FEATURE_DETAILS,
                                         SZ_ENTITY_INCLUDE_RECORD_FEATURE_STATS);
      
          // preprocess the record
          String responseJson = engine.preprocessRecord(recordDefinition, flags);
      
          // do something with the response JSON (varies by application)
          JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject();
      
          if (jsonObject.containsKey("FEATURES")) {
              JsonObject featuresObj = jsonObject.getJsonObject("FEATURES");
              featuresObj.forEach((featureName, jsonValue) -> {
                  ...
              });
          }
      
      } catch (SzException e) {
          // handle or rethrow the exception
          logError("Failed to preprocess record.", e);
      }
      

      Parameters:
      recordDefinition - The String that defines the record, typically in JSON format.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_RECORD_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_RECORD_DEFAULT_FLAGS.
      Returns:
      The JSON String result produced by preprocessing the record (depending on the specified flags).
      Throws:
      SzException - If a failure occurs.
      See Also:
    • 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_MODIFY_FLAGS group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

      Usage:

      // How to delete a record
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // delete the record from the repository
          String infoJson = engine.deleteRecord(
              SzRecordKey.of("TEST", "ABC123"),
              SZ_WITH_INFO_FLAGS);
      
          // do something with the "info JSON" (varies by application)
          JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject();
          if (jsonObject.containsKey("AFFECTED_ENTITIES")) {
              JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES");
              for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) {
                  long affectedId = affected.getJsonNumber("ENTITY_ID").longValue();
      
                  ...
              }
          }
      
      } catch (SzUnknownDataSourceException e) {
          // handle the unknown data source exception
          logError("Expected data source is not configured.", e);
      
      } catch (SzException e) {
          // handle or rethrow the exception
          logError("Failed to delete record.", e);
      }
      

      Parameters:
      recordKey - The non-null SzRecordKey that specifies the data source code and record Id of the record to delete.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_MODIFY_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS. Specify SzFlag.SZ_WITH_INFO_FLAGS for an INFO response.
      Returns:
      The JSON String result produced by deleting the record from the repository, or null if the specified flags do not indicate that an INFO message should be returned.
      Throws:
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzException - If a failure occurs.
      See Also:
    • 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_MODIFY_FLAGS group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

      Usage:

      // How to reevaluate a record
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // reevaluate a record in the repository
          String infoJson = engine.reevaluateRecord(
              SzRecordKey.of("TEST", "ABC123"),
              SZ_WITH_INFO_FLAGS);
      
          // do something with the "info JSON" (varies by application)
          JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject();
          if (jsonObject.containsKey("AFFECTED_ENTITIES")) {
              JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES");
              for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) {
                  long affectedId = affected.getJsonNumber("ENTITY_ID").longValue();
      
                  ...
              }
          }
      
      } catch (SzUnknownDataSourceException e) {
          // handle the unknown data source exception
          logError("Expected data source is not configured.", e);
      
      } catch (SzException e) {
          // handle or rethrow the exception
          logError("Failed to reevaluate record.", e);
      }
      

      Parameters:
      recordKey - The non-null SzRecordKey that specifies the data source code and record Id of the record to reevaluate.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_MODIFY_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS. Specify SzFlag.SZ_WITH_INFO_FLAGS for an INFO response.
      Returns:
      The JSON String result produced by reevaluating the record in the repository, or null if the specified flags do not indicate that an INFO message should be returned.
      Throws:
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzException - If a failure occurs.
      See Also:
    • 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_MODIFY_FLAGS group will be recognized (other SzFlag instances will be ignored). NOTE: EnumSet offers an efficient means of constructing a Set of SzFlag.

      Usage:

      // How to reevaluate an entity
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get the ID of an entity to reevaluate (varies by application)
          long entityId = getEntityId();
      
          // reevaluate an entity in the repository
          String infoJson = engine.reevaluateEntity(entityId, SZ_WITH_INFO_FLAGS);
      
          // do something with the "info JSON" (varies by application)
          JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject();
          if (jsonObject.containsKey("AFFECTED_ENTITIES")) {
              JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES");
              for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) {
                  long affectedId = affected.getJsonNumber("ENTITY_ID").longValue();
      
                  ...
              }
          }
      
      } catch (SzException e) {
          // handle or rethrow the exception
          logError("Failed to reevaluate entity.", e);
      }
      

      Parameters:
      entityId - The ID of the resolved entity to reevaluate.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_MODIFY_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS. Specify SzFlag.SZ_WITH_INFO_FLAGS for an INFO response.
      Returns:
      The JSON String result produced by reevaluating the entity in the repository, or null if the specified flags do not indicate that an INFO message should be returned.
      Throws:
      SzException - If a failure occurs.
      See Also:
    • 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

      String searchByAttributes(String attributes, Set<SzFlag> flags) throws SzException
      This method is equivalent to calling searchByAttributes(String, String, Set) with a null value for the search profile parameter. See searchByAttributes(String, String, Set) documentation for details.

      Usage:

      // How to search for entities matching criteria
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get the search attributes (varies by application)
          String searchAttributes =
                  """
                  {
                      "NAME_FULL": "Joe Schmoe",
                      "PHONE_NUMBER": "702-555-1212",
                      "EMAIL_ADDRESS": "joeschmoe@nowhere.com"
                  }
                  """;
      
          // search for matching entities in the repository
          String responseJson = engine.searchByAttributes(
              searchAttributes,
              SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS);
      
          // do something with the response JSON (varies by application)
          JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject();
          if (jsonObject.containsKey("RESOLVED_ENTITIES")) {
              JsonArray resultsArr = jsonObject.getJsonArray("RESOLVED_ENTITIES");
              for (JsonObject result : resultsArr.getValuesAs(JsonObject.class)) {
                  // get the match info for the result
                  JsonObject matchInfo = result.getJsonObject("MATCH_INFO");
      
                  ...
      
                  // get the entity for the result
                  JsonObject  entityInfo  = result.getJsonObject("ENTITY");
                  JsonObject  entity      = entityInfo.getJsonObject("RESOLVED_ENTITY");
                  long        entityId    = entity.getJsonNumber("ENTITY_ID").longValue();
      
                  ...
              }
          }
      
      } catch (SzException e) {
          // handle or rethrow the exception
          logError("Failed to search for entities.", e);
      }
      

      Parameters:
      attributes - The search attributes defining the hypothetical record to match and/or relate to in order to obtain the search results.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_SEARCH_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The resulting JSON String describing the result of the search.
      Throws:
      SzException - If a failure occurs.
      See Also:
    • 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

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

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

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

      Usage:

      // How to retrieve an entity via its record key
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // retrieve the entity by record key
          String responseJson = engine.getEntity(
              SzRecordKey.of("TEST", "ABC123"),
              SZ_ENTITY_DEFAULT_FLAGS);
      
          // do something with the response JSON (varies by application)
          JsonObject  jsonObject  = Json.createReader(new StringReader(responseJson)).readObject();
          JsonObject  entity      = jsonObject.getJsonObject("RESOLVED_ENTITY");
          String      entityName  = entity.getString("ENTITY_NAME");
      
          ...
      
          if (jsonObject.containsKey("RECORDS")) {
              JsonArray recordArr = jsonObject.getJsonArray("RECORDS");
              for (JsonObject record : recordArr.getValuesAs(JsonObject.class)) {
                  String dataSource = record.getString("DATA_SOURCE");
                  String recordId   = record.getString("RECORD_ID");
      
                  ...
              }
          }
      
      } catch (SzUnknownDataSourceException e) {
          // handle the unknown data source exception
          logError("Expected data source is not configured.", e);
      
      } catch (SzNotFoundException e) {
          // handle the not-found exception
          logError("Entity not found for record key.", e);
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to retrieve entity by record key.", e);
      }
      

      Parameters:
      recordKey - The non-null SzRecordKey that specifies the data source code and record Id of the consituent record for the entity to retrieve.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_ENTITY_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_ENTITY_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The JSON String describing the entity.
      Throws:
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzNotFoundException - If no entity could be found with the specified entity ID.
      SzException - If a failure occurs.
      See Also:
    • 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 currenlty no flags are specifically defined for this experimental method. Flags that are not applicable to this method will simply be ignored.

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

      Usage:

      // How to find interesting entities related to an entity via entity ID
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get the ID of an entity to retrieve (varies by application)
          long entityId = getEntityId();
      
          // find the interesting entities by entity ID
          String responseJson = engine.findInterestingEntities(entityId, SZ_NO_FLAGS);
      
          // do something with the response JSON (varies by application)
          JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject();
      
          ...
      
      } catch (SzNotFoundException e) {
          // handle the not-found exception
          logError("Entity not found for entity ID.", e);
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to find interesting entities by entity ID.", e);
      }
      

      Parameters:
      entityId - The entity ID identifying the entity that will be the focus for the interesting entities to be returned.
      flags - The optional Set of SzFlag instances for the operation, though no flags are currently defined for this experimental method.
      Returns:
      The JSON String describing the interesting entities.
      Throws:
      SzNotFoundException - If no entity could be found with the specified entity ID.
      SzException - If a failure occurs.
    • findInterestingEntities 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 currenlty no flags are specifically defined for this experimental method. Flags that are not applicable to this method will simply be ignored.

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

      Usage:

      // How to find interesting entities related to an entity via record key
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // retrieve the entity by record key
          String responseJson = engine.findInterestingEntities(
              SzRecordKey.of("TEST", "ABC123"),
              SZ_NO_FLAGS);
      
          // do something with the response JSON (varies by application)
          JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject();
      
          ...
      
      } catch (SzUnknownDataSourceException e) {
          // handle the unknown data source exception
          logError("Expected data source is not configured.", e);
      
      } catch (SzNotFoundException e) {
          // handle the not-found exception
          logError("Entity not found for record key.", e);
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to find interesting entities by record key.", e);
      }
      

      Parameters:
      recordKey - The non-null SzRecordKey that specifies the data source code and record Id of the consituent record for the entity that is the focus for the interesting entities to be returned.
      flags - The optional Set of SzFlag instances for the operation, though no flags are currently defined for this experimental method.
      Returns:
      The JSON String describing the interesting entities.
      Throws:
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzNotFoundException - If no reord could be found with the specified record ID.
      SzException - If a failure occurs.
    • findPath 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 neccessary to find the path. To strictly avoid the specified entities specify the SzFlag.SZ_FIND_PATH_STRICT_AVOID flag.

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

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

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

      Usage:

      // How to find an entity path using entity ID's
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get entity ID's for the path endpoints (varies by application)
          long startEntityId = getPathStartEntityId();
          long endEntityId   = getPathEndEntityId();
      
          // determine the maximum path degrees (varies by application)
          int maxDegrees = 4;
      
          // determine any entities to be avoided (varies by application)
          Set<Long> avoidEntities = getPathAvoidEntityIds();
      
          // determine any data sources to require in the path (varies by application)
          Set<String> requiredSources = null;
      
          // retrieve the entity path using the entity ID's
          String responseJson = engine.findPath(startEntityId,
                                                endEntityId,
                                                maxDegrees,
                                                SzEntityIds.of(avoidEntities),
                                                requiredSources,
                                                SZ_FIND_PATH_DEFAULT_FLAGS);
      
          // do something with the response JSON (varies by application)
          JsonObject  jsonObject  = Json.createReader(new StringReader(responseJson)).readObject();
          JsonArray   pathArr     = jsonObject.getJsonArray("ENTITY_PATHS");
          for (JsonObject path : pathArr.getValuesAs(JsonObject.class)) {
              JsonArray entityIds = path.getJsonArray("ENTITIES");
      
              for (JsonNumber number : entityIds.getValuesAs(JsonNumber.class)) {
                  long entityId = number.longValue();
      
                  ...
              }
          }
      
      } catch (SzUnknownDataSourceException e) {
          // handle the unknown data source exception
          logError("Expected data source is not configured.", e);
      
      } catch (SzNotFoundException e) {
          // handle the not-found exception
          logError("Entity not found for entity ID.", e);
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to retrieve entity path by entity ID.", e);
      }
      

      Parameters:
      startEntityId - The entity ID of the first entity.
      endEntityId - The entity ID of the second entity.
      maxDegrees - The maximum number of degrees for the path search.
      avoidEntityIds - The optional SzEntityIds describing the Set of non-null Long entity ID's identifying entities to be avoided when finding the path, or null if no entities are to be avoided.
      requiredDataSources - The optional Set of non-null String data source codes identifying the data sources for which at least one record must be included on the path, or null if none are required.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_FIND_PATH_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_FIND_PATH_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The JSON String describing the resultant entity path which may be an empty path if no path exists between the two entities given the path parameters.
      Throws:
      SzNotFoundException - If either the path-start or path-end entities for the specified entity ID's cannot be found.
      SzUnknownDataSourceException - If an unrecognized required data source is specified.
      SzException - If a failure occurs.
      See Also:
    • 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 neccessary to find the path. To strictly avoid the associated entities specify the SzFlag.SZ_FIND_PATH_STRICT_AVOID flag.

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

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

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

      Usage:

      // How to find an entity path using record keys
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get entity ID's for the path endpoints (varies by application)
          SzRecordKey startRecordKey = getPathStartRecordKey();
          SzRecordKey endRecordKey   = getPathEndRecordKey();
      
          // determine the maximum path degrees (varies by application)
          int maxDegrees = 4;
      
          // determine any records to be avoided (varies by application)
          Set<SzRecordKey> avoidRecords = getPathAvoidRecordKeys();
      
          // determine any data sources to require in the path (varies by application)
          Set<String> requiredSources = null;
      
          // retrieve the entity path using the record keys
          String responseJson = engine.findPath(startRecordKey,
                                                endRecordKey,
                                                maxDegrees,
                                                SzRecordKeys.of(avoidRecords),
                                                requiredSources,
                                                SZ_FIND_PATH_DEFAULT_FLAGS);
      
          // do something with the response JSON (varies by application)
          JsonObject  jsonObject  = Json.createReader(new StringReader(responseJson)).readObject();
          JsonArray   pathArr     = jsonObject.getJsonArray("ENTITY_PATHS");
          for (JsonObject path : pathArr.getValuesAs(JsonObject.class)) {
              JsonArray entityIds = path.getJsonArray("ENTITIES");
      
              for (JsonNumber number : entityIds.getValuesAs(JsonNumber.class)) {
                  long entityId = number.longValue();
      
                  ...
              }
          }
      
      } catch (SzUnknownDataSourceException e) {
          // handle the unknown data source exception
          logError("Expected data source is not configured.", e);
      
      } catch (SzNotFoundException e) {
          // handle the not-found exception
          logError("Entity not found for record key.", e);
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to retrieve entity path by record key.", e);
      }
      

      Parameters:
      startRecordKey - The SzRecordKey containing the data source code and record ID identifying the record at the start of the path.
      endRecordKey - The SzRecordKey containing the data source code and record ID identifying the record at the end of the path.
      maxDegrees - The maximum number of degrees for the path search.
      avoidRecordKeys - The optional SzRecordKeys describing the Set of non-null SzRecordKey instances providing the data source code and record ID pairs of the records whose entities are to be avoided when finding the path, or null if no entities identified by are to be avoided.
      requiredDataSources - The optional Set of non-null String data source codes identifying the data sources for which at least one record must be included on the path, or null if none are required.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_FIND_PATH_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_FIND_PATH_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The JSON String describing the resultant entity path which may be an empty path if no path exists between the two entities given the path parameters.
      Throws:
      SzNotFoundException - If either the path-start or path-end records for the specified data source code and record ID pairs cannot be found.
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzException - If a failure occurs.
      See Also:
    • 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

      String findNetwork(SzRecordKeys recordKeys, int maxDegrees, int buildOutDegrees, int buildOutMaxEntities, Set<SzFlag> flags) throws SzUnknownDataSourceException, SzNotFoundException, SzException
      Finds a network of entity relationships surrounding the paths between a set of entities having the constituent records identified by the data source code and record ID pairs contained in the specified instance of SzRecordKeys -- which is a Set of one or more non-null SzRecordKey instances.

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

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

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

      Usage:

      // How to find an entity network using record keys
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get entity ID's for the path endpoints (varies by application)
          Set<SzRecordKey> recordKeys = getNetworkRecordKeys();
      
          // determine the maximum path degrees (varies by application)
          int maxDegrees = 3;
      
          // determine the degrees to build-out the network (varies by application)
          int buildOutDegrees = 0;
      
          // determine the max entities to build-out (varies by application)
          int buildOutMaxEntities = 10;
      
          // retrieve the entity newtwork using the record keys
          String responseJson = engine.findNetwork(SzRecordKeys.of(recordKeys),
                                                   maxDegrees,
                                                   buildOutDegrees,
                                                   buildOutMaxEntities,
                                                   SZ_FIND_NETWORK_DEFAULT_FLAGS);
      
          // do something with the response JSON (varies by application)
          JsonObject  jsonObject  = Json.createReader(new StringReader(responseJson)).readObject();
          JsonArray   pathArr     = jsonObject.getJsonArray("ENTITY_PATHS");
          for (JsonObject path : pathArr.getValuesAs(JsonObject.class)) {
              long      startEntityId = path.getJsonNumber("START_ENTITY_ID").longValue();
              long      endEntityId   = path.getJsonNumber("END_ENTITY_ID").longValue();
              JsonArray entityPathIds = path.getJsonArray("ENTITIES");
      
              for (JsonNumber number : entityPathIds.getValuesAs(JsonNumber.class)) {
                  long entityId = number.longValue();
      
                  ...
              }
          }
      
      } catch (SzUnknownDataSourceException e) {
          // handle the unknown data source exception
          logError("Expected data source is not configured.", e);
      
      } catch (SzNotFoundException e) {
          // handle the not-found exception
          logError("Entity not found for record key.", e);
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to retrieve entity network.", e);
      }
      

      Parameters:
      recordKeys - The SzRecordKeys describing the Set of non-null SzRecordKey instances providing the data source code and record ID pairs for the consituent records of the entities for which to build the network.
      maxDegrees - The maximum number of degrees for the path search between the specified entities.
      buildOutDegrees - The number of relationship degrees to build out from each of the found entities on the network, or zero to prevent network build-out.
      buildOutMaxEntities - The maximum number of entities to build out for the entire network.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_FIND_NETWORK_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_FIND_NETWORK_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The JSON String describing the resultant entity network and the entities on the network.
      Throws:
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzNotFoundException - If any of the records for the specified data source code and record ID pairs cannot be found.
      SzException - If a failure occurs.
      See Also:
    • whyRecordInEntity Link icon

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

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

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

      Usage:

      // How to determine why a record is a member of its respective entity
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // determine why the record is part of its entity
          String responseJson = engine.whyRecordInEntity(
              SzRecordKey.of("TEST", "ABC123"),
              SZ_WHY_RECORD_IN_ENTITY_DEFAULT_FLAGS);
      
          // do something with the response JSON (varies by application)
          JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject();
          JsonArray resultsArr = jsonObject.getJsonArray("WHY_RESULTS");
          for (JsonObject result : resultsArr.getValuesAs(JsonObject.class)) {
              long entityId = result.getJsonNumber("ENTITY_ID").longValue();
      
              ...
          }
      
      } catch (SzUnknownDataSourceException e) {
          // handle the unknown data source exception
          logError("Expected data source is not configured.", e);
      
      } catch (SzNotFoundException e) {
          // handle the not-found exception
          logError("Entity not found for record key.", e);
      
      } catch (SzException e) {
          // handle or rethrow the exception
          logError("Failed to reevaluate record.", e);
      }
      

      Parameters:
      recordKey - The SzRecordKey that has the data source code and record ID identifying the record.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_WHY_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_WHY_RECORD_IN_ENTITY_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The JSON String describing why the record is included in its respective entity.
      Throws:
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzNotFoundException - If any of the records for the specified data source code and record ID pairs cannot be found.
      SzException - If a failure occurs.
      See Also:
    • whyRecords Link icon

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

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

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

      Usage:

      // How to determine how two records are related
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get the records on which to operate (varies by application)
          SzRecordKey recordKey1 = getWhyRecordsKey1();
          SzRecordKey recordKey2 = getWhyRecordsKey2();
      
          // determine how the records are related
          String responseJson = engine.whyRecords(recordKey1,
                                                  recordKey2,
                                                  SZ_WHY_RECORDS_DEFAULT_FLAGS);
      
          // do something with the response JSON (varies by application)
          JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject();
          JsonArray resultsArr = jsonObject.getJsonArray("WHY_RESULTS");
          for (JsonObject result : resultsArr.getValuesAs(JsonObject.class)) {
              long entityId1 = result.getJsonNumber("ENTITY_ID").longValue();
              long entityId2 = result.getJsonNumber("ENTITY_ID_2").longValue();
      
              ...
          }
      
      } catch (SzUnknownDataSourceException e) {
          // handle the unknown data source exception
          logError("Expected data source is not configured.", e);
      
      } catch (SzNotFoundException e) {
          // handle the not-found exception
          logError("Entity not found for record key.", e);
      
      } catch (SzException e) {
          // handle or rethrow the exception
          logError("Failed to reevaluate record.", e);
      }
      

      Parameters:
      recordKey1 - The non-null SzRecordKey providing the data source code and record ID for the first record.
      recordKey2 - The non-null SzRecordKey providing the data source code and record ID for the second record.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_WHY_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_WHY_RECORDS_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The JSON String describing the ways in which the records are related to one another.
      Throws:
      SzUnknownDataSourceException - If an unrecognized data source code is specified.
      SzNotFoundException - If either of the records for the specified data source code and record ID pairs cannot be found.
      SzException - If a failure occurs.
      See Also:
    • 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_FLAGS group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

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

      Usage:

      // How to determine how two entities are related
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get the entities on which to operate (varies by application)
          long entityId1 = getWhyEntitiesId1();
          long entityId2 = getWhyEntitiesId2();
      
          // determine how the entities are related
          String responseJson = engine.whyEntities(entityId1,
                                                   entityId2,
                                                   SZ_WHY_ENTITIES_DEFAULT_FLAGS);
      
          // do something with the response JSON (varies by application)
          JsonObject jsonObject = Json.createReader(new StringReader(responseJson)).readObject();
          JsonArray resultsArr = jsonObject.getJsonArray("WHY_RESULTS");
          for (JsonObject result : resultsArr.getValuesAs(JsonObject.class)) {
              long whyEntityId1 = result.getJsonNumber("ENTITY_ID").longValue();
              long whyEntityId2 = result.getJsonNumber("ENTITY_ID_2").longValue();
      
              ...
          }
      
      } catch (SzNotFoundException e) {
          // handle the not-found exception
          logError("Entity not found for record key.", e);
      
      } catch (SzException e) {
          // handle or rethrow the exception
          logError("Failed to reevaluate record.", e);
      }
      

      Parameters:
      entityId1 - The entity ID of the first entity.
      entityId2 - The entity ID of the second entity.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_WHY_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_WHY_ENTITIES_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The JSON String describing the ways in which the entities are related to one another.
      Throws:
      SzNotFoundException - If either of the entities for the specified entity ID's could not be found.
      SzException - If a failure occurs.
      See Also:
    • howEntity Link icon

      String howEntity(long entityId, Set<SzFlag> flags) throws SzNotFoundException, SzException
      Deterimes how an entity identified by the specified entity ID was constructed from its constituent records.

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

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

      Usage:

      // How to retrieve the "how analysis" for an entity via its entity ID
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get the entity ID on which to operate (varies by application)
          long entityId = getEntityId();
      
          // determine how the entity was formed
          String responseJson = engine.howEntity(entityId, SZ_HOW_ENTITY_DEFAULT_FLAGS);
      
          // do something with the response JSON (varies by application)
          JsonObject  jsonObject  = Json.createReader(new StringReader(responseJson)).readObject();
          JsonObject  howResults  = jsonObject.getJsonObject("HOW_RESULTS");
          JsonArray   stepsArr    = howResults.getJsonArray("RESOLUTION_STEPS");
      
          for (JsonObject step : stepsArr.getValuesAs(JsonObject.class)) {
              JsonObject matchInfo = step.getJsonObject("MATCH_INFO");
      
              ...
          }
      
      } catch (SzNotFoundException e) {
          // handle the not-found exception
          logError("Entity not found for entity ID.", e);
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to retrieve how analysis.", e);
      }
      

      Parameters:
      entityId - The entity ID of the entity.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_HOW_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_HOW_ENTITY_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The JSON String describing the how the entity was constructed.
      Throws:
      SzNotFoundException - If the entity for the specified entity ID could not be found.
      SzException - If a failure occurs.
      See Also:
    • 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:
    • getRecord Link icon

      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:
    • exportJsonEntityReport Link icon

      long exportJsonEntityReport(Set<SzFlag> flags) throws SzException
      Iniitiates an export of entity data as JSON-lines format and returns an "export handle" that can be used to read the export data and must be closed when complete. Each output line contains the exported entity data for a single resolved entity.

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

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

      Usage:

      // How to export entity data in JSON format
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // export the JSON data
          long exportHandle = engine.exportJsonEntityReport(SZ_EXPORT_DEFAULT_FLAGS);
      
          // read the data
          try {
              // fetch the first JSON record
              String jsonData = engine.fetchNext(exportHandle);
      
              while (jsonData != null) {
                  // parse the JSON data
                  JsonObject jsonObject = Json.createReader(new StringReader(jsonData)).readObject();
      
                  // do something with the parsed data (varies by application)
                  processJsonRecord(jsonObject);
      
                  // fetch the next JSON record
                  jsonData = engine.fetchNext(exportHandle);
              }
      
          } finally {
              // close the export handle
              engine.closeExport(exportHandle);
          }
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to retrieve record by record key.", e);
      }
      

      Parameters:
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_EXPORT_FLAGS group to control how the operation is performed and the content of the export, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_EXPORT_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The export handle to use for retrieving the export data.
      Throws:
      SzException - If a failure occurs.
      See Also:
    • 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 retrieve record by record key.", e);
      }
      

      Parameters:
      csvColumnList - Specify "*" to indicate "all columns", specify empty-string to indicate the "standard columns", otherwise specify a comma-sepatated list of column names.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_EXPORT_FLAGS group to control how the operation is performed and the content of the export, or null to default to SzFlag.SZ_NO_FLAGS or SzFlag.SZ_EXPORT_DEFAULT_FLAGS for the default recommended flags.
      Returns:
      The export handle to use for retrieving the export data.
      Throws:
      SzException - If a failure occurs.
      See Also:
    • 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 retrieve record by record key.", e);
      }
      

      Usage (CSV export):

      // How to export entity data in CSV format
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // export the JSON data
          long exportHandle = engine.exportCsvEntityReport("*", SZ_EXPORT_DEFAULT_FLAGS);
      
          // read the data
          try {
              // fetch the CSV header line from the exported data
              String csvHeaders = engine.fetchNext(exportHandle);
      
              // process the CSV headers (varies by application)
              processCsvHeaders(csvHeaders);
      
              // fetch the first CSV record from the exported data
              String csvRecord = engine.fetchNext(exportHandle);
      
              while (csvRecord != null) {
                  // do something with the exported record (varies by application)
                  processCsvRecord(csvRecord);
      
                  // fetch the next exported CSV record
                  csvRecord = engine.fetchNext(exportHandle);
              }
      
          } finally {
              // close the export handle
              engine.closeExport(exportHandle);
          }
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to retrieve record by record key.", e);
      }
      

      Parameters:
      exportHandle - The export handle to identify the export from which to retrieve the next line of data.
      Returns:
      The next line of export data whose format depends on which function was used to initiate the export, or null if there is no more data to be exported via the specified handle.
      Throws:
      SzException - If a failure occurs.
      See Also:
    • 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 retrieve record by record key.", e);
      }
      

      Usage (CSV export):

      // How to export entity data in CSV format
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // export the JSON data
          long exportHandle = engine.exportCsvEntityReport("*", SZ_EXPORT_DEFAULT_FLAGS);
      
          // read the data
          try {
              // fetch the CSV header line from the exported data
              String csvHeaders = engine.fetchNext(exportHandle);
      
              // process the CSV headers (varies by application)
              processCsvHeaders(csvHeaders);
      
              // fetch the first CSV record from the exported data
              String csvRecord = engine.fetchNext(exportHandle);
      
              while (csvRecord != null) {
                  // do something with the exported record (varies by application)
                  processCsvRecord(csvRecord);
      
                  // fetch the next exported CSV record
                  csvRecord = engine.fetchNext(exportHandle);
              }
      
          } finally {
              // close the export handle
              engine.closeExport(exportHandle);
          }
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to retrieve record by record key.", e);
      }
      

      Parameters:
      exportHandle - The export handle of the export to close.
      Throws:
      SzException - If a failure occurs.
      See Also:
    • 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_MODIFY_FLAGS group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags).

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

      Usage:

      // How to check for and process redo records
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get the redo count
          long redoCount = engine.countRedoRecords();
      
          // check if we have redo records
          if (redoCount > 0L) {
      
              // get the next redo record
              String redoRecord = engine.getRedoRecord();
      
              // loop while we still have redo records
              while (redoRecord != null) {
                  try {
                      // process the redo record
                      String infoJson = engine.processRedoRecord(redoRecord, SZ_ENTITY_DEFAULT_FLAGS);
      
                      // do something with the "info JSON" (varies by application)
                      JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject();
                      if (jsonObject.containsKey("AFFECTED_ENTITIES")) {
                          JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES");
                          for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) {
                              long affectedId = affected.getJsonNumber("ENTITY_ID").longValue();
      
                              ...
                          }
                      }
      
                  } catch (SzException e) {
                      // handle or rethrow the other exceptions
                      logError("Failed to process redo record: " + redoRecord, e);
                  }
      
                  // get the next redo record
                  redoRecord = engine.getRedoRecord();
              }
          }
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to process redos.", e);
      }
      

      Parameters:
      redoRecord - The redo record to be processed.
      flags - The optional Set of SzFlag instances belonging to the SzFlagUsageGroup.SZ_MODIFY_FLAGS group to control how the operation is performed and the content of the response, or null to default to SzFlag.SZ_NO_FLAGS. Specify SzFlag.SZ_WITH_INFO_FLAGS for an INFO response.
      Returns:
      The JSON String result produced by processing the redo record in the repository, or null if the specified flags do not indicate that an INFO message should be returned.
      Throws:
      SzException - If a failure occurs.
      See Also:
    • getRedoRecord Link icon

      String getRedoRecord() throws SzException
      Retrieves a pending redo record from the reevaluation queue. If no redo records are availbale then this returns an null.

      Usage:

      // How to check for and process redo records
      try {
          // obtain the SzEnvironment (varies by application)
          SzEnvironment env = getEnvironment();
      
          // get the engine
          SzEngine engine = env.getEngine();
      
          // get the redo count
          long redoCount = engine.countRedoRecords();
      
          // check if we have redo records
          if (redoCount > 0L) {
      
              // get the next redo record
              String redoRecord = engine.getRedoRecord();
      
              // loop while we still have redo records
              while (redoRecord != null) {
                  try {
                      // process the redo record
                      String infoJson = engine.processRedoRecord(redoRecord, SZ_ENTITY_DEFAULT_FLAGS);
      
                      // do something with the "info JSON" (varies by application)
                      JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject();
                      if (jsonObject.containsKey("AFFECTED_ENTITIES")) {
                          JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES");
                          for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) {
                              long affectedId = affected.getJsonNumber("ENTITY_ID").longValue();
      
                              ...
                          }
                      }
      
                  } catch (SzException e) {
                      // handle or rethrow the other exceptions
                      logError("Failed to process redo record: " + redoRecord, e);
                  }
      
                  // get the next redo record
                  redoRecord = engine.getRedoRecord();
              }
          }
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to process redos.", e);
      }
      

      Returns:
      The retrieved redo record or null if there were no pending redo records.
      Throws:
      SzException - If a failure occurs.
      See Also:
    • 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_ENTITY_DEFAULT_FLAGS);
      
                      // do something with the "info JSON" (varies by application)
                      JsonObject jsonObject = Json.createReader(new StringReader(infoJson)).readObject();
                      if (jsonObject.containsKey("AFFECTED_ENTITIES")) {
                          JsonArray affectedArr = jsonObject.getJsonArray("AFFECTED_ENTITIES");
                          for (JsonObject affected : affectedArr.getValuesAs(JsonObject.class)) {
                              long affectedId = affected.getJsonNumber("ENTITY_ID").longValue();
      
                              ...
                          }
                      }
      
                  } catch (SzException e) {
                      // handle or rethrow the other exceptions
                      logError("Failed to process redo record: " + redoRecord, e);
                  }
      
                  // get the next redo record
                  redoRecord = engine.getRedoRecord();
              }
          }
      
      } catch (SzException e) {
          // handle or rethrow the other exceptions
          logError("Failed to process redos.", e);
      }
      

      Returns:
      The number of redo records pending to be processed.
      Throws:
      SzException - If a failure occurs.
      See Also: