sdk/java-v2/src/main/java/org/arvados/client/facade/ArvadosFacade.java

   1 /*
   2  * Copyright (C) The Arvados Authors. All rights reserved.
   3  *
   4  * SPDX-License-Identifier: AGPL-3.0 OR Apache-2.0
   5  *
   6  */
   7
   8 package org.arvados.client.facade;
   9
  10 import com.google.common.collect.Lists;
  11 import org.arvados.client.api.client.CollectionsApiClient;
  12 import org.arvados.client.api.client.GroupsApiClient;
  13 import org.arvados.client.api.client.KeepWebApiClient;
  14 import org.arvados.client.api.client.UsersApiClient;
  15 import org.arvados.client.api.model.*;
  16 import org.arvados.client.api.model.argument.Filter;
  17 import org.arvados.client.api.model.argument.ListArgument;
  18 import org.arvados.client.config.FileConfigProvider;
  19 import org.arvados.client.config.ConfigProvider;
  20 import org.arvados.client.logic.collection.FileToken;
  21 import org.arvados.client.logic.collection.ManifestDecoder;
  22 import org.arvados.client.logic.keep.FileDownloader;
  23 import org.arvados.client.logic.keep.FileUploader;
  24 import org.arvados.client.logic.keep.KeepClient;
  25 import org.slf4j.Logger;
  26
  27 import java.io.File;
  28 import java.util.Arrays;
  29 import java.util.Collections;
  30 import java.util.List;
  31
  32 public class ArvadosFacade {
  33
  34     private final ConfigProvider config;
  35     private final Logger log = org.slf4j.LoggerFactory.getLogger(ArvadosFacade.class);
  36     private CollectionsApiClient collectionsApiClient;
  37     private GroupsApiClient groupsApiClient;
  38     private UsersApiClient usersApiClient;
  39     private FileDownloader fileDownloader;
  40     private FileUploader fileUploader;
  41     private static final String PROJECT = "project";
  42     private static final String SUBPROJECT = "sub-project";
  43
  44     public ArvadosFacade(ConfigProvider config) {
  45         this.config = config;
  46         setFacadeFields();
  47     }
  48
  49     public ArvadosFacade() {
  50         this.config = new FileConfigProvider();
  51         setFacadeFields();
  52     }
  53
  54     private void setFacadeFields() {
  55         collectionsApiClient = new CollectionsApiClient(config);
  56         groupsApiClient = new GroupsApiClient(config);
  57         usersApiClient = new UsersApiClient(config);
  58         KeepClient keepClient = new KeepClient(config);
  59         ManifestDecoder manifestDecoder = new ManifestDecoder();
  60         KeepWebApiClient keepWebApiClient = new KeepWebApiClient(config);
  61         fileDownloader = new FileDownloader(keepClient, manifestDecoder, collectionsApiClient, keepWebApiClient);
  62         fileUploader = new FileUploader(keepClient, collectionsApiClient, config);
  63     }
  64
  65     /**
  66      * This method downloads single file from collection using Arvados Keep-Web.
  67      * File is saved on a drive in specified location and returned.
  68      *
  69      * @param filePathName         path to the file in collection. If requested file is stored
  70      *                             directly in collection (not within its subdirectory) this
  71      *                             would be just the name of file (ex. 'file.txt').
  72      *                             Otherwise full file path must be passed (ex. 'folder/file.txt')
  73      * @param collectionUuid       uuid of collection containing requested file
  74      * @param pathToDownloadFolder path to location in which file should be saved.
  75      *                             Passed location must be a directory in which file of
  76      *                             that name does not already exist.
  77      * @return downloaded file
  78      */
  79     public File downloadFile(String filePathName, String collectionUuid, String pathToDownloadFolder) {
  80         return fileDownloader.downloadSingleFileUsingKeepWeb(filePathName, collectionUuid, pathToDownloadFolder);
  81     }
  82
  83     /**
  84      * This method downloads all files from collection.
  85      * Directory named by collection uuid is created in specified location,
  86      * files are saved on a drive in this directory and list with downloaded
  87      * files is returned.
  88      *
  89      * @param collectionUuid       uuid of collection from which files are downloaded
  90      * @param pathToDownloadFolder path to location in which files should be saved.
  91      *                             New folder named by collection uuid, containing
  92      *                             downloaded files, is created in this location.
  93      *                             Passed location must be a directory in which folder
  94      *                             of that name does not already exist.
  95      * @param usingKeepWeb         if set to true files will be downloaded using Keep Web.
  96      *                             If set to false files will be downloaded using Keep Server API.
  97      * @return list containing downloaded files
  98      */
  99     public List<File> downloadCollectionFiles(String collectionUuid, String pathToDownloadFolder, boolean usingKeepWeb) {
 100         if (usingKeepWeb)
 101             return fileDownloader.downloadFilesFromCollectionUsingKeepWeb(collectionUuid, pathToDownloadFolder);
 102         return fileDownloader.downloadFilesFromCollection(collectionUuid, pathToDownloadFolder);
 103     }
 104
 105     /**
 106      * Lists all FileTokens (objects containing information about files) for
 107      * specified collection.
 108      * Information in each FileToken includes file path, name, size and position
 109      * in data stream
 110      *
 111      * @param collectionUuid uuid of collection for which FileTokens are listed
 112      * @return list containing FileTokens for each file in specified collection
 113      */
 114     public List<FileToken> listFileInfoFromCollection(String collectionUuid) {
 115         return fileDownloader.listFileInfoFromCollection(collectionUuid);
 116     }
 117
 118     /**
 119      * Creates and uploads new collection containing passed files.
 120      * Created collection has a default name and is uploaded to user's 'Home' project.
 121      *
 122      * @see ArvadosFacade#upload(List, String, String)
 123      * @param files    list of files to be uploaded within new collection
 124      * @return collection object mapped from JSON that is returned from server after successful upload
 125      */
 126     public Collection upload(List<File> files) {
 127         return upload(files, null, null);
 128     }
 129
 130     /**
 131      * Creates and uploads new collection containing a single file.
 132      * Created collection has a default name and is uploaded to user's 'Home' project.
 133      *
 134      * @see ArvadosFacade#upload(List, String, String)
 135      * @param file file to be uploaded
 136      * @return collection object mapped from JSON that is returned from server after successful upload
 137      */
 138     public Collection upload(File file) {
 139         return upload(Collections.singletonList(file), null, null);
 140     }
 141
 142     /**
 143      * Uploads new collection with specified name and containing selected files
 144      * to an existing project.
 145      *
 146      * @param sourceFiles    list of files to be uploaded within new collection
 147      * @param collectionName name for the newly created collection.
 148      *                       Collection with that name cannot be already created
 149      *                       in specified project. If null is passed
 150      *                       then collection name is set to default, containing
 151      *                       phrase 'New Collection' and a timestamp.
 152      * @param projectUuid    uuid of the project in which created collection is to be included.
 153      *                       If null is passed then collection is uploaded to user's 'Home' project.
 154      * @return collection object mapped from JSON that is returned from server after successful upload
 155      */
 156     public Collection upload(List<File> sourceFiles, String collectionName, String projectUuid) {
 157         return fileUploader.upload(sourceFiles, collectionName, projectUuid);
 158     }
 159
 160     /**
 161      * Uploads a file to a specified collection.
 162      *
 163      * @see ArvadosFacade#uploadToExistingCollection(List, String)
 164      * @param file           file to be uploaded to existing collection. Filenames must be unique
 165      *                       in comparison with files already existing within collection.
 166      * @param collectionUUID UUID of collection to which files should be uploaded
 167      * @return collection object mapped from JSON that is returned from server after successful upload
 168      */
 169     public Collection uploadToExistingCollection(File file, String collectionUUID) {
 170         return fileUploader.uploadToExistingCollection(Collections.singletonList(file), collectionUUID);
 171     }
 172
 173     /**
 174      * Uploads multiple files to an existing collection.
 175      *
 176      * @param files          list of files to be uploaded to existing collection.
 177      *                       File names must be unique - both within passed list and
 178      *                       in comparison with files already existing within collection.
 179      * @param collectionUUID UUID of collection to which files should be uploaded
 180      * @return collection object mapped from JSON that is returned from server after successful upload
 181      */
 182     public Collection uploadToExistingCollection(List<File> files, String collectionUUID) {
 183         return fileUploader.uploadToExistingCollection(files, collectionUUID);
 184     }
 185
 186     /**
 187      * Creates and uploads new empty collection to specified project.
 188      *
 189      * @param collectionName name for the newly created collection.
 190      *                       Collection with that name cannot be already created
 191      *                       in specified project.
 192      * @param projectUuid    uuid of project that will contain uploaded empty collection.
 193      *                       To select home project pass current user's uuid from getCurrentUser()
 194      * @return collection object mapped from JSON that is returned from server after successful upload
 195      * @see ArvadosFacade#getCurrentUser()
 196      */
 197     public Collection createEmptyCollection(String collectionName, String projectUuid) {
 198         Collection collection = new Collection();
 199         collection.setOwnerUuid(projectUuid);
 200         collection.setName(collectionName);
 201         return collectionsApiClient.create(collection);
 202     }
 203
 204     /**
 205      * Returns current user information based on Api Token provided via configuration
 206      *
 207      * @return user object mapped from JSON that is returned from server based on provided Api Token.
 208      * It contains information about user who has this token assigned.
 209      */
 210     public User getCurrentUser() {
 211         return usersApiClient.current();
 212     }
 213
 214     /**
 215      * Gets uuid of current user based on api Token provided in configuration and uses it to list all
 216      * projects that this user owns in Arvados.
 217      *
 218      * @return GroupList containing all groups that current user is owner of.
 219      * @see ArvadosFacade#getCurrentUser()
 220      */
 221     public GroupList showGroupsOwnedByCurrentUser() {
 222         ListArgument listArgument = ListArgument.builder()
 223                 .filters(Arrays.asList(
 224                         Filter.of("owner_uuid", Filter.Operator.LIKE, getCurrentUser().getUuid()),
 225                         Filter.of("group_class", Filter.Operator.IN, Lists.newArrayList(PROJECT, SUBPROJECT)
 226                         )))
 227                 .build();
 228         GroupList groupList = groupsApiClient.list(listArgument);
 229         log.debug("Groups owned by user:");
 230         groupList.getItems().forEach(m -> log.debug(m.getUuid() + " -- " + m.getName()));
 231
 232         return groupList;
 233     }
 234
 235     /**
 236      * Gets uuid of current user based on api Token provided in configuration and uses it to list all
 237      * projects that this user has read access to in Arvados.
 238      *
 239      * @return GroupList containing all groups that current user has read access to.
 240      */
 241     public GroupList showGroupsAccessibleByCurrentUser() {
 242         ListArgument listArgument = ListArgument.builder()
 243                 .filters(Collections.singletonList(
 244                         Filter.of("group_class", Filter.Operator.IN, Lists.newArrayList(PROJECT, SUBPROJECT)
 245                         )))
 246                 .build();
 247         GroupList groupList = groupsApiClient.list(listArgument);
 248         log.debug("Groups accessible by user:");
 249         groupList.getItems().forEach(m -> log.debug(m.getUuid() + " -- " + m.getName()));
 250
 251         return groupList;
 252     }
 253
 254     /**
 255      * Filters all collections from selected project and returns list of those that contain passed String in their name.
 256      * Operator "LIKE" is used so in order to obtain certain collection it is sufficient to pass just part of its name.
 257      * Returned collections in collectionList are ordered by date of creation (starting from oldest one).
 258      *
 259      * @param collectionName collections containing this param in their name will be returned.
 260      *                       Passing a wildcard is possible - for example passing "a%" searches for
 261      *                       all collections starting with "a".
 262      * @param projectUuid    uuid of project in which will be searched for collections with given name. To search home
 263      *                       project provide user uuid (from getCurrentUser())
 264      * @return object CollectionList containing all collections matching specified name criteria
 265      * @see ArvadosFacade#getCurrentUser()
 266      */
 267     public CollectionList getCollectionsFromProjectByName(String collectionName, String projectUuid) {
 268         ListArgument listArgument = ListArgument.builder()
 269                 .filters(Arrays.asList(
 270                         Filter.of("owner_uuid", Filter.Operator.LIKE, projectUuid),
 271                         Filter.of("name", Filter.Operator.LIKE, collectionName)
 272                 ))
 273                 .order(Collections.singletonList("created_at"))
 274                 .build();
 275
 276         return collectionsApiClient.list(listArgument);
 277     }
 278
 279     /**
 280      * Gets project details by uuid.
 281      *
 282      * @param projectUuid uuid of project
 283      * @return Group object containing information about project
 284      */
 285     public Group getProjectByUuid(String projectUuid) {
 286         Group project = groupsApiClient.get(projectUuid);
 287         log.debug("Retrieved " + project.getName() + " with UUID: " + project.getUuid());
 288         return project;
 289     }
 290
 291     /**
 292      * Creates new project that will be a subproject of "home" for current user.
 293      *
 294      * @param projectName name for the newly created project
 295      * @return Group object containing information about created project
 296      * (mapped from JSON returned from server after creating the project)
 297      */
 298     public Group createNewProject(String projectName) {
 299         Group project = new Group();
 300         project.setName(projectName);
 301         project.setGroupClass(PROJECT);
 302         Group createdProject = groupsApiClient.create(project);
 303         log.debug("Project " + createdProject.getName() + " created with UUID: " + createdProject.getUuid());
 304         return createdProject;
 305     }
 306
 307     /**
 308      * Deletes collection with specified uuid.
 309      *
 310      * @param collectionUuid uuid of collection to be deleted. User whose token is provided in configuration
 311      *                       must be authorized to delete such collection.
 312      * @return collection object with deleted collection (mapped from JSON returned from server after deleting the collection)
 313      */
 314     public Collection deleteCollection(String collectionUuid) {
 315         Collection deletedCollection = collectionsApiClient.delete(collectionUuid);
 316         log.debug("Collection: " + collectionUuid + " deleted.");
 317         return deletedCollection;
 318     }
 319 }