Package com.senzing.sdk

Interface SzConfig

public interface SzConfig

Defines the Java interface to the Senzing configuration functions.

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

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

    SzConfig config = env.getConfig();

    ...

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

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    addDataSource(long configHandle, String dataSourceCode)
    Adds a new data source that is identified by the specified data source code to the in-memory configuration associated with the specified configuraiton handle.
    void
    closeConfig(long configHandle)
    Closes the in-memory configuration associated with the specified config handle and cleans up system resources.
    long
    createConfig()
    Creates a new in-memory configuration using the default configuraiton template and returns the configuration handle for working with it.
    void
    deleteDataSource(long configHandle, String dataSourceCode)
    Deletes the data source identified by the specified data source code from the in-memory configuration associated with the specified config handle.
    String
    exportConfig(long configHandle)
    Obtains the configuration definition formatted as JSON for the in-memory configuration associated with the specified configuration handle.
    String
    getDataSources(long configHandle)
    Extracts the data sources from the in-memory configuration associated with the specified config handle returns the JSON text describing the data sources from the configuration.
    long
    importConfig(String configDefinition)
    Creates a new in-memory configuration using the specified configuration definition and returns the configuration handle for working with it.

  • Method Details

    • createConfig

      long createConfig() throws SzException
      Creates a new in-memory configuration using the default configuraiton template and returns the configuration handle for working with it.

      Usage: 

      // How to create a new in-memory config and obtain a handle
try {
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = getEnvironment();

    // get the SzConfig instance
    SzConfig config = env.getConfig();

    // create the config and obtain the handle
    long configHandle = config.createConfig();

    // do something with the config handle
    try {
        ... }

    } finally {
        // close the config handle
        config.closeConfig(configHandle);
    }

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

      Returns:
      The configuraton handle for working with the configuration that was created.
      Throws:
      SzException - If a failure occurs.

    • importConfig

      long importConfig(String configDefinition) throws SzException
      Creates a new in-memory configuration using the specified configuration definition and returns the configuration handle for working with it. Depending upon implementation of this interface, the specified definition may allow other forms, but it is typically a JSON-formatted Senzing configuration (an example template JSON configuration ships with the Senzing product).

      Usage: 

      // How to import config JSON into an in-memory config
try {
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = getEnvironment();

    // get the SzConfig instance
    SzConfig config = env.getConfig();

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

    // import the config and obtain the handle
    long configHandle = config.importConfig(configDefinition);

    // do something with the config handle
    try {
        ... }

    } finally {
        // close the config handle
        config.closeConfig(configHandle);
    }

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

      Parameters:
      configDefinition - The definition for the Senzing configuration.
      Returns:
      The configuraton handle for working with the configuration that was created and populated with the specified definition.
      Throws:
      SzException - If a failure occurs.

    • exportConfig

      String exportConfig(long configHandle) throws SzException
      Obtains the configuration definition formatted as JSON for the in-memory configuration associated with the specified configuration handle.

      Usage: 

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

    // get the SzConfig instance
    SzConfig config = env.getConfig();

    // get a valid config handle
    long configHandle = config.createConfig();

    // export the config
    try {
        String configDefinition = config.exportConfig(configHandle);

        ...

    } finally {
        // close the config handle
        config.closeConfig(configHandle);
    }

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

      Parameters:
      configHandle - The configuration handle associated with the in-memory configuration to be formatted as JSON.
      Returns:
      The configuration defininition formatted as JSON.
      Throws:
      SzException - If a failure occurs.

    • closeConfig

      void closeConfig(long configHandle) throws SzException
      Closes the in-memory configuration associated with the specified config handle and cleans up system resources. After calling this method, the configuration handle can no longer be used and becomes invalid.

      Usage: 

      // How to close a previously obtained config handle.
try {
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = getEnvironment();

    // get the SzConfig instance
    SzConfig config = env.getConfig();

    // obtain a config handle in some way
    long configHandle = config.createConfig();

    // do something with the config handle
    try {
        ... }

    } finally {
        // close the config handle
        config.closeConfig(configHandle);
    }

} catch (SzException e) {
    // handle or rethrow the exception
    logError("Failed config operation.", e);
}

      Parameters:
      configHandle - The config handle identifying the in-memory configuration to close.
      Throws:
      SzException - If a failure occurs.

    • getDataSources

      String getDataSources(long configHandle) throws SzException
      Extracts the data sources from the in-memory configuration associated with the specified config handle returns the JSON text describing the data sources from the configuration.

      The format of the JSON response is as follows: 

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

      Usage: 

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

    // get the SzConfig instance
    SzConfig config = env.getConfig();

    // get a valid config handle
    long configHandle = config.createConfig();

    // get the data sources
    try {
        String sourcesJson = config.getDataSources(configHandle);

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

            ...
        }

    } finally {
        // close the config handle
        config.closeConfig(configHandle);
    }

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

      Parameters:
      configHandle - The config handle associated witht he in-memory configuration from which to obtain the data sources.
      Returns:
      The JSON String describing the data sources found in the configuration.
      Throws:
      SzException - If a failure occurs.

    • addDataSource

      String addDataSource(long configHandle, String dataSourceCode) throws SzException
      Adds a new data source that is identified by the specified data source code to the in-memory configuration associated with the specified configuraiton handle. An exception is thrown if the data source already exists in the configuration.

      The response JSON provides the data source ID of the created data source and has the following format: 

         {
     "DSRC_ID": 410
   }

      Usage: 

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

    // get the SzConfig instance
    SzConfig config = env.getConfig();

    // get a valid config handle
    long configHandle = config.createConfig();

    try {
        // add data sources to the config
        config.addDataSource(configHandle, "CUSTOMERS");

        config.addDataSource(configHandle, "EMPLOYEES");

        config.addDataSource(configHandle, "WATCHLIST");

    } finally {
        // close the config handle
        config.closeConfig(configHandle);
    }

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

      Parameters:
      configHandle - The config handle identifying the in-memory configuration to which to add the data source.
      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.

    • deleteDataSource

      void deleteDataSource(long configHandle, String dataSourceCode) throws SzException
      Deletes the data source identified by the specified data source code from the in-memory configuration associated with the specified config handle.

      Usage: 

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

    // get the SzConfig instance
    SzConfig config = env.getConfig();

    // get a valid config handle
    long configHandle = config.createConfig();

    try {
        // delete the data soure from the config
        config.deleteDataSource(configHandle, "CUSTOMERS");

    } finally {
        // close the config handle
        config.closeConfig(configHandle);
    }

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

      Parameters:
      configHandle - The config handle identifying the in-memory configuration from which to delete the data source.
      dataSourceCode - The data source code that identifies the data source to delete from the configuration.
      Throws:
      SzException - If a failure occurs.