-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
3 changed files
with
373 additions
and
3 deletions.
There are no files selected for viewing
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,362 @@ | ||
| <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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters