Home > Blogs > VMware Developer Blog


API Tutorial – Downloading Files from a Content Library Item

This blog post is a part of the blog series published by the Content Library team. Please find all the blog posts by the team at this link.

In Uploading an OVF Template to a Content Library tutorial, we went through the UpdateSession API to upload files to a library item with an example for uploading an OVF template. In this tutorial, we explain the concept of DownloadSession API and show how to use it to download files from a library item.

At the end of this tutorial you should be able to:


To be able to run the API sample for this tutorial, you will need:

  • A library created on the vCenter Server containing at least one library item.
  • This library item must contain some uploaded files.

Check out the API Samples and provided resources!

 

A Primer on the Content Library DownloadSession API

Any download of the files from a library item needs to be done via the DownloadSession API. The download session helps in:

  • Tracking the download of the files.
  • Controlling the availability of the download links.

Overview of the DownloadSession API Workflow

  • To initiate the download of the files from a library item, a client creates a download session using DownloadSession.create() API for that library item.
  • Using com.vmware.content.library.item.downloadsession.File.list() API, the client gets the information about the files in the library item.
  • The client can choose to download specific files from the library item by selecting only those from the available file list in the download session.
  • The client calls com.vmware.content.library.item.downloadsession.File.prepare() API for each file that needs to be downloaded from the library item.
    • This ensures that the requested file is available for download.
    • In most cases, the file will be prepared instantaneously. But in case of the on-demand subscribed libraries, this preparation may take more time. The on-demand subscribed libraries are configured to retrieve the files from published library only when required. So to make the file available for download, the Content Library Service has to first retrieve the requested file from the published library.
    • We will cover this behaviour in detail when we explain published and subscribed libraries in upcoming tutorials.
  • Once the file is successfully prepared, the client downloads the file using the URL retrieved from Info object.
  • When the client is done with the downloads, he/she calls DownloadSession.delete() API to delete the download session. After this, any attempt to download the files from this session will fail.
  • When there are no active downloads on the download session, the Content Library Service will delete the session after a certain period. When this happens, a download session is set to be expired. This session expiration timeout is configurable via the com.vmware.content.Configuration API.

Download Session States

A download session can have the following states:

  • DownloadSessionModel.State.ACTIVE – A download session will be in this state when files are either being prepared for download, or being downloaded.
  • DownloadSessionModel.State.ERROR – A download session will be in this state when the session lifecycle encounters any errors.
  • DownloadSessionModel.State.CANCELED – A download session will be in this state, when a client cancels the session using DownloadSession.cancel() API. When a download session stays in this state for a certain period of time, the Content Library Service will delete it.

A client can delete a download session only when it is not in the ACTIVE state.

Downloading Files from a Library Item

Now that we understand how the DownloadSession API works, let’s use it to download the files from a library item.

Create a Download Session

We start by creating a download session for a library item.

DownloadSessionModel downloadSessionModel = new DownloadSessionModel();
downloadSessionModel.setLibraryItemId(libraryItemId);
String downloadSessionId = client.downloadSession()
        .create(getRandomClientToken(), downloadSessionModel);

Prepare the Files for Download

To download the files from the library item, we need to prepare them first. Let’s get the list of files available in the download session and prepare the files for download.

for (com.vmware.content.library.item.downloadsession.FileTypes.Info
        downloadInfo : client.downloadSessionFile().list(downloadSessionId)) {
    // prepare the file for download
    client.downloadSessionFile().prepare(downloadSessionId, 
            downloadInfo.getName(), 
            EndpointType.HTTPS);
    ...

We then monitor the file preparation status. Once a file is in the PrepareStatus.PREPARED state, we can download it.

    ...
    // check if the file is ready for download
    do {
        Thread.sleep(1000);
    } while (client.downloadSessionFile().get(downloadSessionId, downloadInfo.getName())
            .getStatus() != PrepareStatus.PREPARED);
    ...

Download the Prepared Files

We download a prepared file using its download URL. We get the download URL for the file from its Info object. This download URL will be available only when the file is in the PrepareStatus.PREPARED state.

    ...
    // get the HTTP URL to download the file
    URI downloadUri = client.downloadSessionFile()
            .get(downloadSessionId, downloadInfo.getName()).getDownloadEndpoint().getUri();
    // download the file from the URL
    HttpGet getRequest = new HttpGet(downloadUri);
    response = httpclient.execute(getRequest);
    response.getEntity().writeTo(new FileOutputStream("/tmp/file.iso"));
    ...
} // end for

Delete the Download Session

Once we are done with the download, we delete the session.

client.downloadSession.delete(downloadSessionId);

That’s it! We just used the DownloadSession API to download files from a library item!

To summarize, this tutorial explained the basics of the DownloadSession API and how to use it to download files from a library item. In the next tutorial, we will go through the APIs to Deploy OVF Template from a Content Library.
(Coming soon, stay tuned!)

More in This Series