added a part of API Documentation

git-svn-id: https://svn.d4science-ii.research-infrastructures.eu/gcube/trunk/Common/storagehub-client@181252 82a268e6-3cf1-43bd-a215-b396298e98cf

src/main/java/org/gcube/common/storagehub/client/dsl/FolderContainer.java

@@ -4,7 +4,6 @@ import java.io.InputStream;
 import java.util.List;
 import java.util.Set;
 
-import org.gcube.common.authorization.library.AuthorizationEntry;
 import org.gcube.common.storagehub.client.proxies.ItemManagerClient;
 import org.gcube.common.storagehub.model.acls.ACL;
 import org.gcube.common.storagehub.model.acls.AccessType;
@@ -28,33 +27,104 @@ public class FolderContainer extends ItemContainer<FolderItem>{
 		return ContainerType.FOLDER;
 	}
 	
+	/**
+	 * 
+	 * returns the children of this {@FolderContainer}
+	 * 
+	 * By default this method return all FolderContainers (asContainers) or Items (asItems) without accounting data, content data and metadata of the item
+	 * to add these information see {@ListResolverTyped}
+	 * 
+	 * @return {@ListResolverTyped}
+	 * @throws {@InvalidItemException} 
+	 * @throws {@UserNotAuthorizedException} if user is not authorized to read this folder
+	 */
 	public ListResolverTyped list() throws StorageHubException {
 		return new ListResolverTyped((onlyType, includeHidden, excludes) -> itemclient.getChildren(itemId, onlyType, includeHidden, excludes), itemclient) ;
 	}
 	
+	/**
+	 * 
+	 * creates a {@AbstractFileItem} inside the folder represented by this FolderContainer
+	 * 
+	 * @param stream the file stream
+	 * @param filename the name of the item in the workspace
+	 * @param description the description of the item in the workspace
+	 * @return {@FileContainer} of the Item created
+	 * @throws {@InvalidItemException} 
+	 * @throws {@UserNotAuthorizedException} if user is not authorized to write in this folder
+	 */
 	public FileContainer uploadFile(InputStream stream, String filename, String description) throws StorageHubException {
 		return new FileContainer(itemclient, itemclient.uploadFile(stream, this.itemId , filename, description));
 	}
 	
+	/**
+	 * 
+	 * creates a set of {@Item} in the workspace extracting the Archive
+	 * 
+	 * @param stream the file stream
+	 * @param extractionFolderName the root name of the folder where the archive will be extracted (A new folder with this name will be created)
+	 * @return {@FolderContainer} of the extraction Folder
+	 * @throws {@InvalidItemException} 
+	 * @throws {@UserNotAuthorizedException} if user is not authorized to write in this folder
+	 */
 	public FolderContainer uploadArchive(InputStream stream, String extractionFolderName) throws StorageHubException {
 		return new FolderContainer(itemclient, itemclient.uploadArchive(stream, this.itemId , extractionFolderName));
 	}
 	
