Package com.senzing.sdk.core

Class SzCoreEnvironment

java.lang.Object

com.senzing.sdk.core.SzCoreEnvironment

All Implemented Interfaces:

SzEnvironment

public class SzCoreEnvironment
extends Object
implements SzEnvironment

Provides the core implementation of SzEnvironment that directly initializes the Senzing SDK modules and provides management of the Senzing environment in this process.

Usage:

// get the settings (varies by application)
String settings = getSettings();

// get the instance name (varies by application)
String instanceName = getInstanceName();

// construct the environment
SzEnvironment env = SzCoreEnvironment.newBuilder()
                                     .instanceName(instanceName)
                                     .settings(settings)
                                     .verboseLogging(false)
                                     .build();

// use the environment for some time (usually as long as application is running)
...

// destroy the environment when done (sometimes in a finally block)
env.destroy();

.

Since:

4.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	SzCoreEnvironment.AbstractBuilder<E extends SzCoreEnvironment,B extends SzCoreEnvironment.AbstractBuilder<E,B>>	Provides a base class for builder implementations of SzCoreEnvironment and its derived classes.
static class	SzCoreEnvironment.Builder	The builder class for creating an instance of SzCoreEnvironment.
static interface	SzCoreEnvironment.Initializer	Provides an interface for initializing an instance of SzCoreEnvironment.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_INSTANCE_NAME	The default instance name to use for the Senzing initialization.
static final String	DEFAULT_SETTINGS	The default "bootstrap" settings with which to initialize the SzCoreEnvironment when an explicit settings value has not been provided via SzCoreEnvironment.AbstractBuilder.settings(String).

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	SzCoreEnvironment(SzCoreEnvironment.Initializer initializer)	Protected constructor used by the SzCoreEnvironment.Builder to construct the instance.

Method Summary

Modifier and Type	Method	Description
void	destroy()	Destroys this SzEnvironment and invalidates any SDK singleton references that has previously provided.
protected <T> T	doExecute(Callable<T> task)	Called by execute(Callable) after ensuring that this instance is not destroyed and ensuring any calls to destroy() will block until after this method's invocation is completed.
protected <T> T	execute(Callable<T> task)	Executes the specified Callable task via doExecute(Callable) after ensuring that this instance is not destroyed and will not be destroyed before the task's completion.
long	getActiveConfigId()	Implemented from SzEnvironment.getActiveConfigId().
static SzCoreEnvironment	getActiveInstance()	Gets the current active instance of SzCoreEnvironment.
SzConfigManager	getConfigManager()	Provides a reference to the SzConfigManager instance associated with this SzEnvironment.
SzDiagnostic	getDiagnostic()	Provides a reference to the SzDiagnostic instance associated with this SzEnvironment.
SzEngine	getEngine()	Provides a reference to the SzEngine instance associated with this SzEnvironment.
SzProduct	getProduct()	Provides a reference to the SzProduct instance associated with this SzEnvironment.
boolean	isDestroyed()	Implemented from SzEnvironment.isDestroyed().
static SzCoreEnvironment.Builder	newBuilder()	Creates a new instance of SzCoreEnvironment.Builder for setting up an instance of SzCoreEnvironment.
void	reinitialize(long configId)	Implemented from SzEnvironment.reinitialize(long).
protected boolean	validateActiveInstance()	Internal method that is called by getActiveInstance() to validate the active instance before returning it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DEFAULT_INSTANCE_NAME

public static final String DEFAULT_INSTANCE_NAME

The default instance name to use for the Senzing initialization. The value is ""Senzing Instance". An explicit value can be provided via SzCoreEnvironment.AbstractBuilder.instanceName(String) during initialization.

Since:

4.0.0

See Also:

• newBuilder()
• SzCoreEnvironment.AbstractBuilder.instanceName(String)
• Constant Field Values

DEFAULT_SETTINGS

public static final String DEFAULT_SETTINGS

