com.scaleoutsoftware.soss.client

Class InvocationGridBuilder

java.lang.Object

com.scaleoutsoftware.soss.client.InvocationGridBuilder

public final class InvocationGridBuilder
extends java.lang.Object

An invocation grid (IG) represents a custom configuration of the set of JVMs attached to the hosts in the store. It is used to do parallel invocations of the code across the data grid. IG definitions contain a description of the necessary dependencies (JARs, classes, folders, or files) and JVM parameters. Each invocation grid is identified by a user-specified name.

The purpose of the IG is to have a flexible alternative to copying all the dependencies on every invocation or manually distributing the dependencies and starting Java clients on each host in the store. An IG allows decoupling of staging and invocation, so the invocation infrastructure can be pre-initialized on application startup.

This class is used to configure and load invocation grids at runtime. Use load() to create invocation workers in the grid and get back the InvocationGrid handle object. The invocations can be directed to the IG by NamedCache.setInvocationGrid(InvocationGrid).

On Windows, the SOSS service relies on the JAVA_HOME environment variable to find the Java installation. To be available to the SOSS service, this variable should be set as a system variable, not a user variable. To set it, right click on My Computer and select Properties. On the Advanced tab, select Environment Variables, and then set the system variable JAVA_HOME to point to Java installation directory, for example, C:\Program Files\Java\jre1.7.0.

On Linux, the SOSS process relies on Java being available in /usr/lib/jvm/jre. If Java is installed in a different location, create a symbolic link to the installed location. Example: ln -s /usr/lib/java/jre/latest /usr/lib/jvm/jre

Constructor Summary

Constructors

Constructor and Description
InvocationGridBuilder(java.lang.String name) Creates the builder to configure the invocation grid.

Method Summary

Modifier and Type	Method and Description
InvocationGridBuilder	addClass(java.lang.Class clazz) Adds a class as an invocation grid dependency.
InvocationGridBuilder	addJar(java.lang.String path) Adds a JAR file as an invocation grid dependency.
InvocationGridBuilder	addJar(java.lang.String name, java.io.InputStream stream) Adds a JAR file as an invocation grid dependency.
InvocationGridBuilder	addStartupAction(com.scaleoutsoftware.soss.client.pmi.GridAction gridAction) Add a startup action to the InvocationGrid that will be run on each host after the InvocationGrid spawns on each host.
InvocationGrid	getIfExists()
InvocationGrid	load() If the invocation grid is not yet loaded, this method delivers dependencies to the hosts and starts up the invocation workers.
InvocationGrid	load(boolean forceReload) If the invocation grid is not yet loaded, this method delivers dependencies to the hosts and starts up the invocation workers.
InvocationGridBuilder	setAllowClientCaching(boolean allowClientCaching) Sets a boolean value that controls whether objects fetched in the invocation grid worker process during invoke processing are allowed to be cached in the client cache.
InvocationGridBuilder	setAllowFastReads(boolean allowFastReads) Enables/disables "fast reads" feature for invocations performed within this invocation grid.
InvocationGridBuilder	setClientCacheSize(int clientCacheSize) Set the maximum size of the client-side cache on each worker in the invocation grid in kilobytes.
InvocationGridBuilder	setCoherencyInterval(NamedCache cache, int coherencyInterval) Sets coherency interval in milliseconds which is used for performing PMIs on a given NamedCache.
InvocationGridBuilder	sethServerLibraryPath(java.lang.String path) Sets the appropriate ScaleOut hServer jar path relative to java_api folder.
InvocationGridBuilder	setJVMParameters(java.lang.String jvmParams) Sets the parameter string to be added to command line when starting the invocation grid workers.
InvocationGridBuilder	setLibraryPath(java.lang.String path) Sets the appropriate ScaleOut library jar path relative to java_api/lib folder.
InvocationGridBuilder	setLingerTimeMinutes(int lingerTimeMinutes) Sets the time for which the IG remains loaded after the application exits.
InvocationGridBuilder	setLockObjectsOnReads(boolean lock) If true, the objects are locked before they are read and passed to the Invokable.eval(Object, java.io.Serializable, EvalArgs) method.
InvocationGridBuilder	setNewClassLoader(boolean newClassLoader) If this option is set to true (default), the IG worker will create a new class loader for handling the classes in the IG dependency.
InvocationGridBuilder	setNumberOfThreads(int numberOfThreads) Sets the number of threads in the invocation workers which handle evals and merges.
InvocationGridBuilder	setOneWorkerPerCore(boolean oneWorkerPerCore) If set to true, invocation grid will spawn as many worker JVMs, as there are cores on the store host instead of one worker per JVM.

