= Java CFEnv image:https://build.spring.io/plugins/servlet/wittified/build-status/CFENV-BMASTER[Build Status, link=https://build.spring.io/browse/CFENV-BMASTER]
Java CFEnv is a library for easily accessing the environment variables set when deploying an application to Cloud Foundry.
It is modeled after the design of the node library https://github.com/cloudfoundry-community/node-cfenv/[node-cfenv] and other -cfenv libraries in the Cloud Foundry ecosystem.
The class CfEnv is the entry point to the API for accessing Cloud Foundry environment variables.
In a Spring application, you can use the https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#expressions-bean-references[Spring Expression Language] to invoke methods on bean of type CfEnv to set properties.
CFEnv's Boot support sets https://docs.spring.io/spring-boot/docs/current/reference/html/appendix-application-properties.html#common-application-properties[common application properties] so that Java objects such as the DataSource or the RabbitConnectionFactory are created using Spring Boot autoconfiguration.
The https://spring.io/blog/2019/02/15/introducing-java-cfenv-a-new-library-for-accessing-cloud-foundry-services[1.0 M1 blog] provides some additional background information.
== Compatibility === https://github.com/pivotal-cf/java-cfenv/tree/main[3.x]
https://projects.spring.io/spring-framework/[Spring Framework] 6.x
=== https://github.com/pivotal-cf/java-cfenv/tree/2.5.x[2.x]
https://projects.spring.io/spring-framework/[Spring Framework] 5.3+
== Dependency Info
You can access the stable release from maven central using the coordinates
== SCS and SSO modules If you're attempting to connect a client app to a https://docs.pivotal.io/spring-cloud-services/3-1/common/client-dependencies.html[Spring Cloud Services] or https://docs.pivotal.io/p-identity/1-11/integrating-sso.html[Single Sign-On] service instance, you should follow their respective docs.
== Introduction
The entry point is the class CfEnv which parses Cloud Foundry environment variables such as VCAP_SERVICES.
The information in VCAP_SERVICES is a JSON string that contains credential information to access bound services, such as a database.
For example, here is the value of VCAP_SERVICES for an application bound to the mysql and redis services.
The keys in the JSON are not always identical across services, for example in the above JSON the mysql service has added the key named hostname to the credentials while the redis service has contributed the key named host.
Most relational database services do not expose a key named jdbcUrl so the URL needs to be created by extracting individual fields and building up the URL string. Since this is such a common case, the CfEnv library provides support to retrieve the URL string for several databases.
To get access to a specific service's credentials, the keys tag, name, or label can be specified as a criteria for selecting one of the services in the array.
== Basic usage Using the JSON from the previous section, here are some simple API calls to extract credential information.
Multiple strings can be passed to match against more than one tag.
There are additional finder methods to search by name and label and the finder method support passing a regex string for pattern matching.
The classes CfService and CfCredentials are returned from the following API calls and have methods for accessing common fields in addition to a generic get(String) map API.
CfEnv cfEnv = new CfEnv();
List
CfService redisService = cfEnv.findServiceByTag("redis");
List
CfCredentials redisCredentials = cfEnv.findCredentialsByTag("redis"); String redisPort = redisCredentials.getPort(); Integer redisPort = redisCredentials.getMap().get("port");
The class CfVolume contains information for a shared disk provided by Cloud Foundry volume services.
You can access it using the getVolumes method on CfService as shown below.
=== JDBC Support
spring-cfenv-jdbc.
The entry point to the API is the class CfJdbcEnv which is a subclass of CfEnv and adds a few methods.
The method findJdbcService will heuristically look at all services for known tags, labels and names of common database services to create the URL.
[source,java]CfJdbcEnv cfJdbcEnv = new CfJdbcEnv() CfJdbcService cfJdbcService = cfJdbcEnv.findJdbcService();
If there is more than one database bound to the application, an exception will be thrown and you should use the findJdbcServiceByName method to locate a unique database service.
If you are creating a user-provided-service in order to connect to a database by jdbc, provide a uri property along with username and password in the credentials block.
Alternatively, you can simply provide a fully qualified jdbcUrl.
In either case, consult your database provider's documentation on the correct format of a connection uri. This library will preserve any platform specific uri elements.
=== Use with Spring
If you register the CfJdbcEnv class as a bean, then you can use the Spring Expression Language to set properties.
Then in a property file imported by Spring, refer to the CfJdbcEnv bean using the following syntax.
Or say for cassandra, you can use the CfEnv class registered as a bean.
=== Using Spring Boot
Please check the dedicated README for link:java-cfenv-boot/README.adoc[Spring Boot].
=== Connecting Multiple Instances of a Single Service Type
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, you will need to follow the approach layed out in the sections above (Basic Usage, JDBC Support, Use with Spring) to access the binding credentials. Then follow the same procedure that would be used to connect to your services in any other deployment environment.
=== Pushing your application to Cloud Foundry
You must disable the java buildpack's auto-reconfiguration so that you always delegate to Boot to create beans.
Since the auto-reconfiguration also set the cloud profile, you will have to do that explicitly
== Supporting other Services
The interface https://github.com/pivotal-cf/java-cfenv/blob/master/java-cfenv-boot/src/main/java/io/pivotal/cfenv/spring/boot/CfEnvProcessor.java[`CfEnvProcessor] simplifies what you need to write in most cases. The environment post processor, https://github.com/pivotal-cf/java-cfenv/blob/master/java-cfenv-boot/src/main/java/io/pivotal/cfenv/spring/boot/CfEnvironmentPostProcessor.java[CfEnvPostProcessor] delegates to all CfEnvProcessors that are discovered using Spring'sSpringFactoriesLoader`.
Here is the implementation for MongoDB
public class MongoCfEnvProcessor implements CfEnvProcessor {
private static String mongoScheme = "mongodb";
@Override public boolean accept(CfService service) { <1> return service.existsByTagIgnoreCase("mongodb") || service.existsByLabelStartsWith("mongolab") || service.existsByUriSchemeStartsWith(mongoScheme) || service.existsByCredentialsContainsUriField(mongoScheme); }
@Override public void process(CfCredentials cfCredentials, Map<String, Object> properties) { <2> properties.put("spring.data.mongodb.uri", cfCredentials.getUri(mongoScheme)); }