-	public FolderContainer newFolder(String name, String description) throws Exception {
+	/**
+	 * 
+	 * create a new {@FolderItem} inside the {@FolderItem} represented by this FolderContainer
+	 * 
+	 * @param name the name of the folder
+	 * @param description the description of the folder
+	 * @return the {@FolderContainer} representing the new folder
+	 * @throws {@InvalidItemException} 
+	 * @throws {@UserNotAuthorizedException} if user is not authorized to write in this folder
+	 */
+	public FolderContainer newFolder(String name, String description) throws StorageHubException {
 		String newFolderId = itemclient.createFolder(this.itemId, name, description, false);
 		return new FolderContainer(itemclient, newFolderId);
 	}
 	
+	
+	/**
+	 * 
+	 * create a new hidden {@FolderItem} inside the folder represented by this FolderContainer
+	 * 
+	 * @param name the name of the folder
+	 * @param description the description of the folder
+	 * @return the {@FolderContainer} representing the new folder
+	 * @throws {@InvalidItemException} 
+	 * @throws {@UserNotAuthorizedException} if user is not authorized to write in this folder
+	 */
 	public FolderContainer newHiddenFolder(String name, String description) throws Exception {
 		String newFolderId = itemclient.createFolder(this.itemId, name, description, true);
 		return new FolderContainer(itemclient, newFolderId);
 	}
 	
+	
+	/**
+	 * 
+	 * create a new hidden Folder inside the folder represented by this FolderContainer
+	 * 
+	 * @param name the name of the folder
+	 * @param description the description of the folder
+	 * @return the {@FolderContainer} representing the new folder
+	 * @throws {@InvalidItemException} 
+	 * @throws {@UserNotAuthorizedException} if user is not authorized to write in this folder
+	 */
 	public GenericItemContainer newGcubeItem(GCubeItem item) throws Exception {
 		String itemId = itemclient.createGcubeItem(this.itemId, item);
 		return new GenericItemContainer(itemclient, itemId);
 	}
 	
+	/**
+	 * 
+	 * returns the {@ACL} of the {FolderItem} represented by this FolderContainer
+	 * 
+	 * @return a List of {@ACL}
+	 * @throws {@StorageHubException}
+	 */
 	public List<ACL> getAcls() throws Exception {
 		return itemclient.getACL(this.itemId);
 	}
@@ -63,16 +133,44 @@ public class FolderContainer extends ItemContainer<FolderItem>{
 		return itemclient.canWriteInto(this.itemId);
 	}
 	
+	
+	/**
+	 * 
+	 * returns the children of this {@FolderContainer} that matches the name pattern
+	 * 
+	 * @return {@ListResolver}
+	 * @throws {@InvalidItemException} 
+	 * @throws {@UserNotAuthorizedException} if user is not authorized to read this folder
+	 */
 	public ListResolver findByName(String namePattern) throws StorageHubException {
 		return new ListResolver((onlyType, includeHidden, excludes) -> itemclient.findChildrenByNamePattern(itemId, namePattern , excludes), itemclient);
 	}
 	
+	/**
+	 * 
+	 * shares this Folder with a list of users setting the same {@AccessType} for everyone in the list.
+	 * if the folder is already shared it add the users to the share.
+	 * 
+	 * @return the current {@FolderContainer} updated
+	 * @throws {@InvalidItemException} 
+	 * @throws {@UserNotAuthorizedException} if user is not authorized to share this folder
+	 */
 	public FolderContainer share(Set<String> users, AccessType accessType) throws Exception {
 		itemclient.shareFolder(this.itemId, users, accessType);
 		this.invalidateItem();
 		return this;
 	}
 	
+	/**
+	 * 
+	 * remove share form this Folder for a list of users, for everyone or only for the caller. Is applicable only on {@SharedFolder}.
+	 * if users is empty or null unshare the entire folder for everyone.
+	 * if users contains only the caller login the folder is removed only for him.
+	 * 
+	 * @return the current {@FolderContainer} updated
+	 * @throws {@InvalidItemException} if this folder is not share
+	 * @throws {@UserNotAuthorizedException} if user is not authorized to unshare this folder
+	 */
 	public FolderContainer unshare(Set<String> users) throws Exception {
 		String unsharedId = itemclient.unshareFolder(this.itemId, users);
 		return new FolderContainer(itemclient, unsharedId);

src/main/java/org/gcube/common/storagehub/client/dsl/ListResolver.java

@@ -12,6 +12,13 @@ import org.gcube.common.storagehub.model.NodeConstants;
 import org.gcube.common.storagehub.model.exceptions.StorageHubException;
 import org.gcube.common.storagehub.model.items.Item;
 
+/**
+ * Allow user to decorate the item with more Data
+ * 
+ * 
+ * @author lucio
+ *
+ */
 public class ListResolver {
 
 	ListRetriever retriever;
@@ -27,16 +34,35 @@ public class ListResolver {
 		this.itemClient = itemClient;
 	}
 	
+	/**
+	 * 
+	 * add the accounting data to the item returned
+	 * 
+	 * @return {@ListResolver}
+	 */
 	public ListResolver withAccounting(){
 		excludes.remove(NodeConstants.ACCOUNTING_NAME);
 		return this;
 	}
 	
+	/**
+	 * 
+	 * add the content data to the item returned
+	 * 
+	 * @return {@ListResolver}
+	 */
 	public ListResolver withContent(){
 		excludes.remove(NodeConstants.CONTENT_NAME);
 		return this;
 	}
 	
+	
+	/**
+	 * 
+	 * add the Metadata to the item returned
+	 * 
+	 * @return {@ListResolver}
+	 */
 	public ListResolver withMetadata(){
 		excludes.remove(NodeConstants.METADATA_NAME);
 		return this;

src/main/java/org/gcube/common/storagehub/client/dsl/ListResolverTyped.java

@@ -9,11 +9,25 @@ public class ListResolverTyped extends ListResolver {
 		super(retriever, itemClient);
 	}
 
+	/**
+	 * 
+	 * Filter the items returned by the given type
+	 * 
+	 * @param type Item class
+	 * @return {@ListResolver}
+	 */
 	public ListResolver ofType(Class<? extends Item> type){
 		onlyType = type;
 		return this;
 	}
 	
+	
+	/**
+	 * 
+	 * Includes hidden items
+	 *  
+	 * @return {@ListResolver}
+	 */	
 	public ListResolver includeHidden(){
 		includeHidden = true;
 		return this;

src/main/java/org/gcube/common/storagehub/client/proxies/DefaultItemManager.java

@@ -640,6 +640,7 @@ public class DefaultItemManager implements ItemManagerClient {
 		Call<GXWebTargetAdapterRequest, String> call = new Call<GXWebTargetAdapterRequest, String>() {
 			@Override
 			public String call(GXWebTargetAdapterRequest manager) throws Exception {
+				System.out.println("call done");
 				Objects.requireNonNull(parentId, "parentId cannot be null");
 				Objects.requireNonNull(name, "folder name cannot be null");
 				Objects.requireNonNull(description, "parentId cannot be null");

src/main/java/org/gcube/common/storagehub/client/proxies/DefaultWorkspaceManager.java

@@ -350,6 +350,58 @@ public class DefaultWorkspaceManager implements WorkspaceManagerClient {
 		}
 	}
 
+	@Override
+	public String getTotalItemCount() {
+		Call<GXWebTargetAdapterRequest, String> call = new Call<GXWebTargetAdapterRequest, String>() {
+			@Override
+			public String call(GXWebTargetAdapterRequest manager) throws Exception {
+				GXWebTargetAdapterRequest myManager = manager.path("count");
+	
+				GXInboundResponse response = myManager.get();
+				
+				if (response.isErrorResponse()) {
+					if (response.hasException()) 
+						throw response.getException();
+					else 
+						throw new BackendGenericError();
+				}
+				
+				return response.getSource().readEntity(String.class);
+			}
+		};
+		try {
+			return delegate.make(call);
+		}catch(Exception e) {
+			throw new RuntimeException(e);
+		}
+	}
+
+	@Override
+	public String getTotalVolume() {
+		Call<GXWebTargetAdapterRequest, String> call = new Call<GXWebTargetAdapterRequest, String>() {
+			@Override
+			public String call(GXWebTargetAdapterRequest manager) throws Exception {
+				GXWebTargetAdapterRequest myManager = manager.path("size");
+				
+				GXInboundResponse response = myManager.get();
+				
+				if (response.isErrorResponse()) {
+					if (response.hasException()) 
+						throw response.getException();
+					else 
+						throw new BackendGenericError();
+				}
+				
+				return response.getSource().readEntity(String.class);
+			}
+		};
+		try {
+			return delegate.make(call);
+		}catch(Exception e) {
+			throw new RuntimeException(e);
+		}
+	}
+
 
 
 }

src/main/java/org/gcube/common/storagehub/client/proxies/WorkspaceManagerClient.java

@@ -28,4 +28,8 @@ public interface WorkspaceManagerClient {
 
 	void emptyTrash();
 	
+	String getTotalItemCount();
+	
+	String getTotalVolume();
+	
 }

src/test/java/org/gcube/data/access/fs/Items.java

@@ -22,6 +22,7 @@ import org.gcube.common.storagehub.client.dsl.StorageHubClient;
 import org.gcube.common.storagehub.model.acls.AccessType;
 import org.gcube.common.storagehub.model.exceptions.StorageHubException;
 import org.gcube.common.storagehub.model.exceptions.UserNotAuthorizedException;
+import org.gcube.common.storagehub.model.items.FolderItem;
 import org.gcube.common.storagehub.model.items.Item;
 import org.gcube.resources.discovery.client.api.DiscoveryClient;
 import org.gcube.resources.discovery.client.queries.api.SimpleQuery;
@@ -35,8 +36,8 @@ public class Items {
 
 	@BeforeClass
 	public static void setUp(){
-		SecurityTokenProvider.instance.set("7c26a682-f47b-4e6e-90e0-6d101a4314cd-980114272");
+		SecurityTokenProvider.instance.set("b7c80297-e4ed-42ab-ab42-fdc0b8b0eabf-98187548");
-		ScopeProvider.instance.set("/pred4s");
+		ScopeProvider.instance.set("/gcube");
 	}
 		
 	
@@ -51,9 +52,9 @@ public class Items {
 
 		StorageHubClient shc = new StorageHubClient();
 		
-		shc.open("c58e9fc0-7ef8-40d5-9f46-20e823cc8890").asFile().forceDelete();
+		FolderContainer fc = shc.open("7343dd7d-0f2b-4dc7-968e-b856e7073ea8").asFolder();
-		
+				
-		
+		fc.newFolder("testLucio","testLucio");
 		
 	}
 
@@ -99,14 +100,17 @@ public class Items {
 
 
 
-	@Test(expected=UserNotAuthorizedException.class)
+	@Test
 	public void uploadAndcopyFile() throws Exception {
 		StorageHubClient shc = new StorageHubClient();
-
+		
 		FileContainer file = null;
-		try(InputStream is = new FileInputStream(new File("/home/lucio/Downloads/Table.java"))){
+		try(InputStream is = new FileInputStream(new File("/home/lucio/Downloads/PortletTesting.xlsx"))){
-			file = shc.open("3bc977be-37f0-4518-888f-a7cb96c9be8e").asFolder().uploadFile(is, "TableNew.java", "descr");
+			file = shc.open("1672d620-543e-4c76-b0af-4c46f52cbc82").asFolder().uploadFile(is, "PortletTestingSenzaExt", "graphs");
 		} 
+		
+		
+		
 		//file.copy(shc.getWSRoot(), "firstCopy.jpg");
 	}