Package com.senzing.sdk

Interface SzConfigManager

public interface SzConfigManager

Defines the Java interface to the Senzing configuration management functions.

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

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

    // get the config manager
    SzConfigManager configMgr = env.getConfigManager();

    ...

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

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    addConfig(String configDefinition, String configComment)
    Adds the configuration described by the specified JSON to the repository with the specified comment and returns the identifier for referencing the the config in the entity repository.
    String
    getConfig(long configId)
    Gets the configuration with the specified config ID and returns the configuration defintion as a String.
    String
    getConfigs()
    Gets the list of saved configuration ID's with their comments and timestamps and return the JSON String describing them.
    long
    getDefaultConfigId()
    Gets the configuration ID of the default configuration for the repository and returns it.
    void
    replaceDefaultConfigId(long currentDefaultConfigId, long newDefaultConfigId)
    Replaces the current configuration ID of the repository with the specified new configuration ID providing the current configuration ID of the repository is equal to the specified old configuration ID.
    void
    setDefaultConfigId(long configId)
    Sets the default configuration for the repository to the specified configuration ID.

  • Method Details

    • addConfig

      long addConfig(String configDefinition, String configComment) throws SzException
      Adds the configuration described by the specified JSON to the repository with the specified comment and returns the identifier for referencing the the config in the entity repository.

      Usage: 

      // How to register a configuration with the Senzing repository
