Overview (blend4j 0.2.0-SNAPSHOT API)

Packages
Package	Description
com.github.jmchilton.blend4j
com.github.jmchilton.blend4j.exceptions
com.github.jmchilton.blend4j.galaxy
com.github.jmchilton.blend4j.galaxy.beans
com.github.jmchilton.blend4j.galaxy.beans.collection
com.github.jmchilton.blend4j.galaxy.beans.collection.request
com.github.jmchilton.blend4j.galaxy.beans.collection.response
com.github.jmchilton.blend4j.toolshed
com.github.jmchilton.blend4j.toolshed.beans
com.github.jmchilton.blend4j.util	Subset of Google Guava (version 17) copied into library (and modified slightly) so the functionality is available but we don't actually need to depend on another library.

blend4j is a partial reimplemenation of the Python library bioblend for the JVM. bioblend for Python is a library for scripting interactions with Galaxy. These API documents describe how to use it - for general information including how to obtain and test blend4j checkout its home on github.

Examples

These examples demonstrate some simple use cases - see specific packages and classes for more details.

To tell blend4j which Galaxy instance and API key to use, you can put a .blend.properties file in your home directory:

test.galaxy.instance=https://usegalaxy.org/
test.galaxy.key=7cb.........................79fc (put your API key in here)

For simplicity, these examples assume the following import statements are used to import all of blend4j's Galaxy functionality.

import com.github.jmchilton.blend4j.galaxy.beans.*;
import com.github.jmchilton.blend4j.galaxy.*;

Listing current users history:

  GalaxyInstance galaxyInstance = GalaxyInstanceFactory.get(url, apiKey);
  HistoriesClient historiesClient = galaxyInstance.getHistoriesClient();
  for(History history : historiesClient.getHistories()) {
    String name = history.getName();
    String id = history.getId();
    String message = String.format("Found history with name %s and id %s", name, id);
    System.out.println(message);
  }

Find a data library by name and print its contents:

  final GalaxyInstance galaxyInstance = GalaxyInstanceFactory.get(url, apiKey);
  final LibrariesClient librariesClient = galaxyInstance.getLibrariesClient();
  final List<Library> libraries = librariesClient.getLibraries();
  Library testLibrary = null;
  for(final Library library : libraries) {
    if(library.getName().equals("test-library")) {
      testLibrary = library;
    }
  }
  if(testLibrary == null) {
    return;
  }
  for(final LibraryContent content : librariesClient.getLibraryContents(testLibrary.getId())) {
    final String type = content.getType(); // file or folder
    final String name = content.getName();
    final String id = content.getId();
    final String message = String.format("Found library content of type %s with name %s and id %s", type, name, id);
    System.out.println(message);
  }

The following code demonstrates running a workflow. It assumes the existence of a workflow named TestWorkflow1 with two inputs labeled WorkflowInput1 and WorkflowInput2. Additionally it assumes a history named TestHistory1 already exists containing two datasets Input1 and Input2.

final GalaxyInstance instance = GalaxyInstanceFactory.get(url, apiKey);
final WorkflowsClient workflowsClient = instance.getWorkflowsClient();

// Find history
final HistoriesClient historyClient = instance.getHistoriesClient();
History matchingHistory = null;
for(final History history : historyClient.getHistories()) {
  if(history.getName().equals("TestHistory1")) {
    matchingHistory = history;
  }
}
Assert.assertNotNull(matchingHistory);
String input1Id = null;
String input2Id = null;
for(final HistoryContents historyDataset :historyClient.showHistoryContents(matchingHistory.getId())) {
  if(historyDataset.getName().equals("Input1")) {
    input1Id = historyDataset.getId();
  }
  if(historyDataset.getName().equals("Input2")) {
    input2Id = historyDataset.getId();
  }
}

Workflow matchingWorkflow = null;
for(Workflow workflow : workflowsClient.getWorkflows()) {
  if(workflow.getName().equals("TestWorkflow1")) {
    matchingWorkflow = workflow;
  }
}

