Welcome to Airavata Sharing Registry Service Documentation
Airavata Data Sharing Registry Service is a general purpose Collaborative Workspace Management Component that can solve your Scientific Data Management requirements related to sharing and access controlling.
N.B. This component is under active development and this document will keep on evolving. Click here to see the API docs
Concepts & Terminology
Getting started with the Java client
0. Required maven dependencies
<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>
1. Creating the thrift client
//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);
2. Create a domain
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);
2. Create Users
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.
.
.
.
3. Create User Groups
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".
.
.
.
4. Assign Users to a Group
sharingServiceClient.addUsersToGroup(domainId, Arrays.asList("test-user-3"), "test-group-2");
5. Assign groups to a group
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 */
/********************************************/
6. Create Permission types for your Domain
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);
7. Create Entity Types for your Domain
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);
8. Create Entities
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);
9. Share Entities with Users and Groups
//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) */
/************************************************************************************************************/
9. Checking whether a User has Permission to access an Entity with specified Permission
//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")));
10. Searching Entities
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());