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
    SzConfig
    createConfig()
    Creates a new SzConfig instance from the template configuration definition.
    SzConfig
    createConfig(long configId)
    Creates a new SzConfig instance for a configuration ID.
    SzConfig
    createConfig(String configDefinition)
    Creates a new SzConfig instance from a configuration definition.
    String
    getConfigRegistry()
    Gets the configuration registry.
    long
    getDefaultConfigId()
    Gets the default configuration ID for the repository.
    long
    registerConfig(String configDefinition)
    Registers a configuration definition in the repository with an auto-generated comment.
    long
    registerConfig(String configDefinition, String configComment)
    Registers a configuration definition in the repository.
    void
    replaceDefaultConfigId(long currentDefaultConfigId, long newDefaultConfigId)
    Replaces the existing default configuration ID with a new configuration ID.
    long
    setDefaultConfig(String configDefinition)
    Registers a configuration in the repository and then sets its ID as the default for the repository with an auto-generated comment.
    long
    setDefaultConfig(String configDefinition, String configComment)
    Registers a configuration in the repository and then sets its ID as the default for the repository.
    void
    setDefaultConfigId(long configId)
    Sets the default configuration ID.

  • Method Details

    • createConfig

      SzConfig createConfig() throws SzException
      Creates a new SzConfig instance from the template configuration definition.

      Usage: 

      // How to create an SzConfig instance representing the template configuration
try {
  // obtain the SzEnvironment (varies by application)
  SzEnvironment env = getEnvironment();

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

  // create the config from the template
  SzConfig config = configMgr.createConfig();

  // do something with the SzConfig
  ...

} catch (SzException e) {
  // handle or rethrow the exception
  logError("Failed to create new SzConfig from the template.", e);
}

      Returns:
      A newly created SzConfig instance representing the template configuration definition.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • createConfig

      SzConfig createConfig(String configDefinition) throws SzException
      Creates a new SzConfig instance from a configuration definition.

      Usage: 

      // How to create an SzConfig instance representing a specified config definition
