This project provides Spring Boot Auto-Configuration and an associated Spring Boot Starter for the Solace Java API. The goal of this project is to make it easy to auto wire the Solace Java API within your application so you can take advantage of all the benefits of Spring Boot auto-configuration.
- Overview
- Using Auto-Configuration in your App
- Building the Project Yourself
- Running the Sample
- Contributing
- Authors
- License
- Resources
As stated this project provides a Spring Boot Auto-Configuration implementation and a Spring Boot Starter pom for the Solace Java API. The goal of this project is to make it easier to use the Solace Java API with Spring Boot auto-configuration through the @Autowired annotation. This project is used internally within Solace to enable Spring Boot applications and as such it will be maintained and updated as our internal needs required.
The artifacts are published to Maven Central so it should be familiar and intuitive to use this project in your applications. If you find Solace Java API properties that this project does not yet support, simply raise an issue and we'll look into adding this support or submit a pull request with the update.
One item to note as described below is that this project introduces a new factory for Solace Java API sessions: SpringJCSMPFactory
. Overtime the Solace Java API may introduce a similar factory and remove the need for this custom extension. For now however, this is included in the auto-configuration jar for ease of use.
See the associated solace-java-sample-app
for an example of how this is all put together in a simple application. You'll need to do three steps:
- Update your build.
- Autowire a
SpringJCSMPFactory
. - Configure the application to use a Solace PubSub+ service.
The releases from this project are hosted in Maven Central
The easiest way to get started is to include the solace-java-spring-boot-starter
in your application. For an examples see the Java Sample App in this project.
Here is how to include the spring boot starter in your project using Gradle and Maven.
// Solace Java API & auto-configuration
compile("com.solace.spring.boot:solace-java-spring-boot-starter:1.+")
<!-- Solace Java API & auto-configuration-->
<dependency>
<groupId>com.solace.spring.boot</groupId>
<artifactId>solace-java-spring-boot-starter</artifactId>
<version>1.+</version>
</dependency>
Now in your application code, you can simply declare the SpringJCSMPFactory
and annotate it so that it is autowired:
@Autowired
private SpringJCSMPFactory solaceFactory;
Once you have the SpringJCSMPFactory
, it behaves just like the JCSMPFactory
and can be used to create sessions. For example:
final JCSMPSession session = solaceFactory.createSession();
The SpringJCSMPFactory
is a wrapper of the singleton JCSMPFactory
which contains an associated JCSMPProperties
. This facilitates auto-wiring by Spring but otherwise maintains the familiar JCSMPFactory
interface known to users of the Solace Java API.
Alternatively, you could autowire one or more of the following to create your own customized SpringJCSMPFactory
:
/* A factory for creating SpringJCSMPFactory. */
@Autowired
private SpringJCSMPFactoryCloudFactory springJcsmpFactoryCloudFactory;
/* A POJO describing the credentials for the first detected Solace PubSub+ service */
@Autowired
private SolaceServiceCredentials solaceServiceCredentials;
/* The properties of a JCSMP connection for the first detected Solace PubSub+ service */
@Autowired
private JCSMPProperties jcsmpProperties;
However note that the SolaceServiceCredentials
will only provide meaningful information if the application is configured by exposure of a Solace PubSub+ service manifest, and not by using the application properties file.
By using Spring Cloud Connectors, this library can automatically configure a SpringJCSMPFactory
using the detected Solace PubSub+ services when deployed on a Cloud Platform such as Cloud Foundry.
Currently, the Solace Cloud Foundry Cloud Connector is the only connector that is supported by default in this library, but could easily be augmented by adding your own Solace Spring Cloud Connectors as dependencies to the auto-configuration's POM.
For example:
<dependency>
<groupId>com.solace.cloud.cloudfoundry</groupId>
<artifactId>solace-spring-cloud-connector</artifactId>
<version>2.1.0</version>
</dependency>
Configuration of the SpringJCSMPFactory
can be done through exposing a Solace PubSub+ service manifest to the application's JVM properties or OS environment.
For example, you can set a SOLCAP_SERVICES
variable in either your JVM properties or OS's environment to directly contain a VCAP_SERVICES
-formatted manifest file. In which case, the autoconfigure will pick up any Solace PubSub+ services in it and use them to accordingly configure your SpringJCSMPFactory
.
The properties provided by this externally-provided manifest can also be augmented using the values from the application's properties file.
For details on valid manifest formats and other ways of exposing Solace service manifests to your application, see the Manifest Load Order and Expected Formats section in the Solace Services Info project.
Alternatively, configuration of the SpringJCSMPFactory
can also be done through the application.properties
file. This is where users can control the Solace Java API properties. Currently this project supports direct configuration of the following properties:
solace.java.host
solace.java.msgVpn
solace.java.clientUsername
solace.java.clientPassword
solace.java.clientName
solace.java.connectRetries
solace.java.reconnectRetries
solace.java.connectRetriesPerHost
solace.java.reconnectRetryWaitInMillis
Where reasonable, sensible defaults are always chosen. So a developer using a Solace PubSub+ message broker and wishing to use the default message-vpn must only set the solace.java.host
.
See SolaceJavaProperties
for the most up to date list.
Any additional Solace Java API properties can be set through configuring solace.java.apiProperties.<Property>
where <Property>
is the name of the property as defined in the Solace Java API documentation for com.solacesystems.jcsmp.JCSMPProperties
, for example:
solace.java.apiProperties.reapply_subscriptions=false
Note that the direct configuration of solace.java.
properties takes precedence over the solace.java.apiProperties.
.
This project depends on maven for building. To build the jar locally, check out the project and build from source by doing the following:
git clone https://github.com/SolaceProducts/solace-java-spring-boot.git
cd solace-java-spring-boot
mvn package
This will build the auto-configuration jar and associated sample.
Note: As currently setup, the build requires Java 1.8. If you want to use another older version of Java adjust the build accordingly.
The simplest way to run the sample is from the project root folder using maven. For example:
mvn spring-boot:run
Please read CONTRIBUTING.md for details on the process for submitting pull requests to us.
See the list of contributors who participated in this project.
This project is licensed under the Apache License, Version 2.0. - See the LICENSE file for details.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
For more information about Spring Boot Auto-Configuration and Starters try these resources:
- Spring Docs - Spring Boot Auto-Configuration
- Spring Docs - Developing Auto-Configuration
- GitHub Tutorial - Master Spring Boot Auto-Configuration
For more information about Solace technology in general please visit these resources:
- The Solace Developer Portal website at: http://dev.solace.com
- Understanding Solace technology.
- Ask the Solace community.