The cf-java-client
project is a Java language binding for interacting with a Cloud Foundry instance. The project is broken up into a number of components which expose different levels of abstraction depending on need.
cloudfoundry-client
– Interfaces, request, and response objects mapping to the Cloud Foundry REST APIs. This project has no implementation and therefore cannot connect a Cloud Foundry instance on its own.cloudfoundry-client-reactor
– The default implementation of thecloudfoundry-client
project. This implementation is based on the Reactor NettyHttpClient
.cloudfoundry-operations
– An API and implementation that corresponds to the Cloud Foundry CLI operations. This project builds on thecloudfoundry-client
and therefore has a single implementation.cloudfoundry-maven-plugin
/cloudfoundry-gradle-plugin
– Build plugins for Maven and Gradle. These projects build oncloudfoundry-operations
and therefore have single implementations.
Most projects will need two dependencies; the Operations API and an implementation of the Client API. For Maven, the dependencies would be defined like this:
<dependencies>
<dependency>
<groupId>org.cloudfoundry</groupId>
<artifactId>cloudfoundry-client-reactor</artifactId>
<version>2.0.1.RELEASE</version>
</dependency>
<dependency>
<groupId>org.cloudfoundry</groupId>
<artifactId>cloudfoundry-operations</artifactId>
<version>2.0.1.RELEASE</version>
</dependency>
<dependency>
<groupId>io.projectreactor</groupId>
<artifactId>reactor-core</artifactId>
<version>3.0.2.RELEASE</version>
</dependency>
<dependency>
<groupId>io.projectreactor.ipc</groupId>
<artifactId>reactor-netty</artifactId>
<version>0.5.1.RELEASE</version>
</dependency>
...
</dependencies>
The artifacts can be found in the Spring release, milestone, and snapshot repositories:
<repositories>
<repository>
<id>spring-releases</id>
<name>Spring Releases</name>
<url>http://repo.spring.io/release</url>
</repository>
...
</repositories>
<repositories>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>http://repo.spring.io/milestone</url>
</repository>
...
</repositories>
<repositories>
<repository>
<id>spring-snapshots</id>
<name>Spring Snapshots</name>
<url>http://repo.spring.io/snapshot</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
...
</repositories>
For Gradle, the dependencies would be defined like this:
dependencies {
compile 'org.cloudfoundry:cloudfoundry-client-reactor:2.0.1.RELEASE'
compile 'org.cloudfoundry:cloudfoundry-operations:2.0.1.RELEASE'
compile 'io.projectreactor:reactor-core:3.0.2.RELEASE'
compile 'io.projectreactor.ipc:reactor-netty:0.5.1.RELEASE'
...
}
The artifacts can be found in the Spring release, milestone, and snapshot repositories:
repositories {
maven { url 'http://repo.spring.io/release' }
...
}
repositories {
maven { url 'http://repo.spring.io/milestone' }
...
}
repositories {
maven { url 'http://repo.spring.io/snapshot' }
...
}
Both the cloudfoundry-operations
and cloudfoundry-client
projects follow a "Reactive" design pattern and expose their responses with Project Reactor Monos
s and Flux
s.
The lowest-level building blocks of the API are ConnectionContext
and TokenProvider
. These types are intended to be shared between instances of the clients, and come with out of the box implementations. To instantiate them, you configure them with builders:
DefaultConnectionContext.builder()
.apiHost(apiHost)
.build();
PasswordGrantTokenProvider.builder()
.password(password)
.username(username)
.build();
In Spring-based applications, you'll want to encapsulate them in bean definitions:
@Bean
DefaultConnectionContext connectionContext(@Value("${cf.apiHost}") String apiHost) {
return DefaultConnectionContext.builder()
.apiHost(apiHost)
.build();
}
@Bean
PasswordGrantTokenProvider tokenProvider(@Value("${cf.username}") String username,
@Value("${cf.password}") String password) {
return PasswordGrantTokenProvider.builder()
.password(password)
.username(username)
.build();
}
CloudFoundryClient
, DopplerClient
, and UaaClient
are only interfaces. Each has a Reactor-based implementation. To instantiate them, you configure them with builders:
ReactorCloudFoundryClient.builder()
.connectionContext(connectionContext)
.tokenProvider(tokenProvider)
.build();
ReactorDopplerClient.builder()
.connectionContext(connectionContext)
.tokenProvider(tokenProvider)
.build();
ReactorUaaClient.builder()
.connectionContext(connectionContext)
.tokenProvider(tokenProvider)
.build();
In Spring-based applications, you'll want to encapsulate them in bean definitions:
@Bean
ReactorCloudFoundryClient cloudFoundryClient(ConnectionContext connectionContext, TokenProvider tokenProvider) {
return ReactorCloudFoundryClient.builder()
.connectionContext(connectionContext)
.tokenProvider(tokenProvider)
.build();
}
@Bean
ReactorDopplerClient dopplerClient(ConnectionContext connectionContext, TokenProvider tokenProvider) {
return ReactorDopplerClient.builder()
.connectionContext(connectionContext)
.tokenProvider(tokenProvider)
.build();
}
@Bean
ReactorUaaClient uaaClient(ConnectionContext connectionContext, TokenProvider tokenProvider) {
return ReactorUaaClient.builder()
.connectionContext(connectionContext)
.tokenProvider(tokenProvider)
.build();
}
The CloudFoundryClient
, DopplerClient
, and UaaClient
s provide direct access to the raw REST APIs. This level of abstraction provides the most detailed and powerful access to the Cloud Foundry instance, but also requires users to perform quite a lot of orchestration on their own. Most users will instead want to work at the CloudFoundryOperations
layer. Once again this is only an interface and the default implementation of this is the DefaultCloudFoundryOperations
. To instantiate one, you configure it with a builder:
NOTE: The DefaultCloudfoundryOperations
type does not require all clients in order to run. Since not all operations touch all kinds of clients, you can selectively configure the minimum needed. If a client is missing, the first invocation of a method that requires that client will return an error.
DefaultCloudFoundryOperations.builder()
.cloudFoundryClient(cloudFoundryClient)
.dopplerClient(dopplerClient)
.uaaClient(uaaClient)
.organization("example-organization")
.space("example-space")
.build();
In Spring-based applications, you'll want to encapsulate this in a bean definition as well:
@Bean
DefaultCloudFoundryOperations cloudFoundryOperations(CloudFoundryClient cloudFoundryClient,
DopplerClient dopplerClient,
UaaClient uaaClient,
@Value("${cf.organization}") String organization,
@Value("${cf.space}") String space) {
return DefaultCloudFoundryOperations.builder()
.cloudFoundryClient(cloudFoundryClient)
.dopplerClient(dopplerClient)
.uaaClient(uaaClient)
.organization(organization)
.space(space)
.build();
}
Once you've got a reference to the CloudFoundryOperations
, it's time to start making calls to the Cloud Foundry instance. One of the simplest possible operations is list all of the organizations the user is a member of. The following example does three things:
- Requests a list of all organizations
- Extracts the name of each organization
- Prints the name of the each organization to
System.out
cloudFoundryOperations.organizations()
.list()
.map(Organization::getName)
.subscribe(System.out::println);
To relate the example to the description above the following happens:
.list()
– Lists the Cloud Foundry organizations as aFlux
of elements of typeOrganization
..map(...)
– Maps each organization to its name (typeString
). This example uses a method reference; the equivalent lambda would look likeorganization -> organization.getName()
.subscribe...
– The terminal operation that receives each name in theFlux
. Again, this example uses a method reference and the equivalent lambda would look likename -> System.out.println(name)
.
As mentioned earlier, the cloudfoundry-operations
implementation builds upon the cloudfoundry-client
API. That implementation takes advantage of the same reactive style in the lower-level API. The implementation of the Organizations.list()
method (which was demonstrated above) looks like the following (roughly):
cloudFoundryClient.organizations()
.list(ListOrganizationsRequest.builder()
.page(1)
.build())
.flatMap(response -> Flux.fromIterable(response.getResources))
.map(resource -> Organization.builder()
.id(resource.getMetadata().getId())
.name(resource.getEntity().getName())
.build());
The above example is more complicated:
.list(...)
– Retrieves a page of Cloud Foundry organizations..flatMap(...)
– Substitutes the originalMono
with aFlux
of theResource
s returned by the requested page..map(...)
– Maps theResource
to anOrganization
type.
TODO: Document once implemented
TODO: Document once implemented
API Documentation for each module can be found at the following locations:
cloudfoundry-client
–release
,milestone
,snapshot
cloudfoundry-client-reactor
–release
,milestone
,snapshot
cloudfoundry-operations
–release
,milestone
,snapshot
cloudfoundry-util
–release
,milestone
,snapshot
The project depends on Java 8. To build from source and install to your local Maven cache, run the following:
$ git submodule update --init --recursive
$ ./mvnw clean install
To run the integration tests, run the following:
$ ./mvnw -Pintegration-test clean test
IMPORTANT Integration tests should be run against an empty Cloud Foundry instance. The integration tests are destructive, affecting nearly everything on an instance given the chance.
The integration tests require a running instance of Cloud Foundry to test against. We recommend using PCF Dev to start a local instance to test with. To configure the integration tests with the appropriate connection information use the following environment variables:
Name | Description |
---|---|
TEST_ADMIN_CLIENTID |
Client ID for a client with permissions for a Client Credentials grant |
TEST_ADMIN_CLIENTSECRET |
Client secret for a client with permissions for a Client Credentials grant |
TEST_ADMIN_PASSWORD |
Password for a user with admin permissions |
TEST_ADMIN_USERNAME |
Username for a user with admin permissions |
TEST_APIHOST |
The host of Cloud Foundry instance. Typically something like api.local.pcfdev.io . |
TEST_PROXY_HOST |
(Optional) The host of a proxy to route all requests through |
TEST_PROXY_PASSWORD |
(Optional) The password for a proxy to route all requests through |
TEST_PROXY_PORT |
(Optional) The port of a proxy to route all requests through. Defaults to 8080 . |
TEST_PROXY_USERNAME |
(Optional) The username for a proxy to route all requests through |
TEST_SKIPSSLVALIDATION |
(Optional) Whether to skip SSL validation when connecting to the Cloud Foundry instance. Defaults to false . |
Pull requests and Issues are welcome.
This project is released under version 2.0 of the Apache License.