Methods inherited from class java.lang.Object

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

Constructor Detail

InvocationGridBuilder

public InvocationGridBuilder(java.lang.String name)
                      throws NamedCacheException

Creates the builder to configure the invocation grid. The IG is not loaded or available for invocations until load() is called.

Parameters:

name - IG name

Throws:

NamedCacheException - thrown if ScaleOut StateServer is unavailable.

Method Detail

setLingerTimeMinutes

public InvocationGridBuilder setLingerTimeMinutes(int lingerTimeMinutes)

Sets the time for which the IG remains loaded after the application exits. This gives a chance to the next application instance to reuse the existing IG. After that time the IG will be automatically unloaded and invocation workers stopped. The default linger time is 10 minutes.

Parameters:

lingerTimeMinutes - time in minutes to keep the IG loaded after exit

Returns:

self

addJar

public InvocationGridBuilder addJar(java.lang.String path)

Adds a JAR file as an invocation grid dependency. This effectively makes it part of the classpath on the invocation workers.

Parameters:

path - location of JAR file

Returns:

self

addJar

public InvocationGridBuilder addJar(java.lang.String name,
                                    java.io.InputStream stream)

Adds a JAR file as an invocation grid dependency. This effectively makes it part of the classpath on the invocation workers. The JAR file is read from the provided input stream.

Parameters:

name - name of JAR file

stream - input stream to read the JAR form

Returns:

self

addClass

public InvocationGridBuilder addClass(java.lang.Class clazz)

Adds a class as an invocation grid dependency. This will make the class definition available on the invocation workers.

Parameters:

clazz - the class to add to the IG

Returns:

self

setOneWorkerPerCore

public InvocationGridBuilder setOneWorkerPerCore(boolean oneWorkerPerCore)

If set to true, invocation grid will spawn as many worker JVMs, as there are cores on the store host instead of one worker per JVM. Default value of this option is false. Note: setting this option to true is not recommended and is not supported for invocations on the NamedCache.

Parameters:

oneWorkerPerCore - if true, start one worker per core on each host

Returns:

self

setClientCacheSize

public InvocationGridBuilder setClientCacheSize(int clientCacheSize)

Set the maximum size of the client-side cache on each worker in the invocation grid in kilobytes.

When the (approximate) size of all cached objects exceeds the maximum client-side cache size value, the least recently used objects are removed from the cache until the cache consumes no more memory (approximately) than the desired cache size. When the cache size is set to a smaller value, the cache is adjusted synchronously. In particular, setting the cache size to 0 will immediately remove all entries in the client-side cache and disable the client-side cache from use until the cache size is reset to a larger value.

If the maximum cache size is not set programmatically, its initial value is the value of the max_client_cache parameter specified in the soss_params.txt configuration file.

Parameters:

clientCacheSize - the maximum size of the client-side cache in kilobytes.

Returns:

self

Throws:

java.lang.IllegalArgumentException - if clientCacheSize is negative

setAllowClientCaching

public InvocationGridBuilder setAllowClientCaching(boolean allowClientCaching)

Sets a boolean value that controls whether objects fetched in the invocation grid worker process during invoke processing are allowed to be cached in the client cache. If set to true then objects fetched during invoke processing in the invocation grid created via this builder will be cached in the worker process' client caches. If false, objects read during Invoke processing will not be cached in the worker process' client cache although other object accesses may be.

Parameters:

allowClientCaching - true if client caching is allowed

Returns:

self

setJVMParameters

public InvocationGridBuilder setJVMParameters(java.lang.String jvmParams)

Sets the parameter string to be added to command line when starting the invocation grid workers. Particularly, this method can be used to specify custom memory size for the worker. If that method is called several times, the parameter strings are concatenated.

Parameters:

jvmParams - the parameters to be passed to JVM

Returns:

self

setLockObjectsOnReads

public InvocationGridBuilder setLockObjectsOnReads(boolean lock)

If true, the objects are locked before they are read and passed to the Invokable.eval(Object, java.io.Serializable, EvalArgs) method. It ensures that the objects are not modified by some other client at the same time they are being evaluated. This option should be used if the object is written back to the NamedCache after evaluation(EvalObjectDisposition.Update in the EvalArgs.setDisposition(EvalObjectDisposition)). The objects are unlocked after the eval() method is done, whether the disposition is set to update or not.

This option is false by default.

Parameters:

lock - true if the objects should be locked before evals

Returns:

this

setNewClassLoader

public InvocationGridBuilder setNewClassLoader(boolean newClassLoader)

