Package com.senzing.sdk

Interface SzConfig

public interface SzConfig

Defines the Java interface that encapsulates and represents a Senzing configuration and provides functions to operate on that configuration.

An SzConfig instance is typically obtained from an SzConfigManager instance via one of the following methods:

Create from template configuration: 

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

Create from configuration definition: 

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

Create from registered configuration ID: 

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

  • Method Details

    • export

      String export() throws SzException
      Retrieves the definition for this configuration.

      Note: Typically, an implementation's Object.toString() function will be implemented to return the result from this function.

      Usage: 

      // How to export config JSON from a config handle
try {
  // obtain the SzEnvironment (varies by application)
  SzEnvironment env = getEnvironment();

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

  // get an SzConfig object (varies by application)
  SzConfig config = configMgr.createConfig();

  // export the config
  String configDefinition = config.export();

  ...

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

this.saveDemoResult("exportConfig", demoResult, true);

      Example Result:
      The example result is rather large, but can viewed here (formatted for readability).

      Returns:
      The configuration definition formatted as a JSON object.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • getDataSourceRegistry

      String getDataSourceRegistry() throws SzException
      Gets the data source registry for this configuration.

      Usage: 

      // How to get the data source registry from an in-memory config
try {
  // obtain the SzEnvironment (varies by application)
  SzEnvironment env = getEnvironment();

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

  // get an SzConfig object (varies by application)
  SzConfig config = configMgr.createConfig();

  // get the data source registry
  String registry = config.getDataSourceRegistry();

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

  // iterate over the data sources
  for (JsonObject sourceObj : jsonArr.getValuesAs(JsonObject.class)) {
    String dataSourceCode = sourceObj.getString("DSRC_CODE");

    ...
  }

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

      Example Result: (formatted for readability) 

      {
    "DATA_SOURCES": [
        {
            "DSRC_ID": 1,
            "DSRC_CODE": "TEST"
        },
        {
            "DSRC_ID": 2,
            "DSRC_CODE": "SEARCH"
        }
    ]
}

      Returns:
      The data source registry describing the data sources for this configuration formatted as a JSON object.
      Throws:
      SzException - If a failure occurs.

    • registerDataSource

      String registerDataSource(String dataSourceCode) throws SzException
      Adds a data source to this configuration.

      Because SzConfig is an in-memory representation, the repository is not changed unless the configuration is exported and then registered via SzConfigManager.

      Usage: 

      // How to register data sources to an in-memory config
try {
  // obtain the SzEnvironment (varies by application)
  SzEnvironment env = getEnvironment();

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

  // get an SzConfig object (varies by application)
  SzConfig config = configMgr.createConfig();

  // register data sources in the config
  config.registerDataSource("CUSTOMERS");

  config.registerDataSource("EMPLOYEES");

  config.registerDataSource("WATCHLIST");

  ...

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

      Example Result: (formatted for readability) 

      {
    "DSRC_ID": 1003
}

      Parameters:
      dataSourceCode - The data source code for the new data source.
      Returns:
      The JSON String describing the data source was added to the configuration.
      Throws:
      SzException - If a failure occurs.
      See Also:

    • unregisterDataSource

      void unregisterDataSource(String dataSourceCode) throws SzException
      Removes a data source from this configuration.

      Because SzConfig is an in-memory representation, the repository is not changed unless the configuration is exported and then registered via SzConfigManager.

      NOTE: This method is idempotent in that it succeeds with no changes being made when specifying a data source code that is not found in the registry.

      WARNING: If records in the repository refer to the unregistered data source, the configuration cannot be used as the active configuration.

      Usage: 

      // How to unregister a data source from an in-memory config
try {
  // obtain the SzEnvironment (varies by application)
  SzEnvironment env = getEnvironment();

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

  // get an SzConfig object (varies by application)
  SzConfig config = configMgr.createConfig();

  // unregister the data source from the config
  config.unregisterDataSource("CUSTOMERS");

  ...

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

      Parameters:
      dataSourceCode - The data source code that identifies the data source to delete from the configuration.
      Throws:
      SzException - If a failure occurs.