StreamBase Artifact Distribution Service Configuration

< Previous		Next >

Overview

This article provides a reference for writing a StreamBase Artifact Distribution Service configuration file where the HOCON type is com.tibco.ep.streambase.configuration.ads.

The Artifact Distribution Service (ADS) allows for the integration of supported StreamBase operators, and the TIBCO Artifact Management Server (AMS), which is a separately installed product. StreamBase operators use the Java APIs provided by ADS to register for and receive notifications about artifacts managed by AMS. AMS uses ADS to load and activate the artifacts requested by the StreamBase operators into the StreamBase Runtime cluster. As new versions of the artifacts become available, AMS loads and activates the new artifacts and ADS notifies the appropriate StreamBase operators that the new versions are available.

This ADS configuration file is strictly optional. It is for the use case where you want to package your artifact in the fragment or application archive instead of retrieving the artifact from AMS. To retrieve artifacts from AMS without using this HOCON configuration file, you would configure ADS properties in the currently supported model operators and adapters, based on the type of artifact you wish to retrieve:

Required Header Lines

Each configuration file must contain the following header lines, typically found at the beginning of each file:

name

Specifies an arbitrary, case-sensitive string to name this configuration, which must be unique among other files with the same type, if any. Configuration files can refer to each other by this name. Select a name that reminds you of this configuration's type and purpose. For example:

name = "adssettings"

version

Specifies an arbitrary version number that you can use to keep track of file versions for this configuration type in your development project. The maintenance of version numbers is under user control; StreamBase does not compare versions when loading configuration files during the fragment launch process. The version number is a string value, and can contain any combination of characters and numbers. For example:

version = "1.0.0"

type

This essential setting specifies the unique HOCON configuration type described on this page.

type = "com.tibco.ep.streambase.configuration.ads"

The three header lines taken together constitute a unique signature for each HOCON file in a project's configurations folder. Each project's configurations folder can contain only one file with the same signature.

The top-level configuration object defines the configuration envelope the same way for all HOCON file types.

configuration

On a line below the header lines, enter the word configuration followed by an open brace. The configuration object is a sibling of the name, version, and type identifiers, and serves to define the configuration envelope around this type's objects as described on this page. The file must end with the matching close brace.

configuration = {
...
...
}

HOCON Properties Explained

Below shows the configuration's HOCON properties, usage, and syntax example, where applicable.

configuration

ADS configuration root object. Required.

Artifacts

An Artifact Distribution Service configuration specifies artifacts to be loaded into the cluster.

associatedWithEngines

If you want to manually restrict this object to be associated with specific engines, do so here. Each entry can be a specific engine name or a regular expression that can applies to more than one engine. This array is optional and has no default value. If not present, the configuration uses default engine association based on its location in a fragment or application archive, or in a node deploy configuration.

For example:

associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]

artifacts

Array of artifacts to load into the Artifact Distribution Service (ADS). When a fragment starts, the artifacts defined here are loaded into ADS and ADS delivers them to any of the fragment's operators that registered for these artifacts. The type, name, and version fields together form the unique key for an artifact. StreamBase operators register for an artifact by specifying the type, name, and version of the artifact. The type, name, and version fields set in this configuration must match the values specified by the operator in order for the operator to receive the artifact.

For example:

name = "default-decision-tables"
type = "com.tibco.ep.streambase.configuration.ads"
version = "1.0.0"
configuration = {
  Artifacts =
    {
      artifacts =
        [ 
          {
            latest = true
            name = "default/businessrules.sbdt"
            state = ACTIVE
            type = SB_DECISION_TABLE
            version = "1"
            artifactSource = "com/example/decisiontabletest/rulesets/default/
              default.businessrules.sbdt"
          }
          {
            latest = true
            name = "ruleSet1/businessrules.sbdt"
            state = ACTIVE
            type = SB_DECISION_TABLE
            version = "1"
            artifactSource = "com/example/decisiontabletest/rulesets/ruleset1/
              ruleSet1.businessrules.sbdt"
          }
          {
            latest = true
            name = "ruleSet2/businessrules.sbdt"
            state = ACTIVE
            type = SB_DECISION_TABLE
            version = "1"
            artifactSource = "com/example/decisiontabletest/rulesets/ruleset2/
              ruleSet2.businessrules.sbdt"
          }
        ]
    }
}