final WorkflowDetails workflowDetails = workflowsClient.showWorkflow(matchingWorkflow.getId());
String workflowInput1Id = null;
String workflowInput2Id = null;
for(final Map.Entry<String, WorkflowInputDefinition> inputEntry : workflowDetails.getInputs().entrySet()) {
  final String label = inputEntry.getValue().getLabel();
  if(label.equals("WorkflowInput1")) {
    workflowInput1Id = inputEntry.getKey();
  }
  if(label.equals("WorkflowInput2")) {
    workflowInput2Id = inputEntry.getKey();
  }
}

final WorkflowInputs inputs = new WorkflowInputs();
inputs.setDestination(new WorkflowInputs.ExistingHistory(matchingHistory.getId()));
inputs.setWorkflowId(matchingWorkflow.getId());
inputs.setInput(workflowInput1Id, new WorkflowInputs.WorkflowInput(input1Id, WorkflowInputs.InputSourceType.HDA));
inputs.setInput(workflowInput2Id, new WorkflowInputs.WorkflowInput(input2Id, WorkflowInputs.InputSourceType.HDA));
final WorkflowOutputs output = workflowsClient.runWorkflow(inputs);    
System.out.println("Running workflow in history " + output.getHistoryId());
for(String outputId : output.getOutputIds()) {
  System.out.println("  Workflow writing to output id " + outputId);
}

The following code demonstrates creating a data library at four different levels of abstraction (these examples require an admin key):

// Most API methods have corresponding blend4j methods for dealing with 
// both low-level request and parsed POJO responses. You can also use the method
// galaxyInstance.getWebResource() to access the low-level Jersey APIs directly.
final GalaxyInstance galaxyInstance = GalaxyInstanceFactory.get(url, apiKey);
final LibrariesClient librariesClient = galaxyInstance.getLibrariesClient(); 

// Highest level of abstraction, deal with POJO responses
final Library testLibrary1 = new Library("test1");
final Library persistedLibrary1 = librariesClient.createLibrary(testLibrary1);

// Deal with Jersey ClientResponse object in case want to check return status, etc...
final Library testLibrary2 = new Library("test2");
final ClientResponse response2 = librariesClient.createLibraryRequest(testLibrary2);
if(response2.getStatus() == 200) {
  final Library persistedLibrary2 = response2.getEntity(Library.class); 
  // ...
}

// Use Jersey directly (with POJOs)
final WebResource webResource3 = galaxyInstance.getWebResource();
final Library testLibrary3 = new Library("test3");
final ClientResponse response3 = webResource3
    .path("libraries")
    .type(MediaType.APPLICATION_JSON)
    .accept(MediaType.APPLICATION_JSON)
    .post(ClientResponse.class, testLibrary3);
final Library persistedLibrary3 = response3.getEntity(Library.class);

// Use Jersey directly (no POJOs)
final WebResource webResource4 = galaxyInstance.getWebResource();
final ClientResponse response4 = webResource4
    .path("libraries")
    .type(MediaType.APPLICATION_JSON)
    .accept(MediaType.APPLICATION_JSON)
    .post(ClientResponse.class, "{\"name\": \"test4\"}");
final String jsonResponse4 = response4.getEntity(String.class);
System.out.println("JSON response is: " + jsonResponse4);

This example demonstrates an admin process creating a private data library for a user and copying a directories contents to it. This example requires both an admin key and for useremoteuser to be enabled in the Galaxy instance's options file.

final GalaxyInstance galaxyInstance = GalaxyInstanceFactory.get(url, apiKey);
final String email = "alice@example.com";

// Create data library
final Library library = new Library("Example library for " + email);
final LibrariesClient librariesClient = galaxyInstance.getLibrariesClient();
final Library persistedLibrary = librariesClient.createLibrary(library);

// Copy example directory into library
final FilesystemPathsLibraryUpload upload = new FilesystemPathsLibraryUpload();
final LibraryContent rootFolder = librariesClient.getRootFolder(persistedLibrary.getId());
upload.setFolderId(rootFolder.getId());
upload.setContent("test-data/variant_detection");
librariesClient.uploadFilesystemPathsRequest(persistedLibrary.getId(), upload);

// Obtain user object
User owner = null;
final UsersClient usersClient = galaxyInstance.getUsersClient();
for(final User user : usersClient.getUsers()) {
  if(user.getEmail().equals(email)) {
    owner = user;
    break;
  }
}
if(owner == null) {
  // In order to create users like this - use_remote_user must be enabled
  // in the Galaxy instance's universe_wsgi.ini options.
  owner = usersClient.createUser(email);
}

