| <!-- |
| |
| |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| --> |
| <html> |
| <head> |
| <title>Airavata Sharing Registry Service</title> |
| <link href="style.css" rel="stylesheet" type="text/css"/> |
| </head> |
| <body> |
| <div class="container-fluid"> |
| <h2>Welcome to Airavata Sharing Registry Service Documentation</h2> |
| |
| <p>Airavata Data Sharing Registry Service is a general purpose <b>Collaborative Workspace Management Component</b> |
| that can solve |
| your Scientific Data Management requirements related to sharing and access controlling.</p> |
| |
| <p><span style="color: red; ">N.B. This component is under active development and this document will keep on evolving. Click <a href="./api-docs/index.html">here</a> |
| to see the API docs</span> |
| </p> |
| |
| <div id="#concepts"> |
| <h3>Concepts & Terminology</h3> |
| <img src="sharing_overview.png" alt="Sharing Concepts" height="600" width="800"> |
| </div> |
| <br/> |
| |
| <div id="#getting-started"> |
| <h3>Getting started with the Java client</h3> |
| |
| <div> |
| <ol start="0"> |
| <li><a href="#requirements">Requirements</a></li> |
| <li><a href="#thrift-client">Create a thrift client</a></li> |
| <li><a href="#create-domain">Create a Domain</a></li> |
| <li><a href="#create-users">Create Users</a></li> |
| <li><a href="#create-groups">Create Groups</a></li> |
| <li><a href="#assign-users-to-group">Assign Users to a Group</a></li> |
| <li><a href="#assign-groups-to-group">Assign Groups to a Group</a></li> |
| <li><a href="#create-permission-types">Create Permission Types for your Domain</a></li> |
| <li><a href="#create-entity-types">Create Entity Types for your Domain</a></li> |
| <li><a href="#create-entities">Create Entities</a></li> |
| <li><a href="#sharing-entities">Share Entities</a></li> |
| <li><a href="#checking-user-has-access">Checking User has Permission</a></li> |
| <li><a href="#search-entities">Searching Entities</a></li> |
| </ol> |
| </div> |
| <br/> |
| |
| <div class="definition" id="requirements"> |
| <h4>0. Required maven dependencies</h4> |
| <pre> |
| <dependency> |
| <groupId>org.apache.airavata</groupId> |
| <artifactId>airavata-sharing-registry-stubs</artifactId> |
| <version>0.17-SNAPSHOT</version> |
| </dependency> |
| |
| <dependency> |
| <groupId>org.apache.thrift</groupId> |
| <artifactId>libthrift</artifactId> |
| <version>0.9.3</version> |
| </dependency> |
| </pre> |
| </div> |
| |
| <div class="definition" id="thrift-client"> |
| <h4>1. Creating the thrift client</h4> |
| <pre> |
| //should use the correct host name and port here |
| String serverHost = "gw56.iu.xsede.org"; |
| int serverPort = 7878; |
| |
| TTransport transport = new TSocket(serverHost, serverPort); |
| transport.open(); |
| TProtocol protocol = new TBinaryProtocol(transport); |
| SharingRegistryService.Client sharingServiceClient = new SharingRegistryService.Client(protocol); |
| </pre> |
| </div> |
| |
| <div class="definition" id="create-domain"> |
| <h4>2. Create a domain</h4> |
| <pre> |
| Domain domain = new Domain(); |
| //has to be one word |
| domain.setName("test-domain"); |
| //optional |
| domain.setDescription("test domain description"); |
| |
| //domain id will be same as domain name |
| String domainId = sharingServiceClient.createDomain(domain); |
| </pre> |
| </div> |
| |
| <div class="definition" id="create-users"> |
| <h4>2. Create Users</h4> |
| <pre> |
| User user1 = new User(); |
| String userName = "test-user-1"; |
| String userId1 = "test-user-1"; |
| //required |
| user1.setUserId(userId1); |
| //required |
| user.setUserName(userName); |
| //required |
| user1.setDomainId(domainId); |
| //required |
| user1.setFirstName("John"); |
| //required |
| user1.setLastName("Doe"); |
| //required |
| user1.setEmail("john.doe@abc.com"); |
| //optional - this should be bytes of the users image icon |
| //byte[] icon = new byte[10]; |
| //user1.setIcon(icon); |
| |
| sharingServiceClient.createUser(user1); |
| |
| //Similarly create two more users user2 and user3. |
| . |
| . |
| . |
| </pre> |
| </div> |
| |
| <div class="definition" id="create-groups"> |
| <h4>3. Create User Groups</h4> |
| <pre> |
| UserGroup userGroup1 = new UserGroup(); |
| //required |
| userGroup1.setGroupId("test-group-1"); |
| //required |
| userGroup1.setDomainId(domainId); |
| //required |
| userGroup1.setName("test-group-1"); |
| //optional |
| userGroup1.setDescription("test group description"); |
| //required |
| userGroup1.setOwnerId("test-user-1"); |
| //required |
| userGroup1.setGroupType(GroupType.USER_LEVEL_GROUP); |
| |
| sharingServiceClient.createGroup(userGroup1); |
| |
| //Similarly create another group "userGroup2" with the owner being "test-user-2". |
| . |
| . |
| . |
| </pre> |
| </div> |
| |
| <div class="definition" id="assign-users-to-group"> |
| <h4>4. Assign Users to a Group</h4> |
| <pre> |
| sharingServiceClient.addUsersToGroup(domainId, Arrays.asList("test-user-3"), "test-group-2"); |
| </pre> |
| </div> |
| |
| <div class="definition" id="assign-groups-to-group"> |
| <h4>5. Assign groups to a group</h4> |
| <pre> |
| sharingServiceClient.addChildGroupsToParentGroup(domainId, Arrays.asList("test-group-2"), "test-group-1"); |
| |
| /********************************************/ |
| /* test-group-1 */ |
| /* / \ */ |
| /* / \ */ |
| /* test-user-1 test-group-2 */ |
| /* / \ */ |
| /* test-user-2 test-user-3 */ |
| /********************************************/ |
| </pre> |
| </div> |
| |
| <div class="definition" id="create-permission-types"> |
| <h4>6. Create Permission types for your Domain</h4> |
| <pre> |
| PermissionType permissionType1 = new PermissionType(); |
| //required |
| permissionType1.setPermissionTypeId("READ"); |
| //required |
| permissionType1.setDomainId(domainId); |
| //required |
| permissionType1.setName("READ"); |
| //optional |
| permissionType1.setDescription("READ description"); |
| sharingServiceClient.createPermissionType(permissionType1); |
| |
| PermissionType permissionType2 = new PermissionType(); |
| permissionType2.setPermissionTypeId("WRITE"); |
| permissionType2.setDomainId(domainId); |
| permissionType2.setName("WRITE"); |
| permissionType2.setDescription("WRITE description"); |
| sharingServiceClient.createPermissionType(permissionType2); |
| |
| PermissionType permissionType3 = new PermissionType(); |
| permissionType3.setPermissionTypeId("CLONE"); |
| permissionType3.setDomainId(domainId); |
| permissionType3.setName("CLONE"); |
| permissionType3.setDescription("CLONE description"); |
| sharingServiceClient.createPermissionType(permissionType3); |
| </pre> |
| </div> |
| |
| <div class="definition" id="create-entity-types"> |
| <h4>7. Create Entity Types for your Domain</h4> |
| <pre> |
| EntityType entityType1 = new EntityType(); |
| //required |
| entityType1.setEntityTypeId("PROJECT"); |
| //required |
| entityType1.setDomainId(domainId); |
| //required |
| entityType1.setName("PROJECT"); |
| //optional |
| entityType1.setDescription("PROJECT entity type description"); |
| sharingServiceClient.createEntityType(entityType1); |
| |
| EntityType entityType2 = new EntityType(); |
| entityType2.setEntityTypeId("EXPERIMENT"); |
| entityType2.setDomainId(domainId); |
| entityType2.setName("EXPERIMENT"); |
| entityType2.setDescription("EXPERIMENT entity type"); |
| sharingServiceClient.createEntityType(entityType2); |
| |
| EntityType entityType3 = new EntityType(); |
| entityType3.setEntityTypeId("FILE"); |
| entityType3.setDomainId(domainId); |
| entityType3.setName("FILE"); |
| entityType3.setDescription("FILE entity type"); |
| sharingServiceClient.createEntityType(entityType3); |
| </pre> |
| </div> |
| |
| <div class="definition" id="create-entities"> |
| <h4>8. Create Entities</h4> |
| <pre> |
| Entity entity1 = new Entity(); |
| //required |
| entity1.setEntityId("test-project-1"); |
| //required |
| entity1.setDomainId(domainId); |
| //required |
| entity1.setEntityTypeId("PROJECT"); |
| //required |
| entity1.setOwnerId("test-user-1"); |
| //required |
| entity1.setName("test-project-1"); |
| //optional |
| entity1.setDescription("test project 1 description"); |
| //optional |
| entity1.setFullText("test project 1 stampede gaussian seagrid"); |
| //optional - If not set this will be default to current system time |
| entity1.setOriginalEntityCreationTime(System.currentTimeMillis()); |
| |
| Entity entity2 = new Entity(); |
| entity2.setEntityId("test-experiment-1"); |
| entity2.setDomainId(domainId); |
| entity2.setEntityTypeId("EXPERIMENT"); |
| entity2.setOwnerId("test-user-1"); |
| entity2.setName("test-experiment-1"); |
| entity2.setDescription("test experiment 1 description"); |
| entity2.setParentEntityId("test-project-1"); |
| entity2.setFullText("test experiment 1 benzene"); |
| sharingServiceClient.createEntity(entity2); |
| |
| Entity entity3 = new Entity(); |
| entity3.setEntityId("test-experiment-2"); |
| entity3.setDomainId(domainId); |
| entity3.setEntityTypeId("EXPERIMENT"); |
| entity3.setOwnerId("test-user-1"); |
| entity3.setName("test-experiment-2"); |
| entity3.setDescription("test experiment 2 description"); |
| entity3.setParentEntityId("test-project-1"); |
| entity3.setFullText("test experiment 1 3-methyl 1-butanol stampede"); |
| sharingServiceClient.createEntity(entity3); |
| |
| Entity entity4 = new Entity(); |
| entity4.setEntityId("test-file-1"); |
| entity4.setDomainId(domainId); |
| entity4.setEntityTypeId("FILE"); |
| entity4.setOwnerId("test-user-1"); |
| entity4.setName("test-file-1"); |
| entity4.setDescription("test file 1 description"); |
| entity4.setParentEntityId("test-experiment-2"); |
| entity4.setFullText("test input file 1 for experiment 2"); |
| sharingServiceClient.createEntity(entity4); |
| </pre> |
| </div> |
| |
| <div class="definition" id="sharing-entities"> |
| <h4>9. Share Entities with Users and Groups</h4> |
| <pre> |
| //shared with cascading permissions |
| sharingServiceClient.shareEntityWithUsers(domainId, "test-project-1", Arrays.asList("test-user-2"), "WRITE", true); |
| sharingServiceClient.shareEntityWithGroups(domainId, "test-experiment-2", Arrays.asList("test-group-2"), "READ", true); |
| |
| //shared with non cascading permissions |
| sharingServiceClient.shareEntityWithGroups(domainId, "test-experiment-2", Arrays.asList("test-group-2"), "CLONE", false); |
| |
| /************************************************************************************************************/ |
| /* test-project-1 (OWNER:test-user-1, WRITE:test-user-2) */ |
| /* / \ */ |
| /* test-experiment-1 test-experiment-2 */ |
| /* (OWNER:test-user-1,WRITE:test-user-2) (OWNER:test-user-1, WRITE:test-user-2, READ/CLONE:test-group-2) */ |
| /* | */ |
| /* test-file-1 */ |
| /* (OWNER:test-user-1, WRITE:test-user-2, READ:test-group-2) */ |
| /************************************************************************************************************/ |
| </pre> |
| </div> |
| |
| <div class="definition" id="checking-user-has-access"> |
| <h4>9. Checking whether a User has Permission to access an Entity with specified Permission</h4> |
| <pre> |
| //test-project-1 is explicitly shared with test-user-2 with WRITE permission |
| System.out.println(sharingServiceClient.userHasAccess(domainId, "test-user-2", "test-project-1", "WRITE")); |
| |
| //test-user-2 has WRITE permission to test-experiment-1 and test-experiment-2 indirectly |
| System.out.println(sharingServiceClient.userHasAccess(domainId, "test-user-2", "test-experiment-1", "WRITE")); |
| System.out.println(sharingServiceClient.userHasAccess(domainId, "test-user-2", "test-experiment-2", "WRITE")); |
| |
| //test-user-2 does not have READ permission to test-experiment-1 and test-experiment-2 |
| System.out.println(sharingServiceClient.userHasAccess(domainId, "test-user-2", "test-experiment-1", "READ")); |
| System.out.println(sharingServiceClient.userHasAccess(domainId, "test-user-2", "test-experiment-2", "READ")); |
| |
| //test-user-3 does not have READ permission to test-project-1 |
| System.out.println(sharingServiceClient.userHasAccess(domainId, "test-user-3", "test-project-1", "READ")); |
| |
| //test-experiment-2 is shared with test-group-2 with READ permission. Therefore test-user-3 has READ permission |
| System.out.println(sharingServiceClient.userHasAccess(domainId, "test-user-3", "test-experiment-2", "READ")); |
| |
| //test-user-3 does not have WRITE permission to test-experiment-2 |
| System.out.println(sharingServiceClient.userHasAccess(domainId, "test-user-3", "test-experiment-2", "WRITE")); |
| |
| //test-user-3 has CLONE permission to test-experiment-2 |
| System.out.println((sharingServiceClient.userHasAccess(domainId, "test-user-3", "test-experiment-2", "CLONE"))); |
| //test-user-3 does not have CLONE permission to test-file-1 |
| System.out.println((sharingServiceClient.userHasAccess(domainId, "test-user-3", "test-file-1", "CLONE"))); |
| </pre> |
| </div> |
| |
| <div class="definition" id="search-entities"> |
| <h4>10. Searching Entities</h4> |
| <pre> |
| ArrayList<SearchCriteria> filters = new ArrayList<>(); |
| SearchCriteria searchCriteria = new SearchCriteria(); |
| searchCriteria.setSearchCondition(SearchCondition.FULL_TEXT); |
| searchCriteria.setValue("experiment stampede methyl"); |
| searchCriteria.setSearchField(EntitySearchField.FULL_TEXT); |
| filters.add(searchCriteria); |
| |
| searchCriteria = new SearchCriteria(); |
| searchCriteria.setSearchCondition(SearchCondition.EQUAL); |
| searchCriteria.setValue("EXPERIMENT"); |
| searchCriteria.setSearchField(EntitySearchField.ENTITY_TYPE_ID); |
| filters.add(searchCriteria); |
| |
| searchCriteria = new SearchCriteria(); |
| searchCriteria.setSearchCondition(SearchCondition.EQUAL); |
| searchCriteria.setValue("READ"); |
| searchCriteria.setSearchField(EntitySearchField.PERMISSION_TYPE_ID); |
| filters.add(searchCriteria); |
| |
| System.out.println(sharingServiceClient.searchEntities(domainId, "test-user-2", "EXPERIMENT", filters, 0, -1).size()); |
| </pre> |
| </div> |
| |
| </div> |
| </div> |
| </body> |
| </html> |
