Core Concepts

  1. Views or "portable abstractions"
  2. APIs
  3. Providers
  4. Contexts

Views

Views are portable abstractions that are designed to allow you to write code that uses cloud services without tying yourself to a specific vendor. Take JDBC as an example: rather than writing code directly for a specific type of database, you can make generic database requests, and the JDBC specification and drivers translate these into specific commands and statements for a certain type of database.

Views generally make sense only once a reasonably broad set of functionality is supported by multiple vendors. In the cloud space, jclouds currently supports three such views:

APIs

An API in jclouds describes the actual calls (often, but not always, HTTP requests) that can be executed against a specific cloud service to "do stuff". In the case of popular APIs, such as the EC2 compute API, or the S3 storage API, there may be multiple vendors with cloud services that support that particular API. For example, EC2 is supported by Amazon and OpenStack, amongst others.

A vendor may also support an API in multiple geographic locations. For example, Rackspace's Cloud Servers API is available both in the US and the UK.

Providers

A provider in jclouds represents a particular vendor cloud service that supports one or more APIs. For example, Amazon offers EC2 through the aws-ec2 provider, and Rackspace's Cloud Servers instance in the UK is available via the rackspace-cloudservers-uk provider.

Often, a jclouds provider is simply the appropriate API together with service-specific instantiation values, such as the endpoint URL. In some cases, the vendor offers additional functionality that goes beyond the API. For example, AWS EC2 supports various calls and options that are not offered by other providers implementing the ''standard'' EC2 API.

Views, APIs and providers work together in jclouds in the following way:

APIs describe the calls that can be executed against a particular type of cloud service

By looking at the API defintion in jclouds, you can see the actual calls that are available if you talk directly to this API.

APIs support views

Depending on the functionality provided by a particular API, it can be used to implement a particular jclouds view. For instance, EC2 provides the right functionality to support the ComputeService view, but is not useful for the BlobStore or LoadBalancer views.

For some cloud services, one API can support multiple views.

Providers implement APIs, and describe calls that can be executed against a specific vendor cloud service

Each provider in jclouds implements one or more APIs, which is why the provider classes generally extend the API classes. As discussed above, some providers support calls in addition to those offered by the API.

These additional calls may be available only optionally. For example, Rackspace installations in different locations may support different sets of extensions.

By implementing APIs, providers also support views. For instance, AWS EC2 supports the ComputeService view because it implements the EC2 API.

What does this mean for you?

You can write highly portable code

If you code only using views, you will be able to run the same application against a large variety of different clouds, each with potentially a different API. For example, if you're using only the ComputeService, you could switch from AWS EC2 to vCloud without changing your code.

It's like writing your database layer purely against the JDBC specification: you should be able to move from PostgreSQL to MariaDB without code changes.

You can use API-specific calls where needed

If the particular views you are working with do not allow you to do exactly what you want, but the API supports the desired functionality, you can "unwrap" the view to access the underlying API. This reduces the portability of your code, but you can still move between providers that support this API.

For example, if you unwrap the EC2 API from a ComputeService view and talk directly to EC2, you will not be able move to vCloud without code changes any more. You will still be able to switch to a different provider that also supports the EC2 API, however.

You can use provider-specific calls if you really have to

If you really need to use calls or options offered only by a certain provider, you can even unwrap the view to access the provider itself. Some of the features of AWS EC2, for example, are only available on AWS EC2 and are not supported by other providers that implement the standard EC2 API.

Obviously, this means your code is now tied to that specific provider, but that may be an acceptable tradeoff in your situation.

Finally, we have...

Contexts

A context represents a specific connection to a particular provider. From the perspective of our database analogy, this would be broadly similar to a database connection against a specific DB.

Once you have created a context via the ContextBuilder and are "connected" to a particular cloud service, you can either get any of the views that are supported by that provider, or go straight to the API or even to the provider level.

Creating a context is an expensive operation, so in general it is a good idea to create one context per credential and target cloud when the application starts and close it when it terminates. Contexts are thread-safe, so can be shared across your application.

It is important to close a context when you no longer need it, to free its associated resources.

You can also get a view back from the ContextBuilder and later unwrap it to access the underlying API or provider.