- Index

< Previous |  | Next >

# StreamBase Artifact Distribution Service Configuration

## 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 operators, based on the artifact type you wish to retrieve:

- Decision Table

- H2O

- PMML

- Spark

- TERR

## 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.

      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.

        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"

## 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 = "myartifact_type"
            name = "myartifact.xml"
            version = "1.0"
            artifactSource = "myartifacts/myartifact.xml"
            artifactMetadata = "myartifacts/myartifact-metadata.xml"
            encoding = "text/xml"
            state = ACTIVE
            latest = false
         }
       ]
     }
    }