Solace Binding

Configuration reference for the Solace message bus binding.

Overview

The Solace binding provides native integration with Solace PubSub+ message brokers using either Solace's JCSMP (Java) API or CCSMP (C via JNI) API. The JNI binding supports zero-garbage messaging in steady state but is Linux-only, while the Java binding works on all platforms.

For conceptual information about the Solace binding, see Solace Binding.

JNI vs Java Binding Selection

Control which Solace client library is used:

Property
Default
Description

usejni

-

When true, mandates JNI usage (fails if unavailable). When false, never uses JNI.

preferjni

true

When true, silently falls back to JCSMP if JNI unavailable. Ignored if usejni is set.

The JNI binding is only available on Linux platforms and provides zero-garbage messaging capabilities.

Bus Descriptor Format

Solace buses can be configured using a descriptor string or decomposed DDL format.

Descriptor String

solace://<address>:<port>&prop1=val1&propN=valN

Example:

Decomposed DDL Format

As Descriptor (Substitution Support)

Solace Provider Properties

Passed Through Properties

Provider properties specified in the bus descriptor are passed through to the Solace connection with the following processing:

  1. Properties not described in SolaceBindingProperties are stripped out

  2. General bus properties from MessageBusDescriptor are stripped out

  3. Rationalized properties (see below) are translated based on JNI vs Java binding

  4. If usejni=true: Properties not starting with FLOW_ or SESSION_ are stripped, rest passed through

  5. If usejni=false: Properties not starting with jcsmp are stripped, rest passed through

Neeve does not test properties not explicitly documented on this page or in the javadoc. End users should test any passed-through properties thoroughly.

Rationalized Pass Through Properties

These common properties are automatically translated between JCSMP (Java) and CCSMP (JNI):

Binding Property
JCSMP Property
CCSMP Property

vpn_name

jcsmp.vpn_name

SESSION_VPN_NAME

username

jcsmp.username

SESSION_USERNAME

password

jcsmp.password

SESSION_PASSWORD

publish_window_size

jcsmp.pub_ack_window_size

SESSION_PUB_WINDOW_SIZE

reconnect_retry_count

jcsmp.CLIENT_CHANNEL_PROPERTIES.ReconnectRetries

SESSION_RECONNECT_RETRIES

connect_retry_count

jcsmp.CLIENT_CHANNEL_PROPERTIES.ConnectRetries

SESSION_CONNECT_RETRIES

tcp_nodelay

jcsmp.CLIENT_CHANNEL_PROPERTIES.tcpNoDelay

SESSION_TCP_NODELAY

reapply_subscriptions

jcsmp.REAPPLY_SUBSCRIPTIONS

SESSION_REAPPLY_SUBSCRIPTIONS

ignore_subscriptions_error

jcsmp.IGNORE_DUPLICATE_SUBSCRIPTION_ERROR

SESSION_IGNORE_DUP_SUBSCRIPTION_ERROR

(address from descriptor)

jcsmp.HOST

SESSION_HOST

Additional Properties

See SolaceBindingProperties javadoc for the complete list of binding-specific properties.

Auto Tuning

When not explicitly set, these properties are automatically configured based on nv.optimizefor:

Binding Property

nv.optimizefor=latency

nv.optimizefor=throughput

No Optimization

tcp_nodelay

true

false

false

detached_sends_queue_wait_strategy

See XRuntime.createWaitStrategy

See XRuntime.createWaitStrategy

Blocking

detached_dispatch_queue_wait_strategy

See XRuntime.createWaitStrategy

See XRuntime.createWaitStrategy

Blocking

Other Settings

Property
Default
Description

set_key_on_receipt

false

Sets the topic on a per-message basis. Accessible via message.getMessageKeyAsRaw().

provision_queue

true

Allows Solace to create queues automatically. If disabled, queues must be created manually.

queue_name

N/A

Limits the queue that the application will read from.

sma_metadata_version

1

Message metadata version. Use 2 for more efficient metadata if no receivers use versions prior to 1.8.396.

Orphan Subscription Checks

