Spotfire Streaming JMS Adapter Configuration

This article provides a reference for generating a StreamBase configuration file for JMS and TIBCO EMS adapters, where the HOCON type is com.tibco.ep.streambase.configuration.adapter and the root object is JMSAdapter. Use this page for reference for configuring the server connection and destination specifications for one or more JMS or TIBCO EMS message servers.

Configuration files of this type can be edited as usual with the StreamBase Configuration File Editor. However, StreamBase Studio also provides a specialized JMS Configuration Editor dedicated to configuring this JMS and EMS configurations, which provides a forms-based way to edit the HOCON properties described in this article. The JMS Editor is invoked from the Edit button of the Properties view of any JMS or EMS operator. See JMS and TIBCO EMS Configuration Editor for further details.

Because you will use the JMS Configuration Editor for most of your JMS and TIBCO EMS configuration work, this page serves as a reference for fields in the JMS Editor. Directly editing your JMSAdapter HOCON file is possible, but should be very rare.

Prior to StreamBase 10.3.0, JMS and EMS adapters were specified with a configuration file named adapter-configurations.xml which had to be resident in the Studio project's src/main/resources folder. While this XML file format is still supported, it is a best practice using a HOCON configuration file instead.

For more information on the Spotfire Streaming Adapter for JMS, see JMS Adapter.

Each configuration file must contain the following:

There is one root object in configuration files with type com.tibco.ep.streambase.configuration.adapter that affects these particular operators:

The JMS and TIBCO EMS configuration schema is complex and multi-layered. However, remember that you will configure your JMS connections using the JMS Configuration Editor and will rarely need to edit a configuration file directly.

The exception is setting default entries with properties whose name begins with default. Those must be edited with the text mode HOCON Editor.

In outline view, a JMS configuration file takes the following form:

name = "JMSAdapter"
version = "1.0.0"
type = "com.tibco.ep.streambase.configuration.adapter"
configuration = {
  JMSAdapter = {
    jmsServers = {
      YourServerName = {
        [properties for YourServerName] 
        destinations = {
          dest1 = {
            [properties for dest1 on YourServerName] 
          }
          dest2 = {
            [properties for dest2 on YourServerName]
          }
          ... [possibly more destinations defined]
        }
        defaultDestination = {
          [default properties for destinations on YourServerName]
        }
        [further properties for YourServerName. The JMS Editor usually
        alphabetizes object and property names. Thus, many server 
        properties might be found after the "destinations" objects.]
      }
      AnotherServerName = {
        [properties, objects, and destinations for this second server]
      }
      FurtherServers = {...} ...
    }
    [The next four objects each define a set of named features
    that can be referenced elsewhere in the configuration. Of these
    four, only timeStampFormats is recommended for current use, and
    is the only one supported by the JMS Editor. Instead of the three
    map settings here, current best practice is to follow your EMS
    or JMS component on the canvas with a Map operator that performs 
    the desired mapping there.]
    fieldMaps = { ...
    }
    jmsHeaderFieldMaps = { ...
    }
    jmsPropertyMaps = { ...
    }
    timeStampFormats = { ...
    }
    [The properties whose names begin with "default" specify default
    settings. Default properties are not supported by the JMS Editor
    and can only be specified by editing the jmsAdapter.conf file 
    in text mode with the StreamBase HOCON Configuration Editor.
    The defaults at this level, parallel to the jmsServers object,
    apply to all destinations defined in this configuration file.]
    jmsServerDefaults = {
      [In this object, specify defaults that are to apply to all
      servers defined in this configuration file.]
      ...
      }
    defaultTimeStampFormat = "tsFormat2"
    ...
    [Defaults at this level (parallel to the jmsServers object above)
    apply throughout this configuration file, to destinations as
    well as servers.]
  }
}

This section shows the subordinate objects, properties, usage, and syntax for the JMSAdapter root object. Throughout, the terms JMS and TIBCO EMS apply interchangeably to each other's services. In general, we use JMS for its brevity, but show sample configuration lines for a TIBCO EMS server.