try {
  // obtain the SzEnvironment (varies by application)
  SzEnvironment env = getEnvironment();

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

  // obtain a JSON config definition (varies by application)
  String configDefinition = readConfigFile();

  // create the config using the config definition
  SzConfig config = configMgr.createConfig(configDefinition);

  // do something with the SzConfig
  ...

} catch (SzException e) {
  // handle or rethrow the exception
  logError("Failed to create a new SzConfig from a definition.", e);
}

      Parameters:
      configDefinition - The definition for the Senzing configuration.
      Returns:
      A newly created SzConfig representing the specified configuration definition.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • createConfig

      SzConfig createConfig(long configId) throws SzException
      Creates a new SzConfig instance for a configuration ID.

      If the configuration ID is not found then an exception is thrown.

      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 application)
    long configId = configMgr.getDefaultConfigId();

    // get the config definition for the config ID
    SzConfig config = configMgr.createConfig(configId);

    // do something with the SzConfig
    ...

} catch (SzException e) {
    // handle or rethrow the exception
    logError("Failed to create SzConfig from config ID.", e);
}

      Parameters:
      configId - The configuration ID of the configuration definition to retrieve.
      Returns:
      A newly created SzConfig instance representing the configuration definition that is registered with the specified config ID.
      Throws:
      SzException - If a failure occurs.

    • registerConfig

      long registerConfig(String configDefinition, String configComment) throws SzException
      Registers a configuration definition in the repository.

      NOTE:: Registered configurations do not become immediately active nor do they become the default. Further, registered configurations cannot be unregistered.

      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 application)
    String configDefinition = createConfigWithDataSources("CUSTOMERS");

    // register the config with a custom comment
    long configId = configMgr.registerConfig(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 configuration definition to register.
      configComment - The comments for the configuration.
      Returns:
      The identifier for referencing the config in the entity repository.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • registerConfig

      long registerConfig(String configDefinition) throws SzException
      Registers a configuration definition in the repository with an auto-generated comment.

      NOTE:: Registered configurations do not become immediately active nor do they become the default. Further, registered configurations cannot be unregistered.

      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 application)
    String configDefinition = createConfigWithDataSources("EMPLOYEES");

    // register the config (using an auto-generated comment)
    long configId = configMgr.registerConfig(configDefinition);

    // do something with the config ID
    ...

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

      Parameters:
      configDefinition - The configuration definition to register.
      Returns:
      The identifier for referencing the config in the entity repository.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • getConfigRegistry

      String getConfigRegistry() throws SzException
      Gets the configuration registry.

      The registry contains the original timestamp, original comment and configuration ID of all configurations ever registered with the repository.

      NOTE: Registered configurations cannot be unregistered.

      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 registry = configMgr.getConfigRegistry();

    // do something with the returned JSON (e.g.: parse it and extract values)
    JsonObject jsonObj = Json.createReader(
        new StringReader(registry)).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);
}

      Example Result: (formatted for readability) 

      {
    "CONFIGS": [
        {
            "CONFIG_ID": 1360003129,
            "CONFIG_COMMENTS": "Initial config with COMPANIES",
            "SYS_CREATE_DT": "2025-08-11T18:41:43Z"
        },
        {
            "CONFIG_ID": 2089303284,
            "CONFIG_COMMENTS": "Data Sources: EMPLOYEES",
            "SYS_CREATE_DT": "2025-08-11T18:41:43Z"
        },
        {
            "CONFIG_ID": 2553349549,
            "CONFIG_COMMENTS": "Data Sources: WATCHLIST",
            "SYS_CREATE_DT": "2025-08-11T18:41:43Z"
        },
        {
            "CONFIG_ID": 3420617113,
            "CONFIG_COMMENTS": "Initial Config",
            "SYS_CREATE_DT": "2025-08-11T18:41:43Z"
        },
        {
            "CONFIG_ID": 4205176341,
            "CONFIG_COMMENTS": "Added PASSENGERS data source",
            "SYS_CREATE_DT": "2025-08-11T18:41:43Z"
        }
    ]
}

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

    • getDefaultConfigId

      long getDefaultConfigId() throws SzException
      Gets the default configuration ID for the repository.

      Unless an explicit configuration ID is specified at initialization, the default configuration ID is used.

      NOTE: The default configuration ID may not be the same as the active configuration ID.

      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 configuration ID, or zero (0) if the default configuration has not been set.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • replaceDefaultConfigId

      void replaceDefaultConfigId(long currentDefaultConfigId, long newDefaultConfigId) throws SzReplaceConflictException, SzException
      Replaces the existing default configuration ID with a new configuration ID.

      The change is prevented (with an SzReplaceConflictException being thrown) if the current default configuration ID value is not as expected. Use this in place of setDefaultConfigId(long) to handle race conditions.

      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, "PASSENGERS");
        long   newConfigId      = configMgr.registerConfig(configDefinition, "Added PASSENGERS 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 ID.

      Usually this method is sufficient for setting the default configuration ID. However, in concurrent environments that could encounter race conditions, consider using replaceDefaultConfigId(long,long) instead.

      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("WATCHLIST");
    long configId = configMgr.registerConfig(configDefinition);

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

    • setDefaultConfig

      long setDefaultConfig(String configDefinition, String configComment) throws SzException
      Registers a configuration in the repository and then sets its ID as the default for the repository.

      This is a convenience method for registerConfig(String,String) followed by setDefaultConfigId(long).

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

    // set the default config (using a specific comment)
    long configId = configMgr.setDefaultConfig(configDefinition, "Initial config with COMPANIES");

    // do something with the registered config ID
    ...

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

      Parameters:
      configDefinition - The configuration definition to register as the default.
      configComment - The comments for the configuration.
      Returns:
      The configuration ID under which the configuration was registered.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • setDefaultConfig

      long setDefaultConfig(String configDefinition) throws SzException
      Registers a configuration in the repository and then sets its ID as the default for the repository with an auto-generated comment.

      This is a convenience method for registerConfig(String) followed by setDefaultConfigId(long).

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

    // set the default config (using an auto-generated comment)
    long configId = configMgr.setDefaultConfig(configDefinition);

    // do something with the registered config ID
    ...

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

      Parameters:
      configDefinition - The configuration definition to register as the default.
      Returns:
      The configuration ID under which the configuration was registered.
      Throws:
      SzException - If a failure occurs.
      See Also: