About Grid Libraries

A Grid Library is a set of resources and properties necessary to run a Grid Service, along with configuration information that describes how these resources are to be used. For example, a Grid Library can contain JAR files, native libraries, configuration files, environment variables, hooks, and other resources.

A Grid Library is deployed as an archive file in ZIP or gzipped TAR format, with a grid-library.xml file in the root that describes the Grid Library. It might also contain any number of directories that contain resources.

Grid Libraries are identified by name and version. Versions are optional, but recommended; they are used to detect conflicts between a desired library and library that has already been loaded. Versions also provide for automatic selection of the latest version of a library. A GridServer Service can specify that it is implemented by a particular Grid Library when its Service Type is registered, or by using a Service option.

Grid Libraries can specify that they depend on other Grid Libraries; like the Service Option, such dependencies can be specified by the name, and optionally the version. Also, nearly all aspects of a Grid Library can be specified to be valid only for a specific operating system. This means that the same Grid Library can specify distinct paths and properties for Windows and Linux but only the appropriate set of package options is applied at run-time.

Variable Substitution

You can use placeholder variables in a grid-library.xml file, which are then substituted with their value as defined in a properties file or in an OS environment variable. This enables quick changes in properties in the grid-library.xml file without redeploying the Grid Library.

If the grid-library.xml file contains a property with a value contained with the $ character, such as $mydir$, it is substituted with the value in one of three places, in this order:

A default properties file in your Grid Library named grid-library.properties. This can provide baseline values for your variables.
An external properties file, named with the same name as the Grid Library archive, with the extension .properties, in the Grid Library deployment directory. Values in an external properties file replace those defined in the default properties file within the Grid Library.
A defined OS environment variable. This value replaces the value defined in either properties file.

Note 

If the substitution is not found in the file, the empty string, "", is substituted.

Substitutions are allowed anywhere in a string within the content of property value elements and path elements. Multiple substitutions per string are allowed. $ characters can be treated as literals by escaping them with another $ character. Windows paths that are specified in the library.properties file must escape the \ character with another \.

Versioning

Versioning provides the following functionality:

It allows for deployment of new versions of libraries and deletion of old versions without interrupting currently executing Service Sessions.
It provides for specifying conflicts, or libraries that cannot coexist with each other.
It allows for a Service Session or dependency to specify the use of the latest version of a Grid Library.

To use versioning, you must specify the Grid Library version in the configuration file. An Engine can load only one version of the library with the same name at any time. If the version is not specified, it is implied to be 0.

The version is a String and must adhere to the following version format. This format is

[n1].[n2].[n3]...

where nx is an integer, and there might be one or more version points.

For instance,

4.0.1.1,  4.1,  3 

are in the proper comparable version format.

The integer at each version point is evaluated starting at the first point, and continues until a version point is greater than the other. If a version point does not exist for one, it is implied as zero.

For instance

4.0.0.1 > 4.0
4.0.0.5 < 4.0.1.1

To specify that a dependency or Service uses a particular version of a Grid Library, the version field is set to that value. To specify that it uses the latest version, the field is left blank.

Note: If a version is specified it must match exactly. That is, 3.0.0 is not the same as 3; if the library’s version is 3.0.0 and the Service specifies 3, the Service does not find that library and subsequently fails.

If a version is specified but not in this format, and there are multiple versions of a library, the “latest version” is undefined. Thus, automatic selection of the latest version is only possible when all Grid Libraries with the specified name provide a version in the proper format.

By default, if a Service was set to use the latest version of a Grid Library, all Engines work on the latest version at the time the Service was started, regardless of whether a newer library has been deployed. This can be changed by setting the GRID_LIBRARY_STRICT_VERSIONING option in the driver.properties file to false. When false, if a newer version of the library is deployed while the Service is running, Engines that have not yet worked on the Service use the newer version, while Engines that worked on it prior to deployment continue to use the older version.

Dependencies

Grid Libraries might specify dependencies on other Grid Libraries. A dependency specification resolves to a particular Grid Library using two values:

grid-library-name  The name of the Grid Library, as specified in the dependency’s XML
grid-library-version  The version of the Grid Library, as specified in the dependency’s XML. OS compatibility is determined by checking the os and compiler tags for the top-level element in the dependent Grid Library. If not specified, it uses the latest version supported by the OS

Note that if a dependency resolves to more than one Grid Library, the dependency used is undefined.

Two dependent libraries conflict if they have the same library name, but different versions.

It is possible to specify an OS attribute to a <dependency> element for ignoring Grid Libraries that do not apply to an Engine’s particular operating system. For example, if a Grid Library contains native libraries for multiple platforms, you can specify OS-specific dependencies on the bridge Grid Libraries such that the Engine only loads the bridge corresponding to its operating system.

Note that if a dependency is missing, the Engine logs a warning. Rather than the current task failing, the Engine attempts to continue loading all necessary libraries to run the task.

Conflicts