The following is an example of the com.tibco.ep.streambase.configuration.adapter type with the JMSAdapter root object.

name = "sample-JMSAdapter"
version = "1.0.0"
type = "com.tibco.ep.streambase.configuration.adapter"
configuration = {
  JMSAdapter = {
    adapterClassName = "com.streambase.sb.adapter.jms.enqueue.JMSReader"
    jmsServers = {
      YourServerName = {
        description = "sample server, connects using JNDI"
        providerName = "TIBCO EMS"
        providerContextFactoryClassName = 
          "com.tibco.tibjms.naming.TibjmsInitialContextFactory"
        providerURL = "tibjmsnaming://localhost:7222"
        connectionFactoryName = "ConnectionFactory"
        destinations = {
          dest1 = {
            destinationType = "TOPIC"
            messageSelector = "selector1"
            fieldMap = "fieldMap1"
            jmsHeaderFieldMap = "headerFieldMap1"
            jmsPropertyMap = "propertyMap1"
            timeStampFormat = "tsFormat1"
            deliveryTimeField = "delivery-time-field-1"
            messageToTupleConverterClassName = "com.tibco.converter1"
            tupleToMessageConverterClassName = "com.tibco.deconverter1"
            messageToTupleConverterCustomSettings = "converter 1 custom settings"
            acknowledgeMode = "AUTO_ACKNOWLEDGE"
            deliveryMode = "PERSISTENT"
            timeToLiveMilliseconds = 123
            priority = 5
            disableMessageID = true
            disableMessageTimeStamp = true
            isTemporaryDestination = false
          }
          dest2 = {
            destinationType = "QUEUE"
            messageSelector = "selector2"
            fieldMap = "fieldMap2"
            jmsHeaderFieldMap = "headerFieldMap2"
            jmsPropertyMap = "propertyMap2"
            timeStampFormat = "tsFormat2"
            deliveryTimeField = "delivery-time-field-2"
            messageToTupleConverterClassName = "com.tibco.converter2"
            tupleToMessageConverterClassName = "com.tibco.deconverter2"
            messageToTupleConverterCustomSettings = "converter 2 custom settings"
          }
        }
        defaultDestination = {
          destinationType = "QUEUE"
          messageSelector = "defaultSelector"
          fieldMap = "fieldMap1"
          jmsHeaderFieldMap = "headerFieldMap1"
          jmsPropertyMap = "propertyMap1"
          timeStampFormat = "tsFormat1"
          deliveryTimeField = "delivery-time-field-1"
          messageToTupleConverterClassName = "com.tibco.defaultConverter"
          tupleToMessageConverterClassName = "com.tibco.defaultDeconverter"
          messageToTupleConverterCustomSettings = "default converter custom settings"
          deliveryMode = "RELIABLE_DELIVERY"
          timeToLiveMilliseconds = 321
          priority = 4
          disableMessageID = false
          disableMessageTimeStamp = false
          isTemporaryDestination = false
        }
        acknowledgeMode = "AUTO_ACKNOWLEDGE"
        createDestinations = false
        useTopics = false
        cacheDestinations = false
        userName = "user1"
        password = "secret1"
        clientID = "client-id-1"
        subscriberName = "subscriber-1"
        maxReconnectAttempts = 5
        reconnectSleepSeconds = 3
        destinationMonitorIntervalMilliseconds = 50000
        jndiSecurityPrincipal = "security-principal"
        jndiSecurityCredentials = "security-credentials"
        jndiSecurityAuthentication = "security-auth"
        jndiSecurityProtocol = "security-protocol"
        jndiAuthoritative = true
        jndiDNSURL = "jndi-dns-url"
        jndiReferral = "jndi-referral"
        jndiConnectionBuilderClassName = "com.company.connection.Builder"
        jndiInitialContextBuilderClassName = "com.company.initial.context.Builder"
        jndiExtraProperties = {
          prop1 = "val1"
          prop2 = "val2"
        }
        customSettings = "an arbitrary string passed verbatim to the implementer 
          of the CustomConnectionBuilder interface"
      }
      AnotherServerName = {
        description = "Sample ActiveMQ Server"
        providerName = "Apache ActiveMQ"
        connectionFactoryClassName = "org.apache.activemq.jndi.ActiveMQInitialContextFactory"
        connectionFactoryURL = "tcp://localhost:61616"
        acknowledgeMode = "DUPS_OK_ACKNOWLEDGE"
        createDestinations = true
        useTopics = true
        cacheDestinations = true
        userName = "user2"
        password = "secret2"
        clientID = "client-id-2"
        subscriberName = "subscriber-2"
        maxReconnectAttempts = 10
        reconnectSleepSeconds = 5
        destinationMonitorIntervalMilliseconds = 25000
      }
    }
    fieldMaps = {
      mapForDest1 = {
        jmsField1 = "sbField1"
        jmsField2 = "sbField2"
      }
      mapForDest2 = {
        jmsFieldA = sbFieldA
      }
    }
    jmsHeaderFieldMaps = {
      headerFieldMap1 = {
        jms-headerField-Field1 = "sbField5"
        jms-headerField-Field2 = "sbField6"
      }
      headerFieldMap2 = {
        jms-headerField-Field3 = "sbField7"
        jms-headerField-Field4 = "sbField8"
      }
    }
    jmsPropertyMaps = {
      propertyMap1 = {
        jms-property1 = "sbField9"
        jms-property2 = "sbField10"
      }
      propertyMap2 = {
        jms-property3 = "sbField11"
        jms-property4 = "sbField12"
      }
    }
    timeStampFormats = {
      tsFormat1 = "format1"
      tsFormat2 = "format2"
    }
    associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]
    jmsServerDefaults = {
      defaultClientID = "a-default-client-ID"
      defaultSubscriberName = "a-default-subscriber-name"
      defaultMaxReconnectAttempts = 10
      defaultReconnectSleepSeconds = 5
      defaultDestinationMonitorIntervalMilliseconds = 10000
      defaultJNDISecurityPrincipal = "default-jndi-security-principal"
      defaultJNDISecurityCredentials = "default-jndi-security-credentials"
      defaultJNDISecurityAuthentication = "default-jndi-security-authentication"
      defaultJNDISecurityProtocol = "default-jndi-security-protocol"
      defaultJNDIAuthoritative = true
      defaultJNDIDNSURL = "default-jndi-dns-url"
      defaultJNDIReferral = "default-jndi-referral"
      defaultJNDIConnectionBuilderClassName = "default.jndi.connection.builder.class.name"
      defaultJNDIInitialContextBuilderClassName = "default.jndi.initial.context.builder.class.name"
      defaultJNDIExtraProperties = {
        name1 = "val1"
        name2 = "val2"
      }
      defaultJMSServerCustomSettings = "Default custom settings for a custom connection builder"
    }
    defaultFieldMap = "fieldMap1"
    defaultJMSHeaderFieldMap = "headerFieldMap2"
    defaultJMSPropertyMap = "propertyMap1"
    defaultTimeStampFormat = "tsFormat2"
    defaultDeliveryTimeField = "myDeliveryTimeField"
    defaultMessageToTupleConverterClassName = "com.tibco.myMessageToTupleConverter"
    defaultTupleToMessageConverterClassName = "com.tibco.myTupleToMessageConverter"
    defaultMessageToTupleConverterCustomSettings = "a default converter settings string"
    defaultDeliveryMode = "NON_PERSISTENT"
    defaultTimeToLiveMilliseconds = 333
    defaultPriority = 1
    defaultDisableMessageID = false
    defaultDisableMessageTimeStamp = false
  }
}