com.kii.cloud.storage
Class KiiGroup

java.lang.Object
  extended by com.kii.cloud.storage.KiiGroup
All Implemented Interfaces:
KiiSubject

public final class KiiGroup
extends java.lang.Object
implements KiiSubject

KiiGroup is a representation of group. This class has methods for accessing KiiCloud.


Method Summary
 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 for changeName(String).
 void changeName(java.lang.String name)
          Change the name of the group.
static KiiGroup createByUri(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 for delete().
 java.lang.String getGroupName()
          Returns the group name
 KiiUser getOwner()
          Returns the owner of this group This API will access to server.
 int getOwner(KiiGroupCallBack callback)
          Asynchronous call for getOwner().
 java.util.List<KiiUser> listMembers()
          Returns the members of this group.
 int listMembers(KiiGroupCallBack callback)
          Asynchronous call for listMembers().
 void refresh()
          Get latest information of this KiiGroup from the KiiCloud and refresh properties.
 int refresh(KiiGroupCallBack callback)
          Asynchronous call for refresh().
 void removeUser(KiiUser user)
          Remove a user from this group.
 void save()
          Save this KiiGroup on cloud.
 int save(KiiGroupCallBack callback)
          Asynchronous call for save().
 KiiTopic topic(java.lang.String name)
          Get instance of group scope topic.
 Uri toUri()
          Retruns URI of this KiiGroup.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

addUser

public void addUser(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.

bucket

public KiiBucket bucket(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)

changeName

public int changeName(KiiGroupCallBack callback,
                      java.lang.String name)
Asynchronous call for changeName(String). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - notifies events.
Returns:
unique ID which is used to cancel this task
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.
See Also:
Kii.cancelTask(int)

changeName

public void changeName(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)

createByUri

public static KiiGroup createByUri(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()

createWithName

public 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. This api will NOT access to server immediately. After call this api, call save() to save the group to the cloud.

Parameters:
groupName - Name of the group.
Returns:
KiiGroup instance.

createWithNameAndMember

public 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. This api will NOT access to server immediately. After call this api, call save() to save the group to the cloud.

Parameters:
groupName - Name of the group.
groupMembers - 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.

delete

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. (see GroupOperationException)
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(KiiGroupCallBack callback)
Asynchronous call for delete(). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - notifies events.
Returns:
unique ID which is used to cancel this task
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.
See Also:
Kii.cancelTask(int)

getGroupName

public java.lang.String getGroupName()
Returns the group name


getOwner

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(KiiGroupCallBack callback)
Asynchronous call for getOwner(). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - notifies events.
Returns:
unique ID which is used to cancel this task
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.
See Also:
Kii.cancelTask(int)

listMembers

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(KiiGroupCallBack callback)
Asynchronous call for listMembers(). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - notifies events.
Returns:
unique ID which is used to cancel this task
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.
See Also:
Kii.cancelTask(int)

refresh

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)

refresh

public int refresh(KiiGroupCallBack callback)
Asynchronous call for refresh(). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - notifies events.
Returns:
unique ID which is used to cancel this task
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.
See Also:
Kii.cancelTask(int)

removeUser

public void removeUser(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.

save

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(KiiGroupCallBack callback)
Asynchronous call for save(). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - notifies events.
Returns:
unique ID which is used to cancel this task
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.
See Also:
Kii.cancelTask(int)

topic

public KiiTopic topic(java.lang.String name)
Get instance of group scope topic. The topic bound to this group

Parameters:
name -
Returns:
KiiTopic bound to this group.

toUri

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