A conflict between two Grid Libraries means that these libraries cannot be loaded concurrently. When there is a conflict between a loaded Grid Library and a Grid Library required by a Service, the Engine must restart to unload the current libraries and load the requested library.

The following circumstances result in a conflict:

Version Conflict  The most common conflict arises with versioning, and typically when upgrading versions or using more than one version of the same library concurrently. This conflict arises when a Grid Library with the same grid-library-name as the requested Grid Library, but a different version, is loaded.
Explicit Conflict  There can be situations in which different Grid Libraries can conflict with each other due to conflicting native libraries, different versions of Java classes, and so on. Because the Engine cannot determine these implicitly, the conflict element can be used to specify Grid Libraries that are known to conflict with this Grid Library.

Additionally, the value of the grid-library-name can be set to "*". This means that this Grid Library can conflict with all other Grid Libraries (aside from its dependencies), and it is guaranteed that no other Grid Libraries load concurrently with this Grid Library. Note that this is only allowed if the Grid Library is not a dependency; if the "*" is used as a conflict in a Grid Library that is a dependency, a verification error occurs.

Dynamic Version Conflict  A Grid Library conflict occurs if dynamic versioning is used, and the latest version of a Grid Library or Grid Library dependency has changed due to an addition or removal of a dependency since the Grid Library has been loaded.
Variable Substitution Conflict  A Grid Library conflict occurs if its variable substitution file has changed since it has been loaded.

Grid Library Loading

When a Service Session is set to use a Grid Library, that library is loaded. Loading is the process of setting up all resources in the Grid Library for use by the Service. A library is loaded only once per Engine session.

First, the library loads itself, and then it loads all dependencies. The library loader uses the depth-first, or preorder traversal algorithm when loading libraries. When there are a number of dependencies in a Grid Library, the order in the XML is considered left-to-right with respect to the algorithm. The library search order for lib-path and jar-path is determined by their respective lists. Certain aspects of a load might require a restart, and possibly re-initialization of the state.

The following steps are performed by a load of the root library and all dependencies:

1. It checks for conflicts with currently loaded Grid Libraries. If so, it restarts with the requested Grid Library and clear out the current state of any loaded libraries.
2. If new lib-paths have been added for its OS, they append to the current list of lib-paths. The state of loaded libraries includes all libraries already loaded, plus the requested library. Note that specifying a JRE dependency has this effect.
3. If new jar-paths have been added for its OS, the JAR files and classes are added to the classloader.
4. If new assembly-paths have been added, it adds them to the .NET search path.
5. If new command-paths have been added for its OS, it is added to the search path for Command tasks.
6. If new hooks-paths have been added, any hooks in the path are initialized.
7. If the default is current and a Grid Library is requested, the Engine restarts.

State Preservation

Under most cases, when an Engine shuts down, it preserves the current state of which Grid Libraries it has loaded. When it starts back up, it loads all Grid Libraries that were loaded when it shut down. As Grid Libraries are loaded, the path elements they contain are added to a ‘master’ list of paths for that type of pathelement. For example, if a Grid Library contains a lib-path specification, that lib-path is appended to the list of lib-path values obtained from already-loaded Grid Libraries.

Note that this means that it is up to the creator of the Grid Libraries deployed on the grid to ensure that the ordering of library paths does not lead to loading the wrong library. For example, if two different Grid Libraries each provide DLLs in their lib-paths that share the same name, because of OS-specific library load conventions, the one used is the first one in the aggregate lib-path from across all loaded Grid Libraries. Likewise for Java classes, when more than one copy of the same class is in the classloader, it is undefined which class loads. Therefore it is important to either subdivide Grid Libraries appropriately when there is a possibility that such conflicts can arise, or to use the conflict element to explicitly state conflicts.

Grid Library and RunAs State information persists on normal Engine shutdowns, which includes task failures aside from crashes. If the Engine does not shut down normally, such as if it crashes, or if the Daemon kills the process due to it exceeding the shutdown timeout, the state is reset.

If an Engine shuts down due to a conflict, it clears the current state and sets up for only the requested Grid Library upon restart. This is referred to as preloading. If an Engine shuts down due to internal library inconsistencies or a crash, the state is not saved. State is also cleared on all instances when a Daemon is disabled and re-enabled.

Task Reservation

If an Engine requires a restart to load a Grid Library, the task is reserved on the Broker for that Engine. The Engine is instructed to log back into the same Broker, and takes that task upon login. The timeout for this is configurable at Admin > System Admin > Manager Configuration > Services.

Environment Variables and System Properties

All Environment variables and Java System properties for a Grid Library and all dependencies are set each time a task is taken from a particular service that specified that Grid Library. (They are not cleared after the task is finished.) Environment variables are set via JNI so that they can be used by native libraries or .NET assemblies, and they are also passed into Command Services. Note that environment variables such as PATH and LD_LIBRARY_PATH must not be changed through this mechanism. Rather, library-path and command-path are reserved for manipulating these variables.