Class KiiGroup

  • All Implemented Interfaces:
    KiiSubject, KiiThingOwner

    public final class KiiGroup
    extends java.lang.Object
    implements KiiSubject, KiiThingOwner
    KiiGroup is a representation of group. This class has methods for accessing KiiCloud.
    • Method Detail

      • registerGroupWithID

        @WorkerThread
        @NonNull
        public static KiiGroup registerGroupWithID​(@NonNull
                                                   java.lang.String id,
                                                   @NonNull
                                                   java.lang.String name,
                                                   @Nullable
                                                   java.util.List<KiiUser> members)
                                            throws GroupOperationException
        Register new group own by current user on Kii Cloud with specified ID.
        NOTE: This api access to server. Should not be executed in UI/Main thread.
        Parameters:
        id - ID of the KiiGroup.
        name - Name of the KiiGroup.
        members - Members of the group. Group owner will be added as a group member no matter owner is in the list or not.
        Returns:
        KiiGroup instance.
        Throws:
        GroupOperationException - Thrown if KiiCloud execution error or IO error has happened. (see GroupOperationException)
      • registerGroupWithID

        public static void registerGroupWithID​(@NonNull
                                               java.lang.String id,
                                               @NonNull
                                               java.lang.String name,
                                               @Nullable
                                               java.util.List<KiiUser> members,
                                               @NonNull
                                               KiiCallback<KiiGroup> callback)
        Asynchronous call for KiiGroup#registerGroupWithID(String, String, List). A background task will be initiated to execute the task.
        Parameters:
        id - ID of the KiiGroup.
        name - Name of the KiiGroup.
        members - Members of the group. Group owner will be added as a group member no matter owner is in the list or not.
        callback - Notifies events.
      • createWithNameAndMember

        @NonNull
        public static KiiGroup createWithNameAndMember​(@NonNull
                                                       java.lang.String name,
                                                       @Nullable
                                                       java.util.List<KiiUser> users)
        Create a group own by current user assigning the specified users as group members.
        : Group owner will be added as a group member also by default. This api will NOT access to server immediately. After call this api, call save() to save the group to the cloud.
        Parameters:
        name - Name of the group.
        users - Members of the group. Group owner will be added as a group member no matter owner is in the list or not.
        Returns:
        KiiGroup instance.
      • createWithName

        @NonNull
        public static KiiGroup createWithName​(@NonNull
                                              java.lang.String name)
        Create a group own by current user.
        No other member will be added to the group.
        : Group owner(current log-in user) will be added as a group member by default. This api will NOT access to server immediately. After call this api, call save() to save the group to the cloud.
        Parameters:
        name - Name of the group.
        Returns:
        KiiGroup instance.
      • groupWithID

        @NonNull
        public static KiiGroup groupWithID​(@NonNull
                                           java.lang.String groupID)
        Instantiate KiiGroup that refers to existing group which has specified ID. You have to specify the ID of existing KiiGroup. Unlike KiiObject, you can not assign ID in the client side. After instantiation, call refresh(), listMembers() to fetch the properties and members from server.
        Parameters:
        groupID - ID of the KiiGroup to instantiate.
        Returns:
        instance of KiiGroup.
        Throws:
        java.lang.IllegalArgumentException - when passed groupID is empty or null.
        See Also:
        getID()
      • createByUri

        @NonNull
        public static KiiGroup createByUri​(@NonNull
                                           android.net.Uri uri)
        Create KiiGroup from the Uri. This call does not access to server. To get the latest information from server, need to call refresh(), listMembers()
        Parameters:
        uri - is the Uri of group
        Throws:
        java.lang.IllegalArgumentException - Throw if given URI is null or invalid.
        See Also:
        toUri()
      • toUri

        @Nullable
        public android.net.Uri toUri()
        Retruns URI of this KiiGroup. The format is
        kiicloud://groups/{id of user}
        Returns:
        URI of this Group, null if the group has not saved on cloud.
        Throws:
        java.lang.IllegalStateException - Thrown if SDK not initialized, user not logged in.
      • addUser

        public void addUser​(@NonNull
                            KiiUser user)
        Add a user to this group. This api will NOT access to server immediately. After call this api, call save() to send request server. Multiple user can be added before call save() by calling this api several times.
        Parameters:
        user - is KiiUser who you want to add to this group
        Throws:
        java.lang.IllegalArgumentException - Thrown if the user is null or not registered yet.
      • removeUser

        public void removeUser​(@NonNull
                               KiiUser user)
        Remove a user from this group. This api will NOT access to server immediately. After call this api, call save() to send request server. Multiple user can be removed before call save()
        Parameters:
        user - is KiiUser who you want to remove from this group
        Throws:
        java.lang.IllegalArgumentException - Thrown if the user is null or not registered yet.
      • getOwner

        @Nullable
        public KiiUser getOwner()
                         throws GroupOperationException
        Returns the owner of this group This API will access to server. This API does not return all the properties of the owner. To get all owner properties, KiiUser.refresh() is necessary.
        NOTE: This api access to server. Should not be executed in UI/Main thread.
        Returns:
        KiiUser who owns this group. null if the owner of the Group is absent.
        Throws:
        GroupOperationException - Thrown if the operation failed due to IO error or cloud execution error.
        java.lang.IllegalStateException - Thrown if SDK not initialized, user not logged in, group is not saved yet or deleted.
        See Also:
        getOwner(KiiGroupCallBack)
      • getOwner

        public int getOwner​(@NonNull
                            KiiGroupCallBack callback)
        Asynchronous call for getOwner(). A background task will be initiated to execute the task.
        Parameters:
        callback - notifies events.
        Returns:
        unique ID which is used to cancel this task
        See Also:
        Kii.cancelTask(int)
      • getCachedOwner

        @Nullable
        public KiiUser getCachedOwner()
        Returns the owner of this group if this group holds the information of owner. Group will holds the information of owner when "saving group on cloud" or "retrieving group info/owner from cloud". The cache will not be shared among the different instances of KiiGroup.
        Returns:
        KiiUser who owns this group, null if this group doesn't hold the information of owner yet.
        See Also:
        getOwner(), getOwner(KiiGroupCallBack)
      • listMembers

        @WorkerThread
        @NonNull
        public java.util.List<KiiUser> listMembers()
                                            throws GroupOperationException
        Returns the members of this group. This api will access to server to get the members when this group has already saved on cloud. Returns cached member list immediately when this group has not saved on cloud yet.Owner of the group will not be included as group member in cached members.
        NOTE: This api access to server. Should not be executed in UI/Main thread.
        Returns:
        a list of the member of this group.
        Throws:
        GroupOperationException - Thrown if the operation failed due to IO error or cloud execution error.
        java.lang.IllegalStateException - Thrown if SDK not initialized, user not logged in.
        See Also:
        listMembers(KiiGroupCallBack)
      • listMembers

        public int listMembers​(@NonNull
                               KiiGroupCallBack callback)
        Asynchronous call for listMembers(). A background task will be initiated to execute the task.
        Parameters:
        callback - notifies events.
        Returns:
        unique ID which is used to cancel this task
        See Also:
        Kii.cancelTask(int)
      • refresh

        @WorkerThread
        public void refresh()
                     throws GroupOperationException
        Get latest information of this KiiGroup from the KiiCloud and refresh properties.
        NOTE: This api access to server. Should not be executed in UI/Main thread.
        Throws:
        GroupOperationException - Thrown if KiiCloud execution error or IO error has happened. (see GroupOperationException)
        java.lang.IllegalStateException - Thrown if SDK not initialized, user not logged in, group is not saved yet or deleted.
        See Also:
        refresh(KiiGroupCallBack)
      • changeName

        @WorkerThread
        public void changeName​(@NonNull
                               java.lang.String name)
                        throws GroupOperationException
        Change the name of the group.
        NOTE: This API access to server. Should not be executed in UI/Main thread.
        Throws:
        GroupOperationException - Thrown if KiiCloud execution error or IO error has happened. (see GroupOperationException)
        java.lang.IllegalArgumentException - Thrown if specified name is null or empty.
        java.lang.IllegalStateException - Thrown if SDK not initialized, user not logged in.
        See Also:
        changeName(KiiGroupCallBack, String)
      • changeName

        public int changeName​(@NonNull
                              KiiGroupCallBack callback,
                              @NonNull
                              java.lang.String name)
        Asynchronous call for changeName(String). A background task will be initiated to execute the task.
        Parameters:
        callback - notifies events.
        Returns:
        unique ID which is used to cancel this task
        See Also:
        Kii.cancelTask(int)
      • refresh

        public int refresh​(@NonNull
                           KiiGroupCallBack callback)
        Asynchronous call for refresh(). A background task will be initiated to execute the task.
        Parameters:
        callback - notifies events.
        Returns:
        unique ID which is used to cancel this task
        See Also:
        Kii.cancelTask(int)
      • save

        @WorkerThread
        public void save()
                  throws GroupOperationException
        Save this KiiGroup on cloud. It will create a new group if it is not already created, otherwise update the group.
        NOTE: This api access to server. Should not be executed in UI/Main thread.
        Throws:
        GroupOperationException - Thrown if KiiCloud execution error or IO error has happened. (see GroupOperationException)
        java.lang.IllegalStateException - Thrown if SDK not initialized, user not logged in.
        See Also:
        save(KiiGroupCallBack)
      • save

        public int save​(@NonNull
                        KiiGroupCallBack callback)
        Asynchronous call for save(). A background task will be initiated to execute the task.
        Parameters:
        callback - notifies events.
        Returns:
        unique ID which is used to cancel this task
        See Also:
        Kii.cancelTask(int)
      • delete

        public int delete​(@NonNull
                          KiiGroupCallBack callback)
        Asynchronous call for delete(). A background task will be initiated to execute the task.
        Parameters:
        callback - notifies events.
        Returns:
        unique ID which is used to cancel this task
        See Also:
        Kii.cancelTask(int)
      • bucket

        @NonNull
        public KiiBucket bucket​(@NonNull
                                java.lang.String bucketName)
        Returns the KiiBucket whose scope is this group.
        Parameters:
        bucketName - is a name of KiiBucket.
        Returns:
        KiiBucket whose scope is this group.
        Throws:
        java.lang.IllegalArgumentException - when bucketName is not acceptable format. For details please refer to KiiBucket.isValidBucketName(String)
      • encryptedBucket

        @NonNull
        public KiiEncryptedBucket encryptedBucket​(@NonNull
                                                  java.lang.String bucketName)
        Returns the KiiEncryptedBucket whose scope is this group.
        Parameters:
        bucketName - name of the bucket
        Returns:
        encrypted bucket instance.
        Throws:
        java.lang.IllegalArgumentException - when bucketName is not acceptable format. For details please refer to KiiBucket.isValidBucketName(String)
      • getID

        @Nullable
        public java.lang.String getID()
        Returns the ID of the KiiGroup.
        Returns:
        ID of the KiiGroup, null if the group has not saved to the cloud.
      • getGroupName

        @Nullable
        public java.lang.String getGroupName()
        Returns the group name
      • topic

        @NonNull
        public KiiTopic topic​(@NonNull
                              java.lang.String name)
        Get instance of group scope topic. The topic bound to this group
        Parameters:
        name -
        Returns:
        KiiTopic bound to this group.
      • listTopics

        public void listTopics​(@NonNull
                               KiiCallback<KiiListResult<KiiTopic>> callback)
        Asynchronous call for listTopics(). A background task will be initiated to execute the task.
        Parameters:
        callback - notifies events.
      • getThingOwnerID

        @Nullable
        public java.lang.String getThingOwnerID()
        Description copied from interface: KiiThingOwner
        Get the ID of this owner with prefix.
        Specified by:
        getThingOwnerID in interface KiiThingOwner
        Returns:
        user:{UserID} or group:{GroupID}