You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airavata.apache.org by er...@apache.org on 2017/08/16 19:21:42 UTC
airavata-docs git commit: adding sharing introduction pafe
Repository: airavata-docs
Updated Branches:
refs/heads/master c1c321a5d -> f0c1a96ce
adding sharing introduction pafe
Project: http://git-wip-us.apache.org/repos/asf/airavata-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/airavata-docs/commit/f0c1a96c
Tree: http://git-wip-us.apache.org/repos/asf/airavata-docs/tree/f0c1a96c
Diff: http://git-wip-us.apache.org/repos/asf/airavata-docs/diff/f0c1a96c
Branch: refs/heads/master
Commit: f0c1a96ceccb188f8d0b661da1a7c77412e6ecf3
Parents: c1c321a
Author: Eroma Abeysinghe <er...@gmail.com>
Authored: Wed Aug 16 15:21:36 2017 -0400
Committer: Eroma Abeysinghe <er...@gmail.com>
Committed: Wed Aug 16 15:21:36 2017 -0400
----------------------------------------------------------------------
.idea/dictionaries/eabeysin.xml | 7 +
Sharing-Introduction.md | 362 +++++++++++++++++++++++++++++++++++
mkdocs.yml | 7 +-
3 files changed, 373 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/airavata-docs/blob/f0c1a96c/.idea/dictionaries/eabeysin.xml
----------------------------------------------------------------------
diff --git a/.idea/dictionaries/eabeysin.xml b/.idea/dictionaries/eabeysin.xml
new file mode 100644
index 0000000..3f780d0
--- /dev/null
+++ b/.idea/dictionaries/eabeysin.xml
@@ -0,0 +1,7 @@
+<component name="ProjectDictionaryState">
+ <dictionary name="eabeysin">
+ <words>
+ <w>xsede</w>
+ </words>
+ </dictionary>
+</component>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/airavata-docs/blob/f0c1a96c/Sharing-Introduction.md
----------------------------------------------------------------------
diff --git a/Sharing-Introduction.md b/Sharing-Introduction.md
new file mode 100644
index 0000000..c39c37a
--- /dev/null
+++ b/Sharing-Introduction.md
@@ -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>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/airavata-docs/blob/f0c1a96c/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 4db36fd..de9c201 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -26,9 +26,10 @@ pages:
- <h4>Technical Documentation</h4>:
- Airavata API: 'AiravataApi.md'
- <h6>Sharing Documentation</h6>:
- - Index: 'Sharing-Docs.md'
- - Sharing CPI: 'CPI.md'
- - Sharing Models: 'Models.md'
+ - Introduction: 'Sharing-Introduction.md'
+ - API Methods: 'Sharing-Docs.md'
+ - Sharing CPI: 'CPI.md'
+ - Sharing Models: 'Models.md'
- <h4>FAQ</h4>: 'FAQ.md'
- <h4>Previosur Relese Documentation</h4>: 'Previous-Release-Documentation.md'
- <h4>Contact Us</h4>: 'Contact-Us.md'