<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>