Session Properties Required to Establish a Connection in the PubSub+ JCSMP API

When a Session is created, default values are assigned to its settings, but can be modified if required. How to modify the following settings are explained in this section.

• Authentication Scheme
• Client Name
• Host
• Local Host
• Message VPN

For a complete list of Session properties, valid parameters, and the default values, see the PubSub+ Messaging API for JCSMP reference.

For an example of how to define the required Session properties when using a basic authentication scheme, which is the default, see the DirectPubSub sample in the Solace Developer Hub. Although other samples make use of common code, the DirectPubSub sample explicitly includes the methods used to create Session properties and create a session.

Authentication Scheme

When a host event broker initially accepts a connection from a client, that connection is in an unauthenticated state, and the event broker cannot process any requests from the client until the connection is authenticated.

The authentication scheme specifies the credentials that a client will use to authenticate its connection to the event broker. The authentication scheme can be one of the following:

• Basic authentication

The default client authentication scheme; it allows a client to authenticate with an event broker using a valid client username and password. For more information, see Basic Authentication.

• Client certificate authentication

A client authentication scheme that allows a client to prove its identity to the event broker through an X509v3 client certificate. This authentication scheme also requires the client to use a secure connection. For more information, see Client Certificate Authentication.

• Kerberos authentication

A client authentication scheme that uses Kerberos to authenticate a connecting client using a ticket that the client obtains through an approved Ticket Granting Service (TGS). For more information, see Kerberos Authentication.

• OAuth Authentication

  A client authentication scheme that allows a client application to use OAuth to authenticate its connection with event brokers. You can use either OAuth2 or OIDC tokens. For more information, see OAuth Authentication

All of these client authentication schemes require explicit input to successfully authenticate a client. For more information, see Defining Client Authentication Info in the PubSub+ JCSMP API.

Client Name

When connecting a Session to an event broker, a unique client name is required to register that particular client with the event broker. If no client name is entered, the API automatically generates a unique client name. By default, this parameter is not specified.

The client name is also used to uniquely identify the sender in a message’s senderId field when the Session property to generate a sender ID is set.

The client name property is the same as the client property that can be displayed through the event broker CLI or SolAdmin.

When the Session property to generate a sender ID is set, the client name is included the message’s senderId field to uniquely identify the sender.

To set a client name, use JCSMPProperties.CLIENT_NAME:

properties.setProperty(JCSMPProperties.CLIENT_NAME, myClientName);

Host

The host event broker to connect or reconnect the Session to. An application can connect directly to a host event broker in one of the following ways:

• Connecting Directly to Host Event Brokers
• Connecting to Host Event Broker Through Proxies in the PubSub+ JCSMP API

Connecting Directly to Host Event Brokers

To connect to a session directly to an event broker use a host entry composed as follows:

[Protocol:]Host[:Port]

Where:

• Protocol is the protocol used for the transport channel. The valid values are:
• For the JCSMP API the valid values are:
• tcp: or tcp://—Use a TCP channel for communications between the application and the event broker. If no protocol is set, TCP is used by default.
• tcps: or tcps://—Use a TLS/SSL channel over TCP for secure communications between the application and the event broker.
• ws: or ws://—Use a WebSockets transport for communication between the application and the event broker.
• wss: or wss://—Use a TLS/SSL channel over WebSockets for secure communication between the application and the event broker.
• Host is one or more IP addresses or hostnames of event brokers to connect to.
• Up to 16 potential hosts to connect or reconnect to can be listed in a comma‑separated list. Listing more than one host allows a client to attempt to connect or reconnect to alternate hosts should the first event broker be unavailable. Connect or reconnect attempts are made to the hosts in the order in which they are presented in the list. The listed host event brokers may be in separate geographic locations.
• When event brokers are operating in high-availability (HA) redundant pairs, do not list both event brokers in the pair as hosts. The redundant pair use the same IP address for the connection, so they appear as one event broker to the messaging API.
• The connect and reconnect behavior of a client is controlled by the channel or Session properties used for its connection with the event broker. Its reconnect behavior is also affected by whether the client application is publishing Guaranteed messages. For more information, refer to Connect Retries Per Host.
• In a Windows environment, a fully qualified domain name (FQDN) should be used for the host parameter, and it must match the FQDN that the event broker uses for the Kerberos Service Principal Name (SPN).
• Port is the port number to use to establish the connection.
• A value is only required when the client needs to use a port other than the automatically‑assigned default port number. The default port number for TCP is 55555 when compression is not in use, or 55003 when compression is in use. The default port for TLS/SSL is 55443, and you use the same port if you use TLS with compression. The default port numbers for:
  • http/ws is 80 for appliances or 8008 for software event brokers
  • https/wss is 443 for appliances or 1443 for software event brokers