If this option is set to true (default), the IG worker will create a new class loader for handling the classes in the IG dependency. This will work for most cases, but can cause exceptions if the code makes an attempt to use system class loader to resolve the IG classes (the most common case is manual deserialization). If this option is set to false the IG worker will make the best effort to update the system class loader with the IG classes. This is not directly supported by Java, so it is not recommended to use this mode. If this property is set to false, the IG cannot be reloaded with different set of classes/JARs.

Parameters:

newClassLoader - whether to use new class loader for IG

Returns:

self

sethServerLibraryPath

public InvocationGridBuilder sethServerLibraryPath(java.lang.String path)

Sets the appropriate ScaleOut hServer jar path relative to java_api folder.

Parameters:

path - path to the hServer library

Returns:

self

setLibraryPath

public InvocationGridBuilder setLibraryPath(java.lang.String path)

Sets the appropriate ScaleOut library jar path relative to java_api/lib folder.

Parameters:

path - path to the hServer library

Returns:

self

addStartupAction

public InvocationGridBuilder addStartupAction(com.scaleoutsoftware.soss.client.pmi.GridAction gridAction)

Add a startup action to the InvocationGrid that will be run on each host after the InvocationGrid spawns on each host.

Parameters:

gridAction - the action to run.

Returns:

self

setCoherencyInterval

public InvocationGridBuilder setCoherencyInterval(NamedCache cache,
                                                  int coherencyInterval)

Sets coherency interval in milliseconds which is used for performing PMIs on a given NamedCache. Coherency interval is maximum age of the client cache entry at which it can be returned without verifying the version with the server. Coherency interval of 0 means that object version is always verified. This optimization allows to avoid version checking server roundtrips when full coherency is not necessary.

Parameters:

cache - NamedCache to apply coherency interval to

coherencyInterval - coherency interval in milliseconds

Returns:

self

setNumberOfThreads

public InvocationGridBuilder setNumberOfThreads(int numberOfThreads)

Sets the number of threads in the invocation workers which handle evals and merges. If the number of threads is not set, IG will fall back to the reasonable default based on the number of cores.

Parameters:

numberOfThreads - number of threads in the invocation worker

Returns:

self

setAllowFastReads

public InvocationGridBuilder setAllowFastReads(boolean allowFastReads)

Enables/disables "fast reads" feature for invocations performed within this invocation grid. If this feature is enabled, the object version for all objects evaluated by the PMI call is shipped to the IG worker, and the client cache uses this version information to determine if cached objects are valid. When the update rate is low, this reduces the number of server round trips required for version checking of client-cached objects and can significantly improve the performance of invocations running on large numbers of objects. Note that the snapshot of version numbers delivered to the IG worker does not reflect updates which may have occurred after the PMI call was started. This setting only applies to IGs that do not lock objects during invocations by setting setLockObjectsOnReads(boolean) to false.

This feature is turned on by default.

Parameters:

allowFastReads - true if fast reads are allowed

Returns:

self

load

public InvocationGrid load()
                    throws NamedCacheException

If the invocation grid is not yet loaded, this method delivers dependencies to the hosts and starts up the invocation workers. It does not return until workers are running and ready to handle invocations. If the invocation grid is already loaded, and the number of dependencies, and their names match, it connects to the existing invocation grid and returns a corresponding object.

Returns:

InvocationGrid object.

Throws:

NamedCacheInvokeTimeoutException - if the invocation grid workers failed to start. If the failure cause is known for an invocation worker, it will be embedded in that exception.

NamedCacheException - if there was error while loading the IG

load

public InvocationGrid load(boolean forceReload)
                    throws NamedCacheException

If the invocation grid is not yet loaded, this method delivers dependencies to the hosts and starts up the invocation workers. It does not return until workers are running and ready to handle invocations. If the invocation grid is already loaded, and the number of dependencies, and their names match, and forceReload is false, it connects to the existing invocation grid and returns a corresponding object.

Parameters:

forceReload - this parameter controls the behaviour if the invocation grid is already loaded. If true, the method will not connect to the existing invocation grid; instead, it will reload it from scratch. This is not optimal from a performance standpoint, so this mode is only useful if dependencies were changed. Concurrent usage of the IG by multiple clients with enabled force reload is not currently supported.

Returns:

An InvocationGrid object.

Throws:

NamedCacheInvokeTimeoutException - if the invocation grid workers failed to start. If the failure cause is known for an invocation worker, it will be embedded in that exception.

NamedCacheException - if there was error while loading IG

getIfExists

public InvocationGrid getIfExists()
                           throws NamedCacheException

Throws:

NamedCacheException