On This Page
The platform's solace binding includes both a java based and jni based implementation and allows connectivity to a solace message router.
JNI vs JAVA Binding
The JNI binding support zero garbage messaging while in steady state, but is only supported on linux. The Java binding uses solace's JCSMP api while the JNI binding uses solace's CCSMP api. The JNI binding only works on linux platforms while the Java binding works on all platform supported by X. Other differences between the two bindings are:
- UnhandledMesssageEvents issued by the JNI binding return the subscription name rather than the sent topic name.
- UnhandledMesssageEvents issued by the JNI binding return a session specific sequence number rather than the appliance wide sequence number in the transport specific message id.
- The provider properties passed through to the underlying property differ depending on the underlying solace library used. The binding rationalizes some of the common properties between the two implementations. See the configuration section below for more details.
Bus Descriptor Format
A solace message bus can be configured via a descriptor string as follows which takes the connection information followed by a list of provider properties.
solace://<address>:<port>&prop1=val1&propN=valN
An example bus descriptor for solace would like like:
solace://<address>:<port>&usejni=true&vpn_name=default&username=test& / password=test&usejni=true&vpn_name=default&username=test&password=test
DDL
In a DDL config file a solace bus can equivalently be configured in one two ways
Decomposed
As A Descriptor
The descriptor form is useful in cases where the descriptor name may be supplied as an external configuration property that is substituted for example:
As A Descriptor
Solace Provider Properties
Passed Through Properties
The solace JCSMP and JNI apis on which the platform's solace binding is built allow configuration of the connection by specifying properties. The provider properties specified in the bus descriptor for the binding are passed through to the solace connection as follows:
- Properties that are not described as in the SolaceBindingProperties javadoc are stripped out.
General Bus properties defined in
MessageBusDescriptor javadocare also stripped out.- Properties listed as 'Rationalized Properties' below are translated according to whether the jni or java binding implementation will be used these.
- If "usejni" is
true, then any remaining properties that don't start with "FLOW_" or "SESSION_" are are stripped, the rest are passed through opaquely. - If "usejni" is
false, then any remaining properties that don't start with "jcsmp" are are stripped, the rest are passed through opaquely.
See the solace documentation for more information on JCSMP and CCSMP. Neeve, does not test properties not explicitly called out on this page or in the javadoc. End users should therefore do their own due diligence in testing any passed through properties.
Rationalized Properties
To make is easier for applications to switch between using the jni (c) and jcsmp (java) binding implementations, several commonly used binding properties are automatically translated by the binding. These are summarized in the table below. If your application doesn't use any additional solace configuration properties then switching between the java a c
| Binding Property | JCSMP Property | CCSMP Property |
|---|---|---|
| "vpn_name" | "jcsmp.vpn_name" | "SESSION_VPN_NAME" |
| "username" | "jcsmp.usename" | "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" |
MessageBusDescriptor.PROPNAME_ADDRESS(the value from the bus descriptor address) | "jcsmp.HOST" | "SESSION_HOST" |
Additional Properties
See the SolaceBindingProperties javadoc for the listing of additional provider properties specific to the solace binding.
Auto Tuning
When not explicitly as binding property, the following properties are automatically set on the binding based on the global optimization value.
| 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 |
Orphan Subscription Checks
When a solace message bus binding has a queue name specified it is capable of issue guaranteed subscriptions against that queue. When a binding is started it is possible that there may already be existing subscriptions on the queue that don't match those that the application is issuing. Such subscriptions are considered to be 'orphan' subscriptions - presumably those left over from an early session that were not removed.
The following policy can be configured to check for orphan subscriptions
| Policy | Desecription |
|---|---|
| None | With this policy, the appliance is not queried for subscriptions This is the default policy |
| Ignore | With this policy enabled the appliance is queried for subscriptions, but no action is taken other than tracing the orphans subscriptions at info level. One other difference between |
| LogExceptionAndContinue | With this policy enabled the appliance is queried for subscriptions and if orphands are found an exception is logged. |
| NoOrphan | With this policy enabled the appliance is queried for subscriptions and an exception is thrown from the message binding start method. |
Configuration
To check for existing subscription SEMP must be enabled for the binding to retrieve the list of subscriptions over the messaging connection. The following provider properties must be specified on the bus descriptor to perform subscription checks:
| Property | Usage | Default | Description |
|---|---|---|---|
| enable_semp | required | false | Property controlling whether or not Solace semp over messaging requests are enabled. Controls whether or not semp over messaging requests are enabled. This property must be enabled in order to query the solace appliance for existing subscriptions. This requires that the appliance has semp over messaging enabled and that the user is authorized to make semp requests.
|
| orphan_subscription_check | required | None | Property controlling the orphan subscription check policy. This policy controls checks for orphaned Guaranteed subscriptions done when the solace binding is started. The check for orphaned is performed after the bindings subscription are created, but just before messaging is started. The solace appliance is queried for the list of Guaranteed subscriptions on the Queue and compared to the subscriptions that were issued. Any subscriptions on the queue that were not issued by the binding are deemed to be orphans. When using a policy other than |
| semp_version | recommended | soltr/7_1_1 | The version of semp requests must match that supported by the messaging appliance. If this property is not set semp requests will be retried using the version reported in the error response if a version mismatch is detected. Setting this property correctly avoids the need to make the initial request to determine the semp version. |
| semp_request_timeout | recommended | 10000 | Property controlling what timeout to use for semp requests in milliseconds. It is recommended that you test against your appliance and application under load to ensure that the default timeout of 10 seconds is sufficient. |
| subscription_validator | unsupported | - | This is a legacy property that allows the an application registered callback to perform additional subscription validation. This should only be used on guidance for Neeve support. |
NOTE: SEMP operations are currently an experimental feature. Enabling semp is not recommended in production without rigorous end user testing, and it should be noted that solace could drop support for SEMP over messaging in the future. Reliance on SEMP operations may also limit ability to connect to solace appliance versions that don't have a compatibles SEMP model.