Examples:

The following examples show how to connect directly to an event broker. Unless it is otherwise specified, the default port 55555 is used.

• 192.168.160.28—Connect to IP address 192.168.160.28 over TCP.
• dev212— Connect to hostname dev212 over TCP.
• dev212.solacesystems.com—Connect to hostname dev212.solacesystems.com over TCP.
• tcp:192.168.160.28—Connect to IP address 192.168.160.28 over TCP.
• tcps:192.168.160.28—Connect to IP address 192.168.160.28 and port 55443 with TLS/SSL over TCP.
• tcp:192.168.160.28:65535—Connect to IP address 192.168.160.28 and port 65535 over TCP.

When a SPN is generated for the client, the following format is used: service_name/<customer-provided_host>@REALM. The service name portion is configured through the KRB service name session property (by default, it is solace), and the realm portion is determined by the KRB library’s configuration files. An example of a resulting service principle name is solace/dev212@SIMPLESPNEXAMPLE.COM.

When using multiple hosts, the host used for the current connection generates the SPN.

Connecting to Host Event Broker Through Proxies in the PubSub+ JCSMP API

You can establish a connection to an event broker within your private network via an HTTP or SOCKS5 proxy server, which avoids the need for individual firewall exceptions. The proxy configuration is set with system properties, that are usually set on the java command line or JVM. It is important to note that system properties set on a JVM instance apply to all java applications running on the same JVM.

java -Dsolace.proxy.host=proxy.example.com javaApp
or
java -Dsolace.proxy.host=192.168.1.100 javaApp

java -Dsolace.proxy.type=http javaApp
or
java -Dsolace.proxy.type=socks5 javaApp            

java -Dsolace.proxy.port=8080 javaApp 

java -Dsolace.proxy.username=my_proxy_username javaApp					

java -Dsolace.proxy.password=my_proxy_password javaApp					

The following code snippet sets all proxy server parameters:

java -Dsolace.proxy.type={http} -Dsolace.proxy.host={proxy.example.com} \
			-Dsolace.proxy.port={8080} -Dsolace.proxy.username={my_proxy_username} \
			-Dsolace.proxy.password={my_proxy_password} javaApp

Local Host

The hostname or IP address of the machine on which the application is running. This Session property may be required when the application is running on a multi‑homed machine.

On a multi-homed machine, a local hostname or IP address helps ensure that the API uses the correct network interface for communication with the event broker.

To set a local host, use JCSMPProperties.LOCAL_HOST:

properties.setProperty(JCSMPProperties.LOCAL_HOST, myHost);

Message VPN

The name of the Message VPN on the host event broker to connect the client to.

Message VPNs are created on the event broker to provide isolation between groups of clients connecting to Solace PubSub+.

If a specific Message VPN is not provided, the Message VPN named default is used. The default Message VPN is always present on an event broker. Although a network administrator can change the configuration settings for default, it cannot be deleted.

To set a message VPN, use JCSMPProperties.VPN_NAME:

properties.setProperty(JCSMPProperties.VPN_NAME, myVPN);