Interface SzConfigManager

Namespace: Senzing.Sdk

Assembly: Senzing.Sdk.dll

Defines the C# interface to the Senzing config manager functions.

public interface SzConfigManager

Examples

An SzConfigManager instance is typically obtained from an SzEnvironment instance via the 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);
}

Remarks

The Senzing config functions provide means to manage the configurations that are stored in the Senzing repository including the default configuration that will be loaded if no config ID is specified during initialization.

Methods

CreateConfig()

Creates a new SzConfig instance using the default configuration template and returns the SzConfig representing that configuration.

SzConfig CreateConfig()

Returns

SzConfig: A newly created SzConfig instance representing the template configuration definition.

Examples

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

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Add Data Sources

Code Snippet: Initialize Config

CreateConfig(long)

Gets the configuration definition that is registered with the specified config ID and returns a new SzConfig instance representing that configuration.

SzConfig CreateConfig(long configID)

Parameters

configID long: The configuration ID of the configuration to retrieve.

Returns

SzConfig: A newly created SzConfig instance representing the configuration definition that is registered with the specified config ID.

Examples

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

Exceptions

SzException: If a failure occurs.

CreateConfig(string)

Creates a new SzConfig instance using the specified configuration definition and returns the SzConfig representing that configuration.

SzConfig CreateConfig(string configDefinition)

Parameters

configDefinition string: The definition for the Senzing configuration.

Returns

SzConfig: A newly created SzConfig representing the specified configuration definition.

Examples

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

Remarks

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).

Exceptions

SzException: If a failure occurs.

GetConfigs()

Gets the list of saved configuration ID's with their comments and timestamps and return the JSON string describing them.

string GetConfigs()

Returns

string: The JSON string describing the configurations registered in the entity repository with their identifiers, timestamps and comments.

Examples

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 = JsonNode.Parse(configsJson)?.AsObject();

    JsonArray? jsonArr = jsonObj?["CONFIGS"]?.AsArray();

    // iterate over the registered configurations
    if (jsonArr != null)
    {
        for (int index = 0; index < jsonArr.Count; index++)
        {
            JsonObject? configObj = jsonArr[index]?.AsObject();

            long? configID = configObj?["CONFIG_ID"]?.GetValue<long>();
            string? createdOn = configObj?["SYS_CREATE_DT"]?.GetValue<string>();
            string? comment = configObj?["CONFIG_COMMENTS"]?.GetValue<string>();

            . . .

        }
    }

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

Remarks

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"
    },
    . . .
  ]
}

Exceptions

SzException: If a failure occurs.

GetDefaultConfigID()

Gets the configuration ID of the default configuration for the repository and returns it.

long GetDefaultConfigID()

Returns

long: The current default configuration 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.

Examples

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

Remarks

If the entity repository is in the initial state and the default configuration ID has not yet been set, then zero (0) is returned.

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Add Data Sources

RegisterConfig(string)

Registers the configuration described by the specified configuration definition in the repository with an auto-generated comment and returns the identifier for referencing the the config in the entity repository.

long RegisterConfig(string configDefinition)

Parameters

configDefinition string: The configuration definition to register.

Returns

long: The identifier for referencing the config in the entity repository.

Examples

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

Remarks

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Add Data Sources

RegisterConfig(string, string)

Registers the configuration described by the specified configuration definition in the repository with the specified comment and returns the identifier for referencing the the config in the entity repository.

long RegisterConfig(string configDefinition, string configComment)

Parameters

configDefinition string: The configuration definition to register.
configComment string: The comments for the configuration.

Returns

long: The identifier for referencing the config in the entity repository.

Examples

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

Remarks

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Add Data Sources

ReplaceDefaultConfigID(long, long)

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 ReplaceDefaultConfigID(long currentDefaultConfigID, long newDefaultConfigID)

Parameters

currentDefaultConfigID long: The configuration ID that is believed to be the current default configuration ID.
newDefaultConfigID long: The new configuration ID for the repository.

Examples

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

Remarks

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.

Exceptions

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: Code Snippet: Add Data Sources

SetDefaultConfig(string)

Registers the specified config definition with an auto-generated comment and then sets the default configuration ID for the repository to the configuration ID that is the result of that registration.

long SetDefaultConfig(string configDefinition)

Parameters

configDefinition string: The configuration definition to register as the default.

Returns

long: The identifier for referencing the config in the entity repository.

Examples

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

Remarks

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.

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Initialize Config

SetDefaultConfig(string, string)

Registers the specified config definition with the specified comment and then sets the default configuration ID for the repository to the configuration ID that is the result of that registration, returning the config ID under which the configuration was registered.

long SetDefaultConfig(string configDefinition, string configComment)

Parameters

configDefinition string: The configuration definition to register as the default.
configComment string: The comments for the configuration.

Returns

long: The identifier for referencing the config in the entity repository.

Examples

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

Remarks

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Initialize Config

SetDefaultConfigID(long)

Sets the default configuration for the repository to the specified configuration ID.

void SetDefaultConfigID(long configID)

Parameters

configID long: The configuration ID to set as the default configuration.

Examples

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

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Initialize Config

Table of Contents

Interface SzConfigManager

Examples

Remarks

Methods

CreateConfig()

Returns

Examples

Exceptions

CreateConfig(long)

Parameters

Returns

Examples

Exceptions

CreateConfig(string)

Parameters

Returns

Examples

Remarks

Exceptions

GetConfigs()

Returns

Examples

Remarks

Exceptions

GetDefaultConfigID()

Returns

Examples

Remarks

Exceptions

RegisterConfig(string)

Parameters

Returns

Examples

Remarks

Exceptions

RegisterConfig(string, string)

Parameters

Returns

Examples

Remarks

Exceptions

ReplaceDefaultConfigID(long, long)

Parameters

Examples

Remarks

Exceptions

SetDefaultConfig(string)

Parameters

Returns

Examples

Remarks

Exceptions

SetDefaultConfig(string, string)

Parameters

Returns

Examples

Remarks

Exceptions

SetDefaultConfigID(long)

Parameters

Examples

Exceptions