// Obtain user role
Role ownersPrivateRole = null;
final RolesClient rolesClient = galaxyInstance.getRolesClient();
for(final Role role : rolesClient.getRoles()) {
  if(role.getName().equals(email)) {
    ownersPrivateRole = role;
    break;
  }
}
final String ownersPrivateRoleId = ownersPrivateRole.getId(); 

// Set data library permissions
final LibraryPermissions permissions = new LibraryPermissions();
permissions.getAccessInRoles().add(ownersPrivateRoleId);
permissions.getAddInRoles().add(ownersPrivateRoleId);
permissions.getManageInRoles().add(ownersPrivateRoleId);
permissions.getModifyInRoles().add(ownersPrivateRoleId);
librariesClient.setLibraryPermissions(persistedLibrary.getId(), permissions);

This example demonstrates the creation of a dataset collection containing a list of paired-end fastq files.

GalaxyInstance galaxyInstance = GalaxyInstanceFactory.get(url, apiKey);

// Find history named 'TestHistoryCollection'
final HistoriesClient historyClient = galaxyInstance.getHistoriesClient();
History matchingHistory = null;
for(final History history : historyClient.getHistories()) {
  if(history.getName().equals("TestHistoryCollection")) {
    matchingHistory = history;
  }
}
Assert.assertNotNull(matchingHistory);

// Obtain paired fastq file history ids
String file1_forewardId = null;
String file1_reverseId = null;
String file2_forewardId = null;
String file2_reverseId = null;
for(final HistoryContents historyDataset : historyClient.showHistoryContents(matchingHistory.getId())) {
  if(historyDataset.getName().equals("file1_1.fastq")) {
    file1_forewardId = historyDataset.getId();
  }
  if(historyDataset.getName().equals("file1_2.fastq")) {
    file1_reverseId = historyDataset.getId();
  }
  if(historyDataset.getName().equals("file2_1.fastq")) {
    file2_forewardId = historyDataset.getId();
  }
  if(historyDataset.getName().equals("file2_2.fastq")) {
    file2_reverseId = historyDataset.getId();
  }
}

HistoryDatasetElement file1_forward = new HistoryDatasetElement();
file1_forward.setId(file1_forewardId);
file1_forward.setName("forward");

HistoryDatasetElement file1_reverse = new HistoryDatasetElement();
file1_reverse.setId(file1_reverseId);
file1_reverse.setName("reverse");

// Create an object to link together the forward and reverse reads for file1
CollectionElement file1 = new CollectionElement();
file1.setName("file1");
file1.setCollectionType("paired");
file1.addCollectionElement(file1_forward);
file1.addCollectionElement(file1_reverse);

HistoryDatasetElement file2_forward = new HistoryDatasetElement();
file2_forward.setId(file2_forewardId);
file2_forward.setName("forward");

HistoryDatasetElement file2_reverse = new HistoryDatasetElement();
file2_reverse.setId(file2_reverseId);
file2_reverse.setName("reverse");

// Create an object to link together the forward and reverse reads for file2
CollectionElement file2 = new CollectionElement();
file2.setName("file2");
file2.setCollectionType("paired");
file2.addCollectionElement(file2_forward);
file2.addCollectionElement(file2_reverse);

// Create an object used to create the list of paired reads
CollectionDescription collectionDescription = new CollectionDescription();
collectionDescription.setCollectionType("list:paired");
collectionDescription.setName("ListPairedReads");
collectionDescription.addDatasetElement(file1);
collectionDescription.addDatasetElement(file2);

// Builds a dataset collection within Galaxy named 'ListPairedReads'
CollectionResponse collectionResponse =
    historyClient.createDatasetCollection(matchingHistory.getId(), collectionDescription);

// Print information on the newly created dataset collection
System.out.println("New dataset collection created historyId=" + collectionResponse.getHistoryId() 
    + ", collectionId=" + collectionResponse.getId() + ", name=" + collectionResponse.getName());

These examples are taken from Examples.java. For more examples see these integration test cases or the rest of the integration tests here.

Brad Chapman has put together a higher-level Clojure library - clj-blend, the source code of which can serve as additional examples of blend4j usage.