Starlight for JMS configuration reference

A complete configuration reference for Starlight for JMS.

Configuration information is passed to the PulsarConnectionFactory constructor:

Map<String, Object> configuration = new HashMap<>();
configuration.put("...","...");
ConnectionFactory factory = new PulsarConnectionFactory(configuration);
...
factory.close();

Configuration information can also be passed as a JSON encoded string:

String configuration = "{.....}";
ConnectionFactory factory = new PulsarConnectionFactory();
factory.setJsonConfiguration(configuration);
...
factory.close();

Configuration information can be passed when a JMSContext or Session is created with JMSContext.createContext or Session.createSession.

Create a PulsarConnectionFactory with initialContext for configuration.

Map<String, Object> configuration = new HashMap<>();
Map<String, Object> consumerConfig = new HashMap<>();
configuration.put("consumerConfig", consumerConfig);
PulsarConnectionFactory factory = new PulsarConnectionFactory(configuration);
PulsarJMSContext initialContext = (PulsarJMSContext) factory.createContext();

The initial configuration in initialContext will be overridden by the subsequent JMSContext configuration withCustomConfiguration.

Map<String, Object> perContextConfiguration new HashMap<>();
Map<String, Object> perContextConsumerConfig = new HashMap<>();
perContextConsumerConfig.put("consumerConfig", perContextConsumerConfig);
JMSContext withCustomConfiguration = initialContext.createContext(mode, perContextConfiguration);

Or override the initial configuration in initialContext with the JMSContext configuration withCustomConfiguration in a Session object.

Session.createSession(int mode, Map<String, Object> withCustomConfiguration)

The configuration related to consumerConfig is the only configuration that can be overridden with createContext. Other entries are ignored.

Configuration options

Configuration Entry Required Type Default value Notes