artifactMetadata

String. The artifact metadata file is located using a resource lookup using the fragment's path. Place this file under one of the resource directories of the fragment's Studio project. For example, src/main/resources. The path specified is a path relative to the resource directory. Configuration audit fails if metadata file is not found or if the artifact already exists with different metadata.

This property is optional, as ADS does not currently use the metadata file and just passes it through to the operator.

For example:

artifactMetadata = "myartifacts/myartifact-metadata.xml"

artifactSource

String. The artifact data file is located using a resource lookup using the fragment's path. Place this file under one of the resource directories of the fragment's Studio project. For example, src/main/resources. The path specified is a path relative to the resource directory. This property is required. Configuration audit fails if the data file is not found or if the artifact already exists with different data.

For example:

artifactSource = "myartifacts/myartifact.xml"

encoding

String. The artifact's encoding. This property is optional and defaults to the empty string. Configuration audit fails if the artifact already exists with a different encoding.

For example:

encoding = "text/xml"

latest

Boolean. When operators register for artifacts they can request either a specific version of an artifact or the latest version. Set this property to true if this version of the artifact is the latest (that is, current) version of the artifact so that operators that requested the latest version will receive the artifact. At most one artifact with the same type and name attributes can be marked as the latest.

For example:

latest = true

name

String. Artifact name. This property is required and must contain at least one character. For example:

name = "myartifact.xml"

state

The initial state of the artifact. The possible values for this object are INACTIVE or ACTIVE. This property is optional and defaults to INACTIVE. Only active artifacts are delivered to the operators that registered for them. An inactive artifact can be transitioned to the active state with the activate artifact management command. This property is ignored if this artifact already exists when this configuration is activated.

For example:

state = ACTIVE

type

String. Artifact type. This property is required and must contain at least one character. For example:

type = "myartifact_type"

version

String. Artifact version. This property is required and must contain at least one character. For example:

version = "1.0"

replication

Artifact replication configuration. This property is optional.

artifactCacheDirectory

The path of the artifact cache directory. This directory is used by the Artifact Distribution Service (ADS) to store artifact data files. The path can be absolute or relative. Relative paths are relative to the node directory. This field is optional. If this field is not specified then the artifact cache directory is located under the node directory.

Specifying an artifact cache directory can be useful if it allows multiple nodes to share the same artifact cache directory. Using a shared artifact cache directory removes the need to copy artifact data files to each node.

This artifact cache directory is created if it does not exist. If the path cannot be created, or accessed, configuration audit will fail. The permissions of the artifact cache directory, if it is created by ADS, will be set to only allow the node owner access to the directory.

If the directory specified already exists then the operating system user that installed the node must have permissions to create sub-directories and files under this directory. Note that on Unix platforms this means that this operating system user must have read, write, and execute permissions on this directory.

An artifact cache directory outside of the node directory is not removed when the node is removed. The artifact cache directory must not be manually removed until all nodes using the artifact cache directory are removed.

An existing artifact cache directory can be reused if the nodes are re-created. Stale artifact data files are automatically replaced with the current artifact data files, as needed.

numberOfReplicas

Long. Number of replica nodes to use when replicating artifacts. This property is optional and its default value is 2 (and a minimum of 1 when the property is specified). For example:

numberOfReplicas = 2

nodePattern

String. A regular expression describing the nodes that can be used for artifact replication. This property is optional and its default value .* is a regular expression specifying all nodes in the cluster. For example:

nodePattern = ".*"

HOCON Configuration File Sample

The following is an example of the com.tibco.ep.streambase.configuration.ads type.

name = "ADS"
type = "com.tibco.ep.streambase.configuration.ads"
version = "1.0.0"
configuration = {
  Artifacts = {
    artifacts = [ 
      {
         artifactMetadata = "myartifacts/myartifact-metadata.txt"
         artifactSource = "myartifacts/myartifact-1.txt"
         encoding = "text/plain"
         latest = false
         name = "myartifactname"
         state = "INACTIVE"
         type = "myartifacttype"
         version = "1.0"
      }
    ]
    associatedWithEngines = [ "sample-engine-identifier" ]
    replication = {
      artifactCacheDirectory = "c:\a\directory\path"
      nodePattern = ".*"
      numberOfReplicas = 2
    }
  }
}