The default "bootstrap" settings with which to initialize the SzCoreEnvironment when an explicit settings value has not been provided via SzCoreEnvironment.AbstractBuilder.settings(String). If this is used it will initialize Senzing when installed in its default path and provide full access access to only the SzProduct interface as well as limited access to the SzConfigManager interface (i.e.: for functionality not dealing with registered configuration ID's). The value of this constant is "{ }".

NOTE: Using these settings is only useful for accessing the the full functionality of the SzProduct interface and limited functionality of the SzConfigManager interface since SzEngine and SzDiagnostic require database access to connect to the Senzing repository. Further, some SzConfigManager functionality (particularly any functionality that works with registered configurations that have configuration ID's) also requires database access to connect to the Senzing repository.

The value of this constant is "{ }".

Since:

4.0.0

See Also:

• newBuilder()
• SzCoreEnvironment.AbstractBuilder.settings(String)
• Constant Field Values

Constructor Details

SzCoreEnvironment

protected SzCoreEnvironment(SzCoreEnvironment.Initializer initializer)

Protected constructor used by the SzCoreEnvironment.Builder to construct the instance.

Parameters:

initializer - The SzCoreEnvironment.Initializer with which to construct (typically an instance of SzCoreEnvironment.AbstractBuilder).

Since:

4.1.0

Method Details

newBuilder

public static SzCoreEnvironment.Builder newBuilder()

Creates a new instance of SzCoreEnvironment.Builder for setting up an instance of SzCoreEnvironment. Keep in mind that while multiple SzCoreEnvironment.Builder instances can exists, only one active instance of SzCoreEnvironment can exist at time. An active instance is one that has not yet been destroyed.

Alternatively, you can directly call the Builder() constructor.

Returns:

The SzCoreEnvironment.Builder for configuring and initializing the SzCoreEnvironment.

Since:

4.0.0

getActiveInstance

public static SzCoreEnvironment getActiveInstance()

Gets the current active instance of SzCoreEnvironment. An active instance is is one that has been constructed and has not yet been destroyed. There can be at most one active instance. If no active instance exists then null is returned.

Returns:

The current active instance of SzCoreEnvironment, or null if there is no active instance.

Since:

4.0.0

execute

protected <T> T execute(Callable<T> task)
                 throws SzException,
SzEnvironmentDestroyedException

Executes the specified Callable task via doExecute(Callable) after ensuring that this instance is not destroyed and will not be destroyed before the task's completion.

This is used by the core implementations of SzEngine, SzProduct, SzConfigManager, SzConfig and SzDiagnostic to execute their functionality and ensure the environment is stable during execution.

If successful, this will return the result of the Callable task. If not successful, this will throw any exception produced by the Callable task, wrapping it in an SzException if it is a checked exception that is not of type SzException.

Type Parameters:

T - The return type.

Parameters:

task - The Callable task to execute.

Returns:

The result from the Callable task.

Throws:

SzException - If the Callable task triggers a failure.

SzEnvironmentDestroyedException - If this SzCoreEnvironment instance has already been destroyed.

Since:

4.1.0

doExecute

protected <T> T doExecute(Callable<T> task)
                   throws Exception

Called by execute(Callable) after ensuring that this instance is not destroyed and ensuring any calls to destroy() will block until after this method's invocation is completed.

If successful, this will return the result of the Callable task. If not successful, this will throw any exception produced by the Callable task.

Type Parameters:

T - The return type.

Parameters:

task - The Callable task to execute.

Returns:

The result from the specified Callable task.

Throws:

Exception - If a failure occurs.

Since:

4.1.0

getConfigManager

public SzConfigManager getConfigManager()
                                 throws SzEnvironmentDestroyedException,
SzException

Provides a reference to the SzConfigManager instance associated with this SzEnvironment.

Usage:

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

Implemented to return an instance of SzConfigManager that will execute all of its functionality via execute(Callable). If you need to change the functionality of the returned instance consider using Proxy and InvocationHandler to proxy the returned instance.

Specified by:

getConfigManager in interface SzEnvironment

Returns:

The SzConfigManager instance associated with this SzEnvironment.

Throws:

SzEnvironmentDestroyedException - If this SzEnvironment instance has been destroyed.

SzException - If there was a failure in obtaining or initializing the SzConfigManager instance.

Since:

4.0.0

getDiagnostic

public SzDiagnostic getDiagnostic()
                           throws SzEnvironmentDestroyedException,
SzException

Provides a reference to the SzDiagnostic instance associated with this SzEnvironment.

Usage:

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

    SzDiagnostic diagnostic = env.getDiagnostic();

    ...

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

Implemented to return an instance of SzDiagnostic that will execute all of its functionality via execute(Callable). If you need to change the functionality of the returned instance consider using Proxy and InvocationHandler to proxy the returned instance.

Specified by:

getDiagnostic in interface SzEnvironment

Returns:

The SzDiagnostic instance associated with this SzEnvironment.

Throws:

SzEnvironmentDestroyedException - If this SzEnvironment instance has been destroyed.

SzException - If there was a failure in obtaining or initializing the SzDiagnostic instance.

Since:

4.0.0

getEngine

public SzEngine getEngine()
                   throws SzEnvironmentDestroyedException,
SzException

Provides a reference to the SzEngine instance associated with this SzEnvironment.

Usage:

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

    SzEngine engine = env.getEngine();

    ...

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

Implemented to return an instance of SzEngine that will execute all of its functionality via execute(Callable). If you need to change the functionality of the returned instance consider using Proxy and InvocationHandler to proxy the returned instance.

Specified by:

getEngine in interface SzEnvironment

Returns:

The SzEngine instance associated with this SzEnvironment.

Throws:

SzEnvironmentDestroyedException - If this SzEnvironment instance has been destroyed.

SzException - If there was a failure in obtaining or initializing the SzEngine instance.

Since:

4.0.0

getProduct

public SzProduct getProduct()
                     throws SzEnvironmentDestroyedException,
SzException

Provides a reference to the SzProduct instance associated with this SzEnvironment.

Usage:

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

    SzProduct product = env.getProduct();

    ...

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

Implemented to return an instance of SzProduct that will execute all of its functionality via execute(Callable). If you need to change the functionality of the returned instance consider using Proxy and InvocationHandler to proxy the returned instance.

Specified by:

getProduct in interface SzEnvironment

Returns:

The SzProduct instance associated with this SzEnvironment.

Throws:

SzEnvironmentDestroyedException - If this SzEnvironment instance has been destroyed.

SzException - If there was a failure in obtaining or initializing the SzProduct instance.

Since:

4.0.0

destroy

public void destroy()

Destroys this SzEnvironment and invalidates any SDK singleton references that has previously provided. If this instance has already been destroyed then this method has no effect.

Usage:

// obtain the SzEnvironment (varies by application)
SzEnvironment env = getEnvironment();

if (!env.isDestroyed()) {
    // destroy the environment
    env.destroy();
}

Implemented to block until all concurrent in-flight operations that are executing via the execute(Callable) are complete before destroying this instance. Once destroyed, a new instance of this class can be created, but only one instance can be active concurrently in the same process.

This method will invalidate any SzEngine, SzProduct, SzDiagnostic, SzConfigManager or SzConfig that was provided through this instance.

Specified by:

destroy in interface SzEnvironment

Since:

4.0.0

isDestroyed

public boolean isDestroyed()

Implemented from SzEnvironment.isDestroyed().

Checks if this instance has had its SzEnvironment.destroy() method called.

Usage:

// obtain the SzEnvironment (varies by application)
SzEnvironment env = getEnvironment();

if (!env.isDestroyed()) {
    // destroy the environment
    env.destroy();
}

Specified by:

isDestroyed in interface SzEnvironment

Returns:

true if this instance has had its SzEnvironment.destroy() method called, otherwise false.

Since:

4.0.0

validateActiveInstance

protected boolean validateActiveInstance()

Internal method that is called by getActiveInstance() to validate the active instance before returning it. It is expected that if this instance is in the process of destroying itself, then this method will block until the completion of the destroy() method. true is returned if this instance is active and has not had its destroy() method called, otherwise false is returned for an instance that was already destroyed.

This method should be overridden by derived classes that override destroy().

IMPORTANT: If this instance is in the process of being destroyed (e.g.: waiting for in-flight operations to complete) then this method must block until destruction is complete.

Returns:

true if this instance if still active, or false if this instance has been destroyed.

Since:

4.1.0

getActiveConfigId

public long getActiveConfigId()
                       throws SzEnvironmentDestroyedException,
SzException

Implemented from SzEnvironment.getActiveConfigId().

Gets the currently active configuration ID for the SzEnvironment.

Usage:

// How to get the active config ID for the SzEnvironment
try {
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = getEnvironment();

    // get the active config ID
    long activeConfigId = env.getActiveConfigId();

    // do something with the active config ID (varies by application)
    SzConfigManager configMgr = env.getConfigManager();

    long defaultConfigId = configMgr.getDefaultConfigId();

    if (activeConfigId != defaultConfigId) {
        // reinitialize the environment with the default config ID
        env.reinitialize(defaultConfigId);
    }

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

Specified by:

getActiveConfigId in interface SzEnvironment

Returns:

The currently active configuration ID.

Throws:

SzEnvironmentDestroyedException - If this SzEnvironment instance has been destroyed.

SzException - If there was a failure in obtaining the active config ID.

Since:

4.0.0

reinitialize

public void reinitialize(long configId)
                  throws SzEnvironmentDestroyedException,
SzException

Implemented from SzEnvironment.reinitialize(long).

Reinitializes the SzEnvironment with the specified configuration ID.

Usage:

// How to get the active config ID for the SzEnvironment
try {
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = getEnvironment();

    // get the active config ID
    long activeConfigId = env.getActiveConfigId();

    // do something with the active config ID (varies by application)
    SzConfigManager configMgr = env.getConfigManager();

    long defaultConfigId = configMgr.getDefaultConfigId();

    if (activeConfigId != defaultConfigId) {
        // reinitialize the environment with the default config ID
        env.reinitialize(defaultConfigId);
    }

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

Specified by:

reinitialize in interface SzEnvironment

Parameters:

configId - The configuration ID with which to initialize.

Throws:

SzEnvironmentDestroyedException - If this SzEnvironment instance has been destroyed.

SzException - If there was a failure reinitializing.

Since:

4.0.0