Configuration Entry	Required	Type	Default value	Notes
`ackTimeout`	no	long	Disabled	Set timeout for unacked messages. Must be >1 second.
`ackTimeoutMillis`	no	long		Same as `ackTimeout`, but expressed in milliseconds
`brokerServiceUrl`	no	String	If not specified, for Pulsar standalone instances running on localhost, defaults to the same value as `webServiceUrl`, `http://localhost:8080`. Can also be specified as `pulsar://localhost:6650` for Pulsar standalone instances on localhost.	The URL to connect to the Pulsar broker or proxy The `brokerServiceUrl` must be specified for Astra Streaming. Must be customized as required for Pulsar standalone instances that are not running on localhost.
`consumerConfig`	no	Map<String,Object>	Empty Map	Additional configuration for each Pulsar Consumer. For all valid consumer objects, see the Apache Pulsar documentation.
`enableTransaction`	no	boolean	false	Enable transactions `enableTransaction` defaults to false because transaction support is not enabled by default in Pulsar 2.7 and the client cannot connect to a cluster that does not enable transactions.
`jms.acknowledgeRejectedMessages`	no	boolean	false	Force acknowledgment of filtered messages on shared subscriptions By default, filtered messages are negatively acknowledged on shared subscriptions. If this flag is `true`, they are acknowledged in order to skip them definitively.
`jms.allowTemporaryTopicWithoutAdmin`	no	boolean	false	Allows temporary topic/queue creation and deletion to pass without errors when `jms.usePulsarAdmin` is set to `false` Use the default values of `allowAutoTopicCreation=true` and `allowAutoTopicCreationType=non-partitioned` in `broker.conf` for auto-creation of temporary topics/queues.
`jms.clientId`	no	String	empty string	Administratively assigned `clientId` (see the JMS specs) The default value assigned to every Connection.
`jms.emulateTransactions`	no	boolean	false	When a `SESSION_TRANSACTED` session is created in this mode, the Session behaves like a transacted Session but is not transactional: a produced message is sent immediately, and acknowledgements are sent during `session.commit()`. See Transaction Emulation.
`jms.enableClientSideEmulation`	no	boolean	false	Enable emulated features Enable features that are not supported directly by the Pulsar Broker but are emulated on the client side.
`jms.forceDeleteTemporaryDestinations`	no	boolean	false	Force the deletion of temporary destinations Use the Pulsar API to force the deletion even if the temporary destination has active subscriptions.
`jms.precreateQueueSubscription`	no	boolean	true	When set to `false`, the JMS client will not pre-create the subscription `jms-queue` Set `allowAutoSubscriptionCreation=false` in `broker.conf` to disable subscription auto-creation on the broker.
`jms.queueSubscriptionName`	no	String	jms-queue	Name of the system subscription used to emulate JMS Queues
`jms.systemNamespace`	no	String	public/default	Default Pulsar namespace in which temporary destinations and destinations without an explicit namespace are created
`jms.topicSharedSubscriptionType`	no	String	Shared	Type of subscription for Shared consumers - Shared\|Key_shared\|Failover Type of subscription is defined when a consumer connects to the subscription.
`jms.transactionsStickyPartitions`	no	boolean	false	Force all messages sent in scope of a transaction to go to the same partition.
`jms.useCredentialsFromCreateConnection`	no	boolean	false	Makes `authParams` the username/password pair passed to `ConnectionFactory.createConnection(username, password)` and `ConnectionFactory.createContext(username, password, mode)`
`jms.useExclusiveSubscriptionsForSimpleConsumers`	no	boolean	true	Use an Exclusive subscription for Topic consumers Set this to `false` to enable Delayed Messages.
`jms.usePulsarAdmin`	no	boolean	true	Allow the client to use the Pulsar Admin API Set this to `false` if your client cannot access the Admin HTTP API.
`jms.useServerSideFiltering`	no	boolean	false	Offloads message filtering to the Broker nodes. See Server Side Filters.
`jms.waitForServerStartupTimeout`	no	number	60000	Grace period in ms to wait for the Pulsar broker to be available Used to wait for Queue subscriptions to be ready.
`negativeAckRedeliveryBackoff`	no	`RedeliveryBackoff`	MultiplierRedeliveryBackoff	Interface for custom message is `ackTimeout` policy. You can specify `RedeliveryBackoff` for a consumer.
`producerConfig`	no	Map<String,Object>	Empty Map	Additional configuration for each Pulsar Producer
`webServiceUrl`	yes	String	`http://localhost:8080` (default)	Main Pulsar HTTP endpoint Must be customized as required for Pulsar standalone instances that are not running on localhost.

ackTimeout

long

Disabled

Set timeout for unacked messages. Must be >1 second.

ackTimeoutMillis

long

Same as ackTimeout, but expressed in milliseconds

brokerServiceUrl

String

If not specified, for Pulsar standalone instances running on localhost, defaults to the same value as webServiceUrl, `http://localhost:8080`. Can also be specified as `pulsar://localhost:6650` for Pulsar standalone instances on localhost.

The URL to connect to the Pulsar broker or proxy
The brokerServiceUrl must be specified for Astra Streaming. Must be customized as required for Pulsar standalone instances that are not running on localhost.

consumerConfig

Map<String,Object>

Empty Map

Additional configuration for each Pulsar Consumer.
For all valid consumer objects, see the Apache Pulsar documentation.

enableTransaction

boolean

false

Enable transactions
enableTransaction defaults to false because transaction support is not enabled by default in Pulsar 2.7 and the client cannot connect to a cluster that does not enable transactions.

jms.acknowledgeRejectedMessages

boolean

false

Force acknowledgment of filtered messages on shared subscriptions
By default, filtered messages are negatively acknowledged on shared subscriptions. If this flag is true, they are acknowledged in order to skip them definitively.

jms.allowTemporaryTopicWithoutAdmin

boolean

false

