Configuring service connections

Page last updated:

The path for configuring service access in your Java based applications is the java-cfenv library. This library can read and parse VCAP_SERVICES and help you extract the information for use in your application.

There are a number of ways to implement this and all Java applications can use the library; it is not limited to specific frameworks. To get started, you must first add a dependency in your project for the library.

java-cfenv modules

The java-cfenv project is split into several modules. Add only the modules that your app needs. Each module includes the modules it depends on.

java-cfenv added by the Java buildpack

For Spring Boot 3.x and 4.x apps, the Java buildpack (v5) automatically adds java-cfenv-all at staging time, in the version that matches the Spring Boot major version. The buildpack does this only if the app does not already contain any java-cfenv JAR. If your app includes any java-cfenv module, the buildpack adds nothing and your app uses only the modules that it includes.

To turn off the automatic installation, set JBP_CONFIG_JAVA_CF_ENV: '{enabled: false}' in the env: block of your manifest.yml file.

Dependencies

Choose the java-cfenv (or java-cfenv-* module) version that matches your Spring Boot version. All modules share the same version number:

• java-cfenv 4.x for Spring Boot 4.x (4.0.2 or later)
• java-cfenv 3.x for Spring Boot 3.x (3.5.3 or later)
• java-cfenv 2.x for Spring Boot 2.x is end of life

For more information, see the compatibility matrix in the java-cfenv repository on GitHub.

The following examples show the dependency syntax for Maven and Gradle.

For Maven:

<dependency>
  <groupId>io.pivotal.cfenv</groupId>
  <artifactId>java-cfenv</artifactId>
  <version>4.0.2</version>
</dependency>

For Gradle:

implementation "io.pivotal.cfenv:java-cfenv:4.0.2"

Java-only / No framework

The entry point for the library is the class CfEnv, which parses Cloud Foundry environment variables. For example, VCAP_SERVICES. VCAP_SERVICES which contains a JSON string that includes credential information used to access bound services, for example, databases.

Create a CfEnv instance and use its findCredentialsBy* methods. There are methods for finding by label, name, and tag. Multiple strings can be passed to match against more than one tag, and the finder method supports passing a regex string for pattern matching.

For example:

CfEnv cfEnv = new CfEnv();

String redisHost = cfEnv.findCredentialsByTag("redis").getHost();
String redisPort = cfEnv.findCredentialsByTag("redis").getPort();
String redisPassword = cfEnv.findCredentialsByTag("redis").getPassword();

List<CfService> cfService = cfEnv.findAllServices();

CfService redisService = cfEnv.findServiceByTag("redis");
List<String> redisServiceTags = redisService.getTags();
String redisPlan = redisService.getPlan();
redisPlan = redisService.get("plan")

CfCredentials redisCredentials = cfEnv.findCredentialsByTag("redis");
String redisPort = redisCredentials.getPort();
Integer redisPort = redisCredentials.getMap().get("port");

cfService = cfEnv.findServiceByName("redis");
cfService = cfEnv.findServiceByLabel("p-redis");
cfService = cfEnv.findServiceByLabel(".*-redis");

JDBC support

There is additional support for getting a JDBC URL from a service binding. This support is contained in the module java-cfenv-jdbc. To enable this module, add the appropriate dependency.

For Maven:

<dependency>
  <groupId>io.pivotal.cfenv</groupId>
  <artifactId>java-cfenv-jdbc</artifactId>
  <version>4.0.2</version>
</dependency>

For Gradle:

implementation "io.pivotal.cfenv:java-cfenv-jdbc:4.0.2"

The entry point for this feature is the class CfJdbcEnv, which is a subclass of CfEnv and adds a few methods. The method findJdbcService heuristically looks at all services for known tags, labels, and names of common database services to create the URL.

For example:

CfJdbcEnv cfJdbcEnv = new CfJdbcEnv()
CfJdbcService cfJdbcService = cfJdbcEnv.findJdbcService();

String jdbcUrl = cfJdbcService.getJdbcUrl();
String username = cfJdbcService.getUsername();
String password = cfJdbcService.getPassword();
String driverClassName = cfJdbcService.getDriverClassName();

Spring Framework

The Spring Framework provides additional support for application developers.

Spring Expression Language

If you register the CfJdbcEnv class as a bean, then you can use the Spring Expression Language to set properties.

@Bean
public CfEnv cfEnv() {
  return new CfEnv();
}

Then, in the properties file imported by Spring, refer to the CfEnv bean using the following syntax:

cassandra.contact-points=#{ cfEnv.findCredentialsByTag('cassandra').get('node_ips') }
cassandra.username=#{ cfEnv.findCredentialsByTag('cassandra').getUserName() }
cassandra.password=#{ cfEnv.findCredentialsByTag('cassandra').getPassword() }
cassandra.port=#{ cfEnv.findCredentialsByTag('cassandra').get('cqlsh_port') }

To specifically target JDBC databases, register this instead:

@Bean
public CfJdbcEnv cfJdbcEnv() {
  return new CfJdbcEnv();
}

Then in a property file imported by Spring, refer to the CfJdbcEnv bean using the following syntax:

myDatasourceUrl=#{ cfJdbcEnv.findJdbcService().getUrl() }

Spring Boot

The module java-cfenv-boot provides several EnvironmentPostProcessor implementations that set well-known Spring Boot properties so that Spring Boot’s auto-configuration is active. For example, the CfDataSourceEnvironmentPostProcessor sets the Spring Boot property, spring.datasource.url.

To use these, add a dependency on java-cfenv-boot.

For Maven:

<dependency>
  <groupId>io.pivotal.cfenv</groupId>
  <artifactId>java-cfenv-boot</artifactId>
  <version>4.0.2</version>
</dependency>

For Gradle:

implementation "io.pivotal.cfenv:java-cfenv-boot:4.0.2"

The list of supported services are:

• Databases - DB2, MySQL, Oracle, PostgreSQL, SQL Server
• RabbitMQ
• Cassandra
• MongoDB
• Redis
• CredHub
• HashiCorp Vault

If you need to prevent processing of a specific service instance, set the flag in your application properties to:

cfenv.service.{serviceName}.enabled=false

Migrating from Spring AutoReconfiguration and Spring Cloud Connectors

The java-cfenv library replaces the older Spring AutoReconfiguration and Spring Cloud Connectors libraries. Use the information in the following sections to migrate to java-cfenv.

Change dependencies

Remove references to any of these libraries from the application build files.

org.springframework.boot:spring-boot-starter-cloud-connectors

or

org.springframework.cloud:spring-cloud-core
org.springframework.cloud:spring-cloud-connectors-core
org.springframework.cloud:spring-cloud-cloudfoundry-connector
org.springframework.cloud:spring-cloud-spring-service-connector

Then add a reference to the java-cfenv library.

Code changes

Remove any of the @ServiceScan or @CloudScan annotations from Spring Java configuration classes (provided by Spring Cloud Connectors). Replace them with the Spring SPeL or Spring Boot configuration options listed above.

Migration considerations

Review these additional considerations before you migrate.

• Non-Spring Boot applications:
  
  If you have a Spring Application that is a non-Spring Boot application, you can still migrate to java-cfenv. You must use either the no framework options or the Spring SPeL option. With SPeL, you might need to manually process the expressions, depending on where you are configuring them. See the Spring documentation for places where SPeL expressions are processed by default.
  
  

• Multiple service instances:
  
  Spring Cloud Connectors support connections to multiple service instances.
  
  If you need to configure connections to multiple instances of a given service type, or do anything more than setting application properties for Spring Boot to pick up and use in auto-configuration, then you must follow the manual configuration approaches laid out in the sections above to access the binding credentials. Either with direct Java code or with SPeL. Then follow the same procedure that is used to connect to the services in any other non-Cloud Foundry deployment environment.
  
  

• Code modifications:
  
  When enabled, the Java Buildpack injects the Spring Auto Reconfiguration module code into your application and overwrites your service configuration. This works well in some cases, but sometimes it causes problems. As of Java buildpack v5, Spring Auto Reconfiguration is deactivated by default.
  
  With java-cfenv, there is no auto-reconfiguration magic. You can explicitly configure your services or you can use the Spring Boot mappers. The Spring Boot mappers are the option most similar to previous operation. Note, that when things don’t work, it’s generally clearer what happened, and it’s easier to debug the problem.
  
  

• Cloud property placeholders:
  
  The Spring Auto Reconfiguration module exposes a set of property placeholder values that you can use to access values from VCAP_SERVICES. If you are using these placeholders, then you must switch from using cloud.<property>. Use vcap.<property> instead.
  
  Spring Boot exposes the same information, just under the vcap. prefix instead of the cloud. prefix.
  
  

• Spring Cloud Profile:
  
  The Spring Auto Reconfiguration module enables a Spring Profile called cloud, by default. Users have come to expect this behavior when deploying to Cloud Foundry.
  
  The java-cfenv-all module activates the cloud profile when running on Cloud Foundry. The other java-cfenv modules do not. If the Java buildpack adds java-cfenv-all to your app, no action is needed. If your app includes its own java-cfenv modules other than java-cfenv-all (for example, only java-cfenv-boot), is not a Spring Boot 3.x or 4.x app, or you turned off the automatic java-cfenv installation, the cloud profile is not active. You can enable it using one of these methods:

  • Run cf set-env <APP> SPRING_PROFILES_ACTIVE cloud
  • Add SPRING_PROFILES_ACTIVE: cloud to the env: block in your manifest.yml file. This supplies the list of profiles for Spring to use.

  If you need to set additional profiles, you can use SPRING_PROFILES_INCLUDE instead. This appends to the existing set of profiles.
  
  

• Spring Cloud Connector extensions:
  
  If you have created any custom Spring Cloud Connector extensions, you must migrate them to java-cfenv. This requires two steps:

  1. Write a Spring Boot Auto Configuration library that creates connections to your service from Spring configuration properties. This makes it easy to also use it in a non-cloud Spring Boot app. When this is done correctly, you can to use the library, and set properties in application.properties (or through other means), and you can have a connection to your service.
  2. Write a java-cfenv extension. This takes values from VCAP_SERVICES and maps them to the properties that you exposed with your Spring Boot Auto Configuration library from the previous step.

Java Buildpack warnings

The Java Buildpack generates warnings to help with migrating from Spring Cloud Connectors and Spring Auto Reconfiguration.

• Spring Auto Reconfiguration installed:
  
  As of Java buildpack v5, Spring Auto Reconfiguration is deactivated by default. The buildpack only installs the Spring Auto Reconfiguration JAR if you explicitly enable it with JBP_CONFIG_SPRING_AUTO_RECONFIGURATION: '{enabled: true}' and your app does not include java-cfenv. When it does, the buildpack generates this message:

  **WARNING** ATTENTION: The Spring Auto Reconfiguration and shaded Spring Cloud Connectors libraries are being installed. These projects have been deprecated and are no longer receiving updates.
  **WARNING** Spring Auto Reconfiguration is now DISABLED BY DEFAULT. You have explicitly enabled it via `JBP_CONFIG_SPRING_AUTO_RECONFIGURATION='{enabled: true}'`. Please migrate to java-cfenv as soon as possible.
  **WARNING** For migration instructions, see https://via.vmw.com/EiBW. Once you migrate to java-cfenv, these warnings will disappear.
  

  To clear this message, migrate your application to the java-cfenv library:

  • Make the code changes in your application to use the java-cfenv library. See the instructions above for how to include the dependencies and how to access service information using this library. After you have added java-cfenv to your classpath, the Java buildpack no longer installs the Auto Reconfiguration JAR and you no longer see this message.
  • Then remove JBP_CONFIG_SPRING_AUTO_RECONFIGURATION from your app environment, for example with cf unset-env <APP> JBP_CONFIG_SPRING_AUTO_RECONFIGURATION, or from the env: block in your manifest.yml file.

• Spring Cloud Connectors present:
  
  When Spring Auto Reconfiguration is enabled, the following message is generated when the buildpack detects that the Spring Cloud Connectors library is present on the classpath.

  WARNING ATTENTION: The Spring Cloud Connectors library is present in your application. This library has been in maintenance mode since July 2019 and is no longer receiving updates.
  WARNING Please migrate to java-cfenv immediately. See https://via.vmw.com/EiBW for migration instructions.
  

  When this message appears, it means that your application or one of its dependencies is including the Spring Cloud Connectors library. You must remove it and migrate to java-cfenv.
  
  After you have migrated to java-cfenv, and the Spring Cloud Connectors libraries are no longer on your classpath, this message no longer appears. It also does not appear when Spring Auto Reconfiguration is deactivated, which is the default.