Class Index | File Index

Classes


Class KiiGroup

Represents a KiiGroup object
Defined in: KiiSDK.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
Method Summary
Method Attributes Method Name and Description
 
addUser(member)
Adds a user to the given group

This method will NOT access the server immediately.
 
bucketWithName(bucketName)
Creates a reference to a bucket for this group

The bucket will be created/accessed within this group's scope
 
changeGroupName(newName, callbacks)
Updates the group name on the server
 
delete(callbacks)
Delete the group from the server
 
Creates a reference to a encrypted bucket for this group

The bucket will be created/accessed within this group's scope
 
Returns the owner of this group if this group holds the information of owner.
 
Get the ID of the current KiiGroup instance.
 
getMemberList(callbacks)
Gets a list of all current members of a group
 
The name of this group
 
getOwner(callbacks)
Gets the owner of the associated group This API does not return all the properties of the owner.
 
<static>  
KiiGroup.groupWithID(groupId)
Instantiate KiiGroup that refers to existing group which has specified ID.
<static>  
KiiGroup.groupWithName(groupName)
Creates a reference to a group with the given name

Note: Returned instance from this API can not operate existing KiiGroup.
<static>  
KiiGroup.groupWithNameAndMembers(groupName, members)
Creates a reference to a group with the given name and a list of default members

Note: Returned instance from this API can not operate existing KiiGroup.
<static>  
KiiGroup.groupWithURI(uri)
Generate a new KiiGroup based on a given URI

Note: Returned instance from this API can operate existing KiiGroup.
 
listTopics(callbacks, paginationKey)
Gets a list of topics in this group scope
 
Get a specifically formatted string referencing the group

The group must exist in the cloud (have a valid UUID).
 
refresh(callbacks)
Updates the local group's data with the group data on the server

The group must exist on the server.
<static>  
KiiGroup.registerGroupWithID(groupID, groupName, members, callbacks)
Register new group own by current user on Kii Cloud with specified ID.
 
removeUser(member)
Removes a user from the given group

This method will NOT access the server immediately.
 
save(callbacks)
Saves the latest group values to the server

If the group does not yet exist, it will be created.
 
saveWithOwner(user, callbacks)
Saves the latest group values to the server with specified owner.
 
topicWithName(topicName)
Instantiate topic belongs to this group.
Class Detail
KiiGroup()
Method Detail
addUser(member)
Adds a user to the given group

This method will NOT access the server immediately. You must call save to add the user on the server. This allows multiple users to be added/removed before calling save.
  var user = . . .; // a KiiUser
  var group = . . .; // a KiiGroup
  group.addUser(user);
  group.save(callbacks);
Parameters:
{KiiUser} member
The user to be added to the group

{KiiBucket} bucketWithName(bucketName)
Creates a reference to a bucket for this group

The bucket will be created/accessed within this group's scope
  var group = . . .; // a KiiGroup
  var bucket = group.bucketWithName("myBucket");
Parameters:
{String} bucketName
The name of the bucket the user should create/access
Returns:
{KiiBucket} A working KiiBucket object