Allows temporary topic/queue creation and deletion to pass without errors when jms.usePulsarAdmin is set to false
Use the default values of allowAutoTopicCreation=true and allowAutoTopicCreationType=non-partitioned in broker.conf for auto-creation of temporary topics/queues.

jms.clientId

String

empty string

Administratively assigned clientId (see the JMS specs)
The default value assigned to every Connection.

jms.emulateTransactions

boolean

false

When a SESSION_TRANSACTED session is created in this mode, the Session behaves like a transacted Session but is not transactional: a produced message is sent immediately, and acknowledgements are sent during session.commit().
See Transaction Emulation.

jms.enableClientSideEmulation

boolean

false

Enable emulated features
Enable features that are not supported directly by the Pulsar Broker but are emulated on the client side.

jms.forceDeleteTemporaryDestinations

boolean

false

Force the deletion of temporary destinations
Use the Pulsar API to force the deletion even if the temporary destination has active subscriptions.

jms.precreateQueueSubscription

boolean

true

When set to false, the JMS client will not pre-create the subscription jms-queue
Set allowAutoSubscriptionCreation=false in broker.conf to disable subscription auto-creation on the broker.

jms.queueSubscriptionName

String

jms-queue

Name of the system subscription used to emulate JMS Queues

jms.systemNamespace

String

public/default

Default Pulsar namespace in which temporary destinations and destinations without an explicit namespace are created

jms.topicSharedSubscriptionType

String

Shared

Type of subscription for Shared consumers - Shared|Key_shared|Failover
Type of subscription is defined when a consumer connects to the subscription.

jms.transactionsStickyPartitions

boolean

false

Force all messages sent in scope of a transaction to go to the same partition.

jms.useCredentialsFromCreateConnection

boolean

false

Makes authParams the username/password pair passed to ConnectionFactory.createConnection(username, password) and ConnectionFactory.createContext(username, password, mode)

jms.useExclusiveSubscriptionsForSimpleConsumers

boolean

true

Use an Exclusive subscription for Topic consumers
Set this to false to enable Delayed Messages.

jms.usePulsarAdmin

boolean

true

Allow the client to use the Pulsar Admin API
Set this to false if your client cannot access the Admin HTTP API.

jms.useServerSideFiltering

boolean

false

Offloads message filtering to the Broker nodes. See Server Side Filters.

jms.waitForServerStartupTimeout

number

60000

Grace period in ms to wait for the Pulsar broker to be available
Used to wait for Queue subscriptions to be ready.

negativeAckRedeliveryBackoff

RedeliveryBackoff

MultiplierRedeliveryBackoff

Interface for custom message is ackTimeout policy. You can specify RedeliveryBackoff for a consumer.

producerConfig

Map<String,Object>

Empty Map

Additional configuration for each Pulsar Producer

webServiceUrl

yes

String

`http://localhost:8080` (default)

Main Pulsar HTTP endpoint
Must be customized as required for Pulsar standalone instances that are not running on localhost.

All other options are passed as configurations to the Pulsar Client and the Pulsar Admin client, allowing you to configure additional Pulsar features, including security.

Please check Apache Pulsar documentation for a complete list of configuration options.

Implementation details

Please refer to Implementation details in order to read about how Starlight for JMS emulates some features that are not directly supported by Pulsar.

Starlight for JMS standalone quickstart: Create a simple command line Java JMS client that connects to a local Pulsar installation.
Getting started with Starlight for JMS: Create a simple command line Java JMS client that connects to an Astra Streaming instance.
Installing Starlight for JMS: Install Starlight for JMS in your own JMS project.
Mapping Pulsar concepts to JMS specifications: Understand Pulsar concepts in the context of JMS.
Starlight for JMS implementation details: Understand key implementation details for Starlight for JMS.
Starlight for JMS FAQs: Frequently asked questions about Starlight for JMS.
Starlight for JMS Github repo

Starlight for JMS configuration reference

Configuration options

Implementation details

Next

Was this helpful?

Give Feedback