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.

Note

This component is under active development and this document will keep on evolving. Click here to see the API docs.

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());