{Promise} changeGroupName(newName, callbacks)
Updates the group name on the server
  // example to use callbacks directly
  var group = . . .; // a KiiGroup
  group.changeGroupName("myNewName", {
      success: function(theRenamedGroup) {
          // do something with the group
      },
  
      failure: function(theGroup, anErrorString) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var group = . . .; // a KiiGroup
  group.changeGroupName("myNewName").then(
      function(theRenamedGroup) {
          // do something with the group
      },
      function(error) {
          // do something with the error response
      }
  );
Parameters:
{String} newName
A String of the desired group name
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful save request
{Method} callbacks.failure
The callback method to call on a failed save request
Returns:
{Promise} return promise object.
  • fulfill callback function: function(theRenamedGroup). theRenamedGroup is KiiGroup instance.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiGroup instance which this method was called on.
    • error.message

{Promise} delete(callbacks)
Delete the group from the server
  // example to use callbacks directly
  var group = . . .; // a KiiGroup
  group.delete({
      success: function(theDeletedGroup) {
          // do something
      },
  
      failure: function(theGroup, anErrorString) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var group = . . .; // a KiiGroup
  group.delete({
      success: function(theDeletedGroup) {
      },
  
      failure: function(theGroup, anErrorString) {
      }
  }).then(
      function(theDeletedGroup) {
          // do something
      },
      function(error) {
          // do something with the error response
      }
  );
Parameters:
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful delete request
{Method} callbacks.failure
The callback method to call on a failed delete request
Returns:
{Promise} return promise object.
  • fulfill callback function: function(theDeletedGroup). theDeletedGroup is KiiGroup instance.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiGroup instance which this method was called on.
    • error.message

{KiiEncryptedBucket} encryptedBucketWithName(bucketName)
Creates a reference to a encrypted bucket for this group

The bucket will be created/accessed within this group's scope
  var group = . . .; // a KiiGroup
  var bucket = group.encryptedBucketWithName("myBucket");
Parameters:
{String} bucketName
The name of the bucket the user should create/access
Returns:
{KiiEncryptedBucket} A working KiiEncryptedBucket object

{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} KiiUser who owns this group, undefined if this group doesn't hold the information of owner yet.
See:
KiiGroup#getOwner

{String} getID()
Get the ID of the current KiiGroup instance.
Returns:
{String} Id of the group or null if the group has not saved to cloud.

{Promise} getMemberList(callbacks)
Gets a list of all current members of a group
  // example to use callbacks directly
  var group = . . .; // a KiiGroup
  group.getMemberList({
      success: function(theGroup, memberList) {
          // do something with the result
          for(var i=0; i<memberList.length; i++){
              var u = memberList[i]; // a KiiUser within the group
          }
      },
  
      failure: function(theGroup, anErrorString) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var group = . . .; // a KiiGroup
  group.getMemberList().then(
      function(params) {
          var theGroup = params[0];
          var memberlist = params[1];
          // do something with the result
          for(var i=0; i<memberList.length; i++){
              var u = memberList[i]; // a KiiUser within the group
          }
      },
      function(error) {
          // do something with the error response
      }
  );
Parameters:
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful list request
{Method} callbacks.failure
The callback method to call on a failed list request
Returns:
{Promise} return promise object.
  • fulfill callback function: function(params). params is Array instance.
    • params[0] is a KiiGroup instance which this method was called on.
    • params[1] is array of memeber KiiUser instances.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiGroup instance which this method was called on.
    • error.message

{String} getName()
The name of this group
Returns:
{String}

{Promise} getOwner(callbacks)
Gets the owner of the associated group This API does not return all the properties of the owner. To get all owner properties, KiiUser#refresh is necessary.
  // example to use callbacks directly
  var group = . . .; // a KiiGroup
  group.getOwner({
      success: function(theGroup, theOwner) {
          // do something
      },
      failure: function(theGroup, anErrorString) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var group = . . .; // a KiiGroup
  group.getOwner().then(
      function(params) {
          // do something
      },
      function(error) {
          // do something with the error response
      }
  );
Parameters:
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful add request
{Method} callbacks.failure
The callback method to call on a failed add request
Returns:
{Promise} return promise object.
  • fulfill callback function: function(params). params is Array instance.
    • params[0] is the KiiGroup instance which this method was called on.
    • params[1] is an group owner KiiUser instances.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiGroup instance which this method was called on.
    • error.message

{String} getUUID()
Deprecated:
Use KiiGroup.getId instead. Get the UUID of the given group, assigned by the server
Returns:
{String}

<static> KiiGroup.groupWithID(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.
NOTE: This API does not access to the server. After instantiation, call KiiGroup#refresh to fetch the properties.
  var group = new KiiUser.groupWithID("__GROUP_ID__");
Parameters:
groupId
ID of the KiiGroup to instantiate.
Throws:
{InvalidArgumentException}
when passed groupID is empty or null.
Returns:
instance of KiiGroup.

<static> {KiiGroup} KiiGroup.groupWithName(groupName)
Creates a reference to a group with the given name

Note: Returned instance from this API can not operate existing KiiGroup.
If you want to operate existing KiiGroup, please use KiiGroup.groupWithURI.
  var group = new KiiGroup.groupWithName("myGroup");
Parameters:
{String} groupName
An application-specific group name
Returns:
{KiiGroup} A new KiiGroup reference

<static> {KiiGroup} KiiGroup.groupWithNameAndMembers(groupName, members)
Creates a reference to a group with the given name and a list of default members

Note: Returned instance from this API can not operate existing KiiGroup.
If you want to operate existing KiiGroup, please use KiiGroup.groupWithURI.
  var group = new KiiGroup.groupWithName("myGroup", members);
Parameters:
{String} groupName
An application-specific group name
{Array} members
An array of KiiUser objects to add to the group
Returns:
{KiiGroup} A new KiiGroup reference

<static> {KiiGroup} KiiGroup.groupWithURI(uri)
Generate a new KiiGroup based on a given URI

Note: Returned instance from this API can operate existing KiiGroup.
If you want to create a new KiiGroup, please use KiiGroup.groupWithName.
  var group = new KiiGroup.groupWithURI("kiicloud://myuri");
Parameters:
{String} uri
The URI of the group to be represented
Throws:
{InvalidURIException}
If the URI given is invalid
Returns:
{KiiGroup} A new KiiGroup with its parameters filled in from the URI

{Promise} listTopics(callbacks, paginationKey)
Gets a list of topics in this group scope
  // example to use callbacks directly
  var group = . . .; // a KiiGroup
  group.listTopics({
      success: function(topicList, nextPaginationKey) {
          // do something with the result
          for(var i=0; i<topicList.length; i++){
              var topic = topicList[i];
          }
          if (nextPaginationKey != null) {
              group.listTopics({
                  success: function(topicList, nextPaginationKey) {...},
                  failure: function(anErrorString) {...}
              }, nextPaginationKey);
          }
      },
      failure: function(anErrorString) {
          // do something with the error response
      }
  });
  
  // example to use promise
  var group = . . .; // a KiiGroup
  group.listTopics().then(
      function(params) {
          var topicList = params[0];
          var nextPaginationKey = params[1];
          // do something with the result
          for(var i=0; i<topicList.length; i++){
              var topic = topicList[i];
          }
          if (nextPaginationKey != null) {
              group.listTopics(null, nextPaginationKey).then(
                  function(params) {...},
                  function(error) {...}
              );
          }
      },
      function(error) {
          // do something with the error response
      }
  );
Parameters:
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful list request
{Method} callbacks.failure
The callback method to call on a failed list request
{String} paginationKey Optional
You can specify the pagination key with the nextPaginationKey passed by callbacks.success. If empty string or no string object is provided, this API regards no paginationKey specified.
Returns:
{Promise} return promise object.
  • fulfill callback function: function(params). params is Array instance.
    • params[0] is array of KiiTopic instances.
    • params[1] is string of nextPaginationKey.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiGroup instance which this method was called on.
    • error.message

{String} objectURI()
Get a specifically formatted string referencing the group

The group must exist in the cloud (have a valid UUID).
  var group = . . .; // a KiiGroup
  var uri = group.objectURI();
Returns:
{String} A URI string based on the current group. null if a URI couldn't be generated.

{Promise} refresh(callbacks)
Updates the local group's data with the group data on the server

The group must exist on the server. Local data will be overwritten.
  // example to use callbacks directly
  var group = . . .; // a KiiGroup
  group.refresh({
      success: function(theRefreshedGroup) {
          // do something with the refreshed group
      },
  
      failure: function(theGroup, anErrorString) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var group = . . .; // a KiiGroup
  group.refresh().then(
      function(theRefreshedGroup) {
          // do something with the refreshed group
      },
      function(error) {
          // do something with the error response
      }
  );
Parameters:
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful refresh request
{Method} callbacks.failure
The callback method to call on a failed refresh request
Returns:
{Promise} return promise object.
  • fulfill callback function: function(theRefreshedGroup). theRefreshedGroup is KiiGroup instance.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiGroup instance which this method was called on.
    • error.message

<static> {Promise} KiiGroup.registerGroupWithID(groupID, groupName, members, callbacks)
Register new group own by current user on Kii Cloud with specified ID.

If the group that has specified id already exists, registration will be failed.
  // example to use callbacks directly
  var members = [];
  members.push(KiiUser.userWithID("Member User Id"));
  KiiGroup.registerGroupWithID("Group ID", "Group Name", members, {
      success: function(theSavedGroup) {
          // do something with the saved group
      },
      failure: function(theGroup, anErrorString, addMembersArray, removeMembersArray) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var members = [];
  members.push(KiiUser.userWithID("Member User Id"));
  KiiGroup.registerGroupWithID("Group ID", "Group Name", members).then(
      function(theSavedGroup) {
          // do something with the saved group
      },
      function(error) {
          var theGroup = error.target;
          var anErrorString = error.message;
          var addMembersArray = error.addMembersArray;
          // do something with the error response
  });
Parameters:
{String} groupID
ID of the KiiGroup
{String} groupName
Name of the KiiGroup
{Array} members
An array of KiiUser objects to add to the group
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful register request
{Method} callbacks.failure
The callback method to call on a failed register request
Returns:
{Promise} return promise object.
  • fulfill callback function: function(theSavedGroup). theSavedGroup is KiiGroup instance.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiGroup instance which this method was called on.
    • error.message
    • error.addMembersArray is array of KiiUser to be added as memebers of this group.
    • error.removeMembersArray is array of KiiUser to be removed from the memebers list of this group.

removeUser(member)
Removes a user from the given group

This method will NOT access the server immediately. You must call save to remove the user on the server. This allows multiple users to be added/removed before calling save.
  var user = . . .; // a KiiUser
  var group = . . .; // a KiiGroup
  group.removeUser(user);
  group.save(callbacks);
Parameters:
{KiiUser} member
The user to be added to the group

{Promise} save(callbacks)
Saves the latest group values to the server

If the group does not yet exist, it will be created. If the group already exists, the members that have changed will be updated accordingly. If the group already exists and there is no updates of members, it will allways succeed but does not execute update. To change the name of group, use #changeGroupName.
  // example to use callbacks directly
  var group = . . .; // a KiiGroup
  group.save({
      success: function(theSavedGroup) {
          // do something with the saved group
      },
  
      failure: function(theGroup, anErrorString, addMembersArray, removeMembersArray) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var group = . . .; // a KiiGroup
  group.save().then(
      function(theSavedGroup) {
          // do something with the saved group
      },
      function(error) {
          var theGroup = error.target;
          var anErrorString = error.message;
          var addMembersArray = error.addMembersArray;
          var removeMembersArray = error.removeMembersArray;
          // do something with the error response
  });
Parameters:
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful save request
{Method} callbacks.failure
The callback method to call on a failed save request
Returns:
{Promise} return promise object.
  • fulfill callback function: function(theSavedGroup). theSavedGroup is KiiGroup instance.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiGroup instance which this method was called on.
    • error.message
    • error.addMembersArray is array of KiiUser to be added as memebers of this group.
    • error.removeMembersArray is array of KiiUser to be removed from the memebers list of this group.

{Promise} saveWithOwner(user, callbacks)
Saves the latest group values to the server with specified owner. This method can be used only by the group owner or app admin.

If the group does not yet exist, it will be created. If the group already exists, the members and owner that have changed will be updated accordingly. If the group already exists and there is no updates of members and owner, it will allways succeed but does not execute update. To change the name of group, use #changeGroupName.
  // example to use callbacks directly
  var group = . . .; // a KiiGroup
  group.saveWithOwner("UserID of owner", {
      success: function(theSavedGroup) {
          // do something with the saved group
      },
  
      failure: function(theGroup, anErrorString, addMembersArray, removeMembersArray) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var group = . . .; // a KiiGroup
  group.saveWithOwner("UserID of owner").then(
      function(theSavedGroup) {
          // do something with the saved group
      },
      function(error) {
          var theGroup = error.target;
          var anErrorString = error.message;
          var addMembersArray = error.addMembersArray;
          var removeMembersArray = error.removeMembersArray;
          // do something with the error response
  });
Parameters:
{String} user
id of owner
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful save request
{Method} callbacks.failure
The callback method to call on a failed save request
Returns:
{Promise} return promise object.
  • fulfill callback function: function(theSavedGroup). theSavedGroup is KiiGroup instance.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiGroup instance which this method was called on.
    • error.message
    • error.addMembersArray is array of KiiUser to be added as memebers of this group.
    • error.removeMembersArray is array of KiiUser to be removed from the memebers list of this group.

{KiiTopic} topicWithName(topicName)
Instantiate topic belongs to this group.
Parameters:
{String} topicName
name of the topic. Must be a not empty string.
Returns:
{KiiTopic} topic instance.

Documentation generated by JsDoc Toolkit 2.4.0 on Wed Sep 15 2021 05:31:33 GMT-0000 (UTC)