StreamBase Artifact Distribution Service Configuration

< Previous		Next >

Overview

This article provides a reference for writing a StreamBase Artifact Distribution Service configuration file.

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 operators, based on the artifact type 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 element lines, enter the word configuration followed by an open brace. The configuration element is a sibling of the name, version, and type elements, 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 Elements Explained

Below shows the configuration's HOCON elements, its name-values, usage, and syntax example, where applicable.

configuration

top-level ADS configuration property. Required.

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 name-value pair 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

List 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 specify 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.

artifactMetadata

String. The artifact metadata file is located using a resource lookup using the fragment's class 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.

For example:

artifactMetadata = "myartifacts/myartifact-metadata.xml"

artifactSource

String. The artifact data file is located using a resource lookup using the fragment's class 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 name-value pair 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 name-value pair is optional and defaults to the empty string. Configuration audit fails if the artifact already exists with a different encoding.

For example:

encoding = ""

latest

Boolean. When operators register for artifacts they can request either a specific version of an artifact or the latest version. Set this name-value pair 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 name-value pair is required and must contain at least one character. For example:

name = "configurationtest-name-1"

state

The initial state of the artifact. The possible values for this name-value pair are INACTIVE or ACTIVE. This field 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 name-value pair is ignored if this artifact already exists when this configuration is activated.

For example:

state = ACTIVE

type

String. Artifact type. This name-value pair is required and must contain at least one character. For example:

type = "configurationtest-lifecycleTest-1"

version

String. Artifact version. This name-value pair is required and must contain at least one character. For example:

version = "1.0"

HOCON Configuration File Sample

The following is an example of the com.tibco.ep.streambase.configuration.ads type. Long lines wrap to the next for clarity.

name = "lifecycleTest"
version = "1.0"
type = "com.tibco.ep.streambase.configuration.ads"
configuration = {
 Artifacts = {
     artifacts = [
         {
             type = "configurationtest-lifecycleTest-1"
             name = "configurationtest-name-1"
             version = "1.0"
             artifactSource = "com/tibco/ep/streambase/configuration/ads/
             configurationtest-111.txt"
             artifactMetadata = "com/tibco/ep/streambase/configuration/ads/
             configurationtest-metadata-111.txt"
             encoding = "configurationtest-encoding-111"
             state = ACTIVE
             latest = false
         }
         {
             type = "configurationtest-lifecycleTest-1"
             name = "configurationtest-name-1"
             version = "2.0"
             artifactSource = "com/tibco/ep/streambase/configuration/ads/
             configurationtest-112.txt"
             artifactMetadata = "com/tibco/ep/streambase/configuration/ads/
             configurationtest-metadata-112.txt"
             encoding = ""
             state = INACTIVE
             latest = false
         }
         {
             type = "configurationtest-lifecycleTest-1"
             name = "configurationtest-name-2"
             version = "1.0"
             artifactSource = "com/tibco/ep/streambase/configuration/ads/
             configurationtest-121.txt"
             artifactMetadata = "com/tibco/ep/streambase/configuration/ads/
             configurationtest-metadata-112.txt"
             state = ACTIVE
             latest = true
             encoding = "text/xml"
         }
     ]
   }
}