Creating a Group

Any authenticated user can create a new group. The creator of a group becomes the group owner by default.

The following options can be combined for creating a group.

Whether the group ID is automatically assigned by Kii Cloud or specified on the client
Whether group members are specified or not when the group is created

This topic contains sample code for creating a group in the following three combinations of the options. Code parameters enable these combinations.

Creating a group with automatic ID assignment
Creating a group with members
Creating a group with a specified ID

Creating a group with automatic ID assignment

The following sample code shows how to create a group.

// Create a group.
KiiGroup group = Kii.group("myGroup", null);

try {
  // Save the group on the server.
  group.save();

  // Get the reference URI and ID of the group.
  Uri groupUri = group.toUri();
  String groupID = group.getID();
} catch (GroupOperationException e) {
  // Handle the error.
}

// Create a group.
KiiGroup group = Kii.group("myGroup", null);

// Save the group on the server.
group.save(new KiiGroupCallBack() {
  @Override
  public void onSaveCompleted(int token, KiiGroup group, Exception exception) {
    if (exception != null) {
      // Handle the error.
      return;
    }

    // Get the reference URI and ID of the group.
    Uri groupUri = group.toUri();
    String groupID = group.getID();
  }
});

Here is what is happening in the sample code:

Create a KiiGroup instance with the group() method.
Register this KiiGroup instance with the save() method.

The group name can be up to 190 characters. There is no restriction on the characters you can use. The group name can duplicate with the existing ones. You cannot retrieve (reinstantiate) the existing group with its name; the group name is merely for debugging and displaying purposes.

After you create a group, you can get its URI and ID by executing the toUri() and getID() methods. You can use them to retrieve the group later.

Creating a group with members

When you create a new group, you can also set its group members at the same time.

See the next sample code:

// Set a group member.
List<KiiUser> members = new ArrayList<KiiUser>();
members.add(KiiUser.userWithID("User ID of a member"));

// Create a group.
KiiGroup group = Kii.group("myGroup", members);

try {
  // Save the group on the server.
  group.save();

  // Get the reference URI and ID of the group.
  Uri groupUri = group.toUri();
  String groupID = group.getID();
} catch (GroupOperationException e) {
  // Handle the error.
}

// Set a group member.
List<KiiUser> members = new ArrayList<KiiUser>();
members.add(KiiUser.userWithID("User ID of a member"));

// Create a group.
KiiGroup group = Kii.group("myGroup", members);

// Save the group on the server.
group.save(new KiiGroupCallBack() {
  @Override
  public void onSaveCompleted(int token, KiiGroup group, Exception exception) {
    if (exception != null) {
      // Handle the error.
      return;
    }

    // Get the reference URI and ID of the group.
    Uri groupUri = group.toUri();
    String groupID = group.getID();
  }
});

Set the group members in the second argument of the group() method.

You can also add group members later.

Creating a group with a specified ID

In the previous sample code, the group ID is automatically assigned. You can also specify the group ID explicitly when you create the group.

The next sample is creating a new group, this time with its ID.

// This example assumes that users have a custom attribute "userSequence".
// Create a group ID with the attribute.
String userShortID = KiiUser.getCurrentUser().getString("userSequence");
String groupID = "my-group-" + userShortID;
String groupName = "myGroup";

try {
  // Create and save a group on the server.
  KiiGroup group = KiiGroup.registerGroupWithID(groupID, groupName, null);

  // Get the reference URI of the group.
  Uri groupUri = group.toUri();
} catch (GroupOperationException e) {
  // Handle the error.
}

// This example assumes that users have a custom attribute "userSequence".
// Create a group ID with the attribute.
String userShortID = KiiUser.getCurrentUser().getString("userSequence");
String groupID = "my-group-" + userShortID;
String groupName = "myGroup";

// Create and save a group on the server.
KiiGroup.registerGroupWithID(groupID, groupName, null, new KiiCallback<KiiGroup>() {
  @Override
  public void onComplete(KiiGroup group, Exception exception) {
    if (exception != null) {
      // Handle the error.
      return;
    }

    // Get the reference URI of the group.
    Uri groupUri = group.toUri();
  }
});

We use the registerGroupWithID() method for creating a group with its group ID. The group ID can contain alphanumeric (lower-case only), period (.), dash (-), and underscore (_). The maximum length of the group ID is 30 characters. You will get an error if you try to set a group ID that duplicates with the existing one.

In the above sample code, we are concatenating a unique value which represents a user with the prefix "my-group-" and using it as the group ID. This will allow spotting IDs of groups owned by a certain user. This naming method is useful, for instance, if you are managing Twitter-like followers with the group feature. The above sample code assumes that a short unique value such as a sequence number has been configured as a custom attribute. You cannot use the user ID as a part of the group ID because it would exceed the maximum length of 30 characters for the group ID.

You can also set the group members at the same time. Set the group members in the third argument of the registerGroupWithID() method.