When a Solace bus binding has a queue name specified, it can detect "orphan" subscriptions - subscriptions on the queue that don't match those issued by the application (presumably left over from an earlier session).

Policies

Policy
Description

None

Appliance is not queried for subscriptions (default).

Ignore

Query appliance and trace orphan subscriptions at info level. Report to subscription validator if registered.

LogExceptionAndContinue

Query appliance and log exception if orphans found.

NoOrphan

Query appliance and throw exception from binding start method if orphans found.

Unsubscribe

With this policy enabled, the appliance is queried for subscriptions and orphan subscriptions are then removed (unsubscribed) from the appliance

Configuration

To perform subscription checks, SEMP must be enabled:

Property
Usage
Default
Description

enable_semp

optional

false

Enable Solace SEMP over messaging requests. Required for subscription checks. Requires appliance has SEMP over messaging enabled and user is authorized. NOTE: SEMP operations are experimental and not recommended for production without rigorous testing.

orphan_subscription_check

optional

None

Orphan subscription check policy. Performed after subscriptions created but before messaging started. Requires enable_semp=true for policies other than None.

semp_version

recommended

soltr/7_1_1

SEMP version. Must match messaging appliance version. If not set, version auto-detected on first request.

semp_request_timeout

recommended

10000

Timeout for SEMP requests in milliseconds. Test under load to ensure sufficient.

subscription_validator

unsupported

-

Legacy property for custom subscription validation. Use only with Neeve support guidance.

SEMP Operations Warning: SEMP operations are experimental. Not recommended for production without rigorous end-user testing. Solace may drop SEMP over messaging support in future versions. Reliance on SEMP may limit ability to connect to appliances with incompatible SEMP models.

Enforcing Max Queue Bind Count

When using Guaranteed messaging, queues can be provisioned with max bind count of 1 to ensure only one application instance can bind. The binding can enforce this via SEMP:

Property
Usage
Default
Description

enable_semp

optional

false

Must be enabled (see above).

enforce_max_bind_count

optional

0

Set to positive value to enforce match against provisioned queue's max bind count. When set, binding issues SEMP request at start to verify queue's max bind count matches this value. Ensures exclusive connectivity with enforce_max_bind_count=1. Ignored if no queue configured or value ≤ 0. Requires SEMP enabled.

Since 3.8: enforce_max_bind_count provides protection against network partitioning by ensuring two instances cannot both consume messages.

Trace Logging

The Solace binding logs trace messages using two loggers:

The nv.sma Logger

Controls trace level and messages emitted by the binding code itself (not the Solace client library).

The nv.sol Logger

Controls trace level and messages emitted by the Solace client runtime.

JNI Enabled (CCSMP)

When using JNI, the binding:

  1. Maps nv.sol logger level to CCSMP trace level (see table below)

  2. Registers callback with CCSMP to intercept trace messages

  3. Logs CCSMP messages via nv.sol logger

nv.sol to CCSMP Mapping:

nv.sol Level
CCSMP Level

SEVERE

ERROR

WARNING

WARNING

INFO, CONFIG

NOTICE

FINE, FINER, DIAGNOSE, VERBOSE

INFO

FINEST, DEBUG, ALL

DEBUG

CCSMP to nv.sol Mapping (for logged messages):

CCSMP Level
nv.sol Level

CRITICAL, ERROR

SEVERE

WARNING

WARNING

NOTICE

INFO

INFO

FINE

DEBUG

FINEST

JNI Disabled (JCSMP)

When using JCSMP, the binding:

  1. Maps nv.sol logger level to set com.solacesystems.jcsmp logger level

  2. Assumes all JCSMP logging uses the com.solacesystems.jcsmp logger

nv.sol to com.solacesystems.jcsmp Mapping:

nv.sol Level
com.solacesystems.jcsmp Level

SEVERE

SEVERE

WARNING

WARNING

INFO

INFO

CONFIG

CONFIG

FINE

FINE

FINER

FINER

DIAGNOSE, VERBOSE, FINEST

FINEST

DEBUG, ALL

ALL

See Trace Logging for information on configuring loggers.

See Also

PreviousConfiguring Bus ConnectionsNextJMS Binding

Last updated