try {
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = getEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.getConfigManager();

    // obtain a JSON config definition (will vary by apppliation)
    String configDefinition = createConfigWithDataSources("CUSTOMERS");

    // register the config with a comment
    long configId = configMgr.addConfig(configDefinition, "Added CUSTOMERS data source");

    // do something with the config ID
    ...

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

      Parameters:
      configDefinition - The JSON text describing the configuration.
      configComment - The comments for the configuration.
      Returns:
      The identifier for referncing the config in the entity repository.
      Throws:
      SzException - If a failure occurs.

    • getConfig

      String getConfig(long configId) throws SzException
      Gets the configuration with the specified config ID and returns the configuration defintion as a String.

      Usage: 

      // How to get a config definition by its configuration ID
try {
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = getEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.getConfigManager();

    // get a valid configuration ID (will vary by apppliation)
    long configId = configMgr.getDefaultConfigId();

    // get the config definition for the config ID
    String configDefinition = configMgr.getConfig(configId);

    // do something with the config definition
    ...

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

      Parameters:
      configId - The configuration ID of the configuration to retrieve.
      Returns:
      The configuration definition as a String.
      Throws:
      SzException - If a failure occurs.

    • getConfigs

      String getConfigs() throws SzException
      Gets the list of saved configuration ID's with their comments and timestamps and return the JSON String describing them. An example format for the response is: 
       {
   "CONFIGS": [
     {
        "CONFIG_ID": 12345678912345,
        "SYS_CREATE_DT": "2021-03-25 18:35:00.743",
        "CONFIG_COMMENTS": "Added EMPLOYEES data source."
     },
     {
        "CONFIG_ID": 23456789123456,
        "SYS_CREATE_DT": "2021-02-08 23:27:09.876",
        "CONFIG_COMMENTS": "Added CUSTOMERS data source."
     },
     {
        "CONFIG_ID": 34567891234567,
        "SYS_CREATE_DT": "2021-02-08 23:27:05.212",
        "CONFIG_COMMENTS": "Initial Config"
     },
     . . .
   ]
 }

      Usage: 

      // How to get a JSON document describing all registered configs
try {
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = getEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.getConfigManager();

    // get the config definition for the config ID
    String configsJson = configMgr.getConfigs();

    // do something with the returned JSON (e.g.: parse it and extract values)
    JsonObject jsonObj = Json.createReader(
        new StringReader(configsJson)).readObject();

    JsonArray jsonArr = jsonObj.getJsonArray("CONFIGS");

    // iterate over the registered configurations
    for (JsonObject configObj : jsonArr.getValuesAs(JsonObject.class)) {
        long    configId    = configObj.getJsonNumber("CONFIG_ID").longValue();
        String  createdOn   = configObj.getString("SYS_CREATE_DT");
        String  comment     = configObj.getString("CONFIG_COMMENTS");

        ...
    }

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

      Returns:
      The JSON String describing the configurations registered in the entity repository with their identifiers, timestamps and comments.
      Throws:
      SzException - If a failure occurs.

    • getDefaultConfigId

      long getDefaultConfigId() throws SzException
      Gets the configuration ID of the default configuration for the repository and returns it. If the entity repository is in the initial state and the default configuration ID has not yet been set, then zero (0) is returned.

      Usage: 

      // How to get the registered default configuration ID
try {
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = getEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.getConfigManager();

    // get the default configuration ID
    long configId = configMgr.getDefaultConfigId();

    // check if no default configuration ID is registered
    if (configId == 0) {
        // handle having no registered configuration ID
        ...
    } else {
        // do something with the configuration ID
        ...
    }

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

      Returns:
      The current default cofiguration ID in the repository, or zero (0) if the entity repository is in the initial state with no default configuration ID having yet been set.
      Throws:
      SzException - If a failure occurs.

    • replaceDefaultConfigId

      void replaceDefaultConfigId(long currentDefaultConfigId, long newDefaultConfigId) throws SzReplaceConflictException, SzException
      Replaces the current configuration ID of the repository with the specified new configuration ID providing the current configuration ID of the repository is equal to the specified old configuration ID. If the current configuration ID is not the same as the specified old configuration ID then this method fails to replace the default configuration ID with the new value and an SzReplaceConflictException is thrown.

      Usage: 

      // How to replace the registered default configuration ID
try {
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = getEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.getConfigManager();

    do {
        // get the current default configuration ID
        long oldConfigId = configMgr.getDefaultConfigId();

        // create a new config (usually modifying the current -- varies by application)
        String configDefinition = addDataSourcesToConfig(oldConfigId, "WATCHLIST");
        long   newConfigId      = configMgr.addConfig(configDefinition, "Added WATCHLIST data source");

        try {
            // replace the default config ID with the new config ID
            configMgr.replaceDefaultConfigId(oldConfigId, newConfigId);

            // if we get here then break out of the loop
            break;

        } catch (SzReplaceConflictException e) {
            // race condition detected
            // do nothing so we loop through and try again
        }

    } while (true);

} catch (SzException e) {
    // handle or rethrow the exception
    logError("Failed to replace default configuration ID.", e);
}

      Parameters:
      currentDefaultConfigId - The configuration ID that is believed to be the current default configuration ID.
      newDefaultConfigId - The new configuration ID for the repository.
      Throws:
      SzReplaceConflictException - If the default configuration ID was not updated to the specified new value because the current default configuration ID found in the repository was not equal to the specified expected current default configuration ID value.
      SzException - If a failure occurs.
      See Also:

    • setDefaultConfigId

      void setDefaultConfigId(long configId) throws SzException
      Sets the default configuration for the repository to the specified configuration ID.

      NOTE: This is best used when initializing the Senzing repository with a registered default config ID the first time (i.e.: when there is no existing default config ID registered). When there is already a default config ID registered, you should consider using replaceDefaultConfigId(long, long) especially if you want to handle race conditions in setting the default config ID.

      Usage: 

      // How to set the registered default configuration ID
try {
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = getEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.getConfigManager();

    // get the configuration ID (varies by application)
    String configDefinition = createConfigWithDataSources("EMPLOYEES");
    long configId = configMgr.addConfig(configDefinition, "Initial config with EMPLOYEES");

    // set the default config ID
    configMgr.setDefaultConfigId(configId);

} catch (SzException e) {
    // handle or rethrow the exception
    logError("Failed to set default configuration ID.", e);
}

      Parameters:
      configId - The configuration ID to set as the default configuration.
      Throws:
      SzException - If a failure occurs.
      See Also: