Skip to content

framework-java-cfenv.md

Latest commit

 

History

History
103 lines (74 loc) · 6.9 KB

framework-java-cfenv.md

File metadata and controls

103 lines (74 loc) · 6.9 KB
Raw

Java CfEnv Framework

The Java CfEnv Framework provides the java-cfenv library for Spring Boot 3.x and 4.x applications. This library sets various Spring Boot properties by parsing Cloud Foundry variables such as VCAP_SERVICES, allowing Spring Boot's autoconfiguration to kick in.

This is the recommended replacement for Spring AutoReconfiguration library which is deprecated. See the java-cfenv repository for more details.

The cloud Spring profile is activated at runtime by java-cfenv's CloudProfileApplicationListener, which ships in the java-cfenv-all module. To ensure the profile is active — or to activate it independently of java-cfenv — set it explicitly. Use SPRING_PROFILES_INCLUDE=cloud to add cloud alongside any other active profiles, or SPRING_PROFILES_ACTIVE=cloud to set it as the sole active profile (this replaces any others). The buildpack itself does not set any Spring profile.

The buildpack selects the appropriate java-cfenv version based on the detected Spring Boot major version:

Spring Boot java-cfenv
3.x 3.x (latest)
4.x 4.x (latest)
Detection Criterion Existence of a spring-boot-3.*.jar or spring-boot-4.*.jar in BOOT-INF/lib, WEB-INF/lib, or lib/; or a Spring-Boot-Version: 3.* / Spring-Boot-Version: 4.* entry in META-INF/MANIFEST.MF No existing java-cfenv library found in the application
Tags java-cf-env=<version>
Tags are printed to standard output by the buildpack detect script

How it works

The framework is implemented in src/java/frameworks/java_cf_env.go:

  1. Detect — activates only when all of these hold: the framework is enabled (see Configuration); a Spring Boot 3.x or 4.x marker is found (a spring-boot-{3,4}.*.jar under BOOT-INF/lib, WEB-INF/lib, or lib/, or a Spring-Boot-Version: 3.* / 4.* entry in META-INF/MANIFEST.MF); and the application does not already bundle a java-cfenv*.jar (if it does, the buildpack backs off and uses the application's own copy).
  2. Supply — selects the java-cfenv version from the detected Spring Boot major (Spring Boot 3 → the manifest's 3.x line, Spring Boot 4 → the 4.x line) and installs the java-cfenv-all jar into the dependency directory.
  3. Finalize — appends the installed jar to CLASSPATH via a .profile.d/java_cf_env.sh script, so it is on the application's runtime classpath.
  4. Runtime — Spring Boot reads the jar's META-INF/spring.factories: the EnvironmentPostProcessors map VCAP_SERVICES to Spring properties, and CloudProfileApplicationListener (in the java-cfenv-all module) activates the cloud profile when running in Cloud Foundry.

VCAP_SERVICES auto-configuration

Spring Boot has built-in support for flattening VCAP_SERVICES into vcap.services.<name>.credentials.* properties (CloudFoundryVcapEnvironmentPostProcessor). This works without java-cfenv but does not set spring.datasource.url or activate the cloud profile.

java-cfenv-all adds service-aware auto-configuration on top: it detects bound services by tag, label, or URI scheme and maps them to the appropriate Spring Boot properties. For example, a bound PostgreSQL service with URI postgres://host:5432/db is automatically mapped to spring.datasource.url=jdbc:postgresql://host:5432/db (plus username, password, and driver class). For reactive apps, spring.r2dbc.* properties are set as well. With a single bound database service, no application.yml DataSource configuration is needed.

This behavior is identical across java-cfenv 3.x and 4.x (the only difference is a Spring Boot 4 package relocation of EnvironmentPostProcessor).

JDBC services (CfDataSourceEnvironmentPostProcessor)

Service Matching criteria JDBC prefix
PostgreSQL tag postgresql/postgres, label prefix postgresql, URI scheme postgres:///postgresql:// jdbc:postgresql://
MySQL / MariaDB tag mysql/mariadb, label prefix mysql/mariadb, URI scheme mysql:///mariadb:// jdbc:mysql:// or jdbc:mariadb://
SQL Server label prefix sqlserver, URI scheme sqlserver:// jdbc:sqlserver://
Oracle label prefix oracle, URI scheme oracle:// jdbc:oracle:thin:@
DB2 tag db2/sqldb/dashDB, label prefix db2, URI scheme db2:// jdbc:db2://

Other services (CfEnvProcessor implementations)

Service Matching criteria Properties set
MongoDB tag mongodb, label prefix mongolab/mongodb spring.data.mongodb.uri
Redis tag redis, URI scheme redis:///rediss:// spring.data.redis.*
RabbitMQ tag rabbitmq/amqp, URI scheme amqp:///amqps:// spring.rabbitmq.*

Configuration

The framework can be disabled via the JBP_CONFIG_JAVA_CF_ENV environment variable:

cf set-env <app> JBP_CONFIG_JAVA_CF_ENV '{enabled: false}'
cf restage <app>

The buildpack only re-reads this variable during staging, so a cf restage is required for the change to take effect.

To re-enable, either set it back to {enabled: true} or remove the variable entirely:

cf unset-env <app> JBP_CONFIG_JAVA_CF_ENV
cf restage <app>
Variable Default Description
JBP_CONFIG_JAVA_CF_ENV {enabled: true} Enable or disable the framework

Note: if java-cfenv*.jar is already present in the application, the buildpack skips injection automatically — no need to disable explicitly for that case.

Disable when:

  • The application handles VCAP_SERVICES manually with custom binding logic
  • The automatic cloud profile activation is unwanted
  • Another service binding library conflicts with java-cfenv

{enabled: false} disables the whole framework — both the VCAP_SERVICES → Spring property mapping and the cloud profile activation. There is no option to disable only the cloud profile.

For finer control, bundle a java-cfenv artifact in the application yourself. Because the buildpack backs off whenever a java-cfenv*.jar is already present, the app's choice wins:

App bundles Property mapping cloud profile
(nothing — buildpack injects java-cfenv-all) yes yes
java-cfenv-all yes yes (app pins the version)
java-cfenv-boot yes no (no CloudProfileApplicationListener)
java-cfenv (core) no (API only) no

So an app can include java-cfenv-boot to keep property mapping without the cloud profile, or the bare java-cfenv core to opt out of all automatic behaviour and use the CfEnv API directly.