Cloud Foundry Java Client

The cf-java-client project provides Java bindings for interacting with Cloud Foundry. It is modularized into several components depending on the required level of abstraction:

• cloudfoundry-client: Contains interfaces, request, and response objects that map to the Cloud Foundry REST APIs. It is an API-only module and does not contain an implementation.
• cloudfoundry-client-reactor: The default implementation of cloudfoundry-client, built using Reactor Netty HttpClient.
• cloudfoundry-operations: Provides an API and implementation that corresponds to the Cloud Foundry CLI operations. It builds on top of cloudfoundry-client and has a single implementation.

The lowest-level building blocks are ConnectionContext and TokenProvider. These are intended to be shared between client instances. You can instantiate them using their respective builders. In Spring applications, these should be defined as @Beans.

DefaultConnectionContext.builder()
    .apiHost(apiHost)
    .build();

PasswordGrantTokenProvider.builder()
    .password(password)
    .username(username)
    .build();

Integration tests can be run using the Maven wrapper.

WARNING: Integration tests require admin access and are destructive. They should only be run against an empty Cloud Foundry instance as they affect nearly everything on the instance. It is strongly recommended to take a snapshot of your VMs before running them to allow for quick rollbacks.

To run all integration tests:

$ ./mvnw -Pintegration-test clean test

To run a specific integration test class or method, use the -Dtest flag:

./mvnw -Pintegration-test clean test -Dtest=org.cloudfoundry.client.v3.ServiceBrokersTest#update

To run tests with HTTP trace output enabled:

CLIENT_LOGGING_LEVEL=trace ./mvnw -Pintegration-test clean test

To build the project from source and install it to your local Maven cache, ensure you have Java 8 installed and have initialized submodules. Note that because the project uses Immutables, you must have an enabled annotation processor in your IDE (Eclipse or IntelliJ) for successful compilation.

$ git submodule update --init --recursive
$ ./mvnw clean install

If you encounter issues, you can capture request and response information by adjusting the logging levels. For Spring Boot applications, use the following configuration:

• To capture basic request/response info: set logging.level.cloudfoundry-client=debug.
• To perform a wire capture (full trace): set logging.level.cloudfoundry-client.wire=trace.

The CloudFoundryClient provides more granular control over requests, such as pagination. The following example demonstrates how to request the first page of organizations and map the raw response resources to OrganizationSummary objects.

cloudFoundryClient.organizations()
    .list(ListOrganizationsRequest.builder()
        .page(1)
        .build())
    .flatMapIterable(ListOrganizationsResponse::getResources)
    .map(resource -> OrganizationSummary.builder()
        .id(resource.getMetadata().getId())
        .name(resource.getEntity().getName())
        .build());

Once you have a CloudFoundryOperations instance, you can perform high-level tasks. The following example lists all organizations the user belongs to, extracts their names, and prints them to the console using reactive operators.

cloudFoundryOperations.organizations()
    .list()
    .map(OrganizationSummary::getName)
    .subscribe(System.out::println);

While the clients provide direct access to raw REST APIs, most users should work at the CloudFoundryOperations layer. This layer provides a higher level of abstraction. The default implementation is DefaultCloudFoundryOperations.

Note: You do not need to provide all clients. If a client is missing, the first invocation of a method requiring that specific client will return an error.

DefaultCloudFoundryOperations.builder()
    .cloudFoundryClient(cloudFoundryClient)
    .dopplerClient(dopplerClient)
    .uaaClient(uaaClient)
    .organization("example-organization")
    .space("example-space")
    .build();

The CloudFoundryClient, DopplerClient, and UaaClient are interfaces. To use them, you must instantiate their Reactor-based implementations using builders. These builders require a ConnectionContext and a TokenProvider.

ReactorCloudFoundryClient.builder()
    .connectionContext(connectionContext)
    .tokenProvider(tokenProvider)
    .build();

ReactorDopplerClient.builder()
    .connectionContext(connectionContext)
    .tokenProvider(tokenProvider)
    .build();

ReactorUaaClient.builder()
    .connectionContext(connectionContext)
    .tokenProvider(tokenProvider)
    .build();