Package com.kii.cloud.storage
Class KiiGroup
- java.lang.Object
-
- com.kii.cloud.storage.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 Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addUser(KiiUser user)
Add a user to this group.KiiBucket
bucket(java.lang.String bucketName)
Returns the KiiBucket whose scope is this group.int
changeName(KiiGroupCallBack callback, java.lang.String name)
Asynchronous call forchangeName(String)
.void
changeName(java.lang.String name)
Change the name of the group.static KiiGroup
createByUri(android.net.Uri uri)
Create KiiGroup from the Uri.static KiiGroup
createWithName(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. static KiiGroup
createWithNameAndMember(java.lang.String name, 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. void
delete()
Delete this group from KiiCloud.int
delete(KiiGroupCallBack callback)
Asynchronous call fordelete()
.KiiEncryptedBucket
encryptedBucket(java.lang.String bucketName)
Returns the KiiEncryptedBucket whose scope is this group.KiiUser
getCachedOwner()
Returns the owner of this group if this group holds the information of owner.java.lang.String
getGroupName()
Returns the group namejava.lang.String
getID()
Returns the ID of the KiiGroup.KiiUser
getOwner()
Returns the owner of this group This API will access to server.int
getOwner(KiiGroupCallBack callback)
Asynchronous call forgetOwner()
.java.lang.String
getThingOwnerID()
Get the ID of this owner with prefix.static KiiGroup
groupWithID(java.lang.String groupID)
Instantiate KiiGroup that refers to existing group which has specified ID.java.util.List<KiiUser>
listMembers()
Returns the members of this group.int
listMembers(KiiGroupCallBack callback)
Asynchronous call forlistMembers()
.KiiListResult<KiiTopic>
listTopics()
Returns the list of topics in this group scope.void
listTopics(KiiCallback<KiiListResult<KiiTopic>> callback)
Asynchronous call forlistTopics()
.KiiListResult<KiiTopic>
listTopics(java.lang.String paginationKey)
Returns the next page of list of topics in this group scope.void
listTopics(java.lang.String paginationKey, KiiCallback<KiiListResult<KiiTopic>> callback)
Asynchronous call forlistTopics(String)
.void
refresh()
Get latest information of this KiiGroup from the KiiCloud and refresh properties.int
refresh(KiiGroupCallBack callback)
Asynchronous call forrefresh()
.static KiiGroup
registerGroupWithID(java.lang.String id, java.lang.String name, java.util.List<KiiUser> members)
Register new group own by current user on Kii Cloud with specified ID.static void
registerGroupWithID(java.lang.String id, java.lang.String name, java.util.List<KiiUser> members, KiiCallback<KiiGroup> callback)
Asynchronous call forKiiGroup#registerGroupWithID(String, String, List
.) void
removeUser(KiiUser user)
Remove a user from this group.void
save()
Save this KiiGroup on cloud.int
save(KiiGroupCallBack callback)
Asynchronous call forsave()
.KiiTopic
topic(java.lang.String name)
Get instance of group scope topic.android.net.Uri
toUri()
Retruns URI of this KiiGroup.
-
-
-
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. (seeGroupOperationException
)
-
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 forKiiGroup#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, callrefresh()
,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 callrefresh()
,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, callsave()
to send request server. Multiple user can be added before callsave()
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, callsave()
to send request server. Multiple user can be removed before callsave()
- 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 forgetOwner()
. 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.- This API will not access to server.
To update the group owner information on cloud, please call
refresh()
,refresh(KiiGroupCallBack)
,getOwner()
orgetOwner(KiiGroupCallBack)
. - This API does not return all the properties of the owner.
To get all owner properties,
KiiUser.refresh()
is necessary.
- Returns:
- KiiUser who owns this group, null if this group doesn't hold the information of owner yet.
- See Also:
getOwner()
,getOwner(KiiGroupCallBack)
- This API will not access to server.
To update the group owner information on cloud, please call
-
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 forlistMembers()
. 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. (seeGroupOperationException
)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. (seeGroupOperationException
)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 forchangeName(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 forrefresh()
. 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. (seeGroupOperationException
)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 forsave()
. 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
@WorkerThread public void delete() throws GroupOperationException
Delete this group from KiiCloud.
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. (seeGroupOperationException
)java.lang.IllegalStateException
- Thrown if SDK not initialized, user not logged in or group id is null.IllegalKiiBaseObjectFormatException
- Thrown if JSON error has happened.- See Also:
delete(KiiGroupCallBack)
-
delete
public int delete(@NonNull KiiGroupCallBack callback)
Asynchronous call fordelete()
. 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 toKiiBucket.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 toKiiBucket.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
@NonNull public KiiListResult<KiiTopic> listTopics() throws BadRequestException, UnauthorizedException, ForbiddenException, ConflictException, NotFoundException, UndefinedException, java.io.IOException
Returns the list of topics in this group scope.
NOTE: This api access to server. Should not be executed in UI/Main thread.- Returns:
- a list of the topics in this group scope.
Call
KiiListResult.hasNext()
to check if there are any more result. - Throws:
java.io.IOException
UnauthorizedException
ForbiddenException
BadRequestException
ConflictException
NotFoundException
UndefinedException
-
listTopics
@WorkerThread @NonNull public KiiListResult<KiiTopic> listTopics(@Nullable java.lang.String paginationKey) throws BadRequestException, UnauthorizedException, ForbiddenException, ConflictException, NotFoundException, UndefinedException, java.io.IOException
Returns the next page of list of topics in this group scope.
NOTE: This api access to server. Should not be executed in UI/Main thread.- Parameters:
paginationKey
- Specifies the pagination key that is obtained byKiiListResult.getPaginationKey()
. If specified null or empty, it's same as thelistTopics()
.- Returns:
- a list of the topics in this group scope.
- Throws:
java.io.IOException
UnauthorizedException
ForbiddenException
BadRequestException
ConflictException
NotFoundException
UndefinedException
-
listTopics
public void listTopics(@NonNull KiiCallback<KiiListResult<KiiTopic>> callback)
Asynchronous call forlistTopics()
. A background task will be initiated to execute the task.- Parameters:
callback
- notifies events.
-
listTopics
public void listTopics(@Nullable java.lang.String paginationKey, @NonNull KiiCallback<KiiListResult<KiiTopic>> callback)
Asynchronous call forlistTopics(String)
. A background task will be initiated to execute the task.- Parameters:
paginationKey
- Specifies the pagination key that is obtained byKiiListResult.getPaginationKey()
. If specified null or empty, it's same as thelistTopics(KiiCallback)
.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 interfaceKiiThingOwner
- Returns:
- user:{UserID} or group:{GroupID}
-
-