AndroidAndroid V4 Objects (BETA) API Reference for Realtime Apps

This page describes the Objects v1 (Beta) that will soon be deprecated. Objects v2 coming soon for this SDK.

In the Android V4 SDK, and in terms of the Objects API, a User is represented as an instance of PNUser. A PNUser is instantiated as follows:

PNUser pnUser = new PNUser("user_1", "foo");

The user's id and name are mandatory and as such need to be passed directly to the constructor.

Other properties (except the id) are settable via setters:

pnUser.setEmail("foo@bar.com");
pnUser.setExternalId("user_foo");

HashMap<String, Object> customUserMap = new HashMap<>();
customUserMap.put("role", "student");
customUserMap.put("enrolled", true);
pnUser.setCustom(customUserMap);

The PNUser class features other properties too, which are not settable directly. Instead, the server is responsible for them and assigns values in different scenarios (e.g. when getting a user from PubNub).

pnUser.getCreated(); // user creation date
pnUser.getUpdated(); // user update date
pnUser.getETag();    // etag
MethodReturn typeDescription
getId()StringReturns the user's unique identifier.
getName()StringReturns the user's name.
getEmail()StringReturns the user's email.
getExternalId()StringReturns the user's external identifier.
getProfileUrl()StringReturns the the URL of the user's profile picture.
getCustom()ObjectReturns the user's deserializable custom data.
getCreated()StringReturns the date and time the object was created.
getUpdated()StringReturns the date and time the object was updated.
getETag()StringReturns the the object's content fingerprint used in conditional requests.
MethodParameter TypeDescription
PNUser()String, StringCreates a new instance of PNUser with id and name provided.
setName()StringSets the name of the user.
getEmail()StringSets a personal email address.
setExternalId()StringSets a user's identifier in an external system.
setProfileUrl()StringSets a user's profile picture URL.
setCustom()ObjectSets a user's custom data. Serialization is done automatically, but the end result must be a Json object with scalar values only.
 
The setters are chainable and offer a fluent API as such.

Creates a user with the specified properties. Returns the created user object, optionally including the user's custom data object.

To Create a User you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    userPNUserYesThe user you wish to create.
    includeFieldsPNUserFields[]NoArray of additional/complex user attributes to include in response.
    syncPNCreateUserResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNCreateUserResult>NoExecutes the call asynchronously.
PNUser pnUser = new PNUser("user_1", "foo");

pubnub.createUser()
    .user(pnUser)
    .async(new PNCallback<PNCreateUserResult>() {
        @Override
        public void onResponse(PNCreateUserResult result, PNStatus status) {
            if (!status.isError()) {
                PNUser user = result.getUser(); // the created user object
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }
        }
    });
The createUser() operation returns a PNCreateUserResult object which contains the following operations:
MethodTypeDescription
getUser()PNUserReturns the created user.
  1. PNUser pnUser = new PNUser("user_1", "foo");
    
    JsonObject customData = new JsonObject();
    customData.addProperty("color", "red");
    customData.addProperty("city", "SF");
    
    pnUser.setCustom(customData);
    
    pubnub.createUser()
        .user(pnUser)
        .includeFields(PNUserFields.CUSTOM)
        .async(new PNCallback<PNCreateUserResult> () {
            @Override
            public void onResponse(PNCreateUserResult result, PNStatus status) {
                if (!status.isError()) {
                    PNUser user = result.getUser(); // the created user object
                    Object custom = user.getCustom(); // the requested custom payload (if any)
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });

Updates a user with the specified properties. Returns the updated user object, optionally including the user's custom data object.

To Update a User you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    userPNUserNoThe user to update.
    includeFieldsPNUserFields[]NoArray of additional/complex user attributes to include in response.
    syncPNUpdateUserResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNUpdateUserResult>NoExecutes the call asynchronously.
     
    • You can change all of the user object's properties, except its ID.
    • Invalid property names are silently ignored and will not cause a request to fail.
    • If you update the custom property, you must completely replace it; partial updates are not supported.
PNUser pnUser = new PNUser("user_1", "foo"); // assume this user is already created
pnUser.setEmail("foo@bar.com"); // set a new email address

pubnub.updateUser()
    .user(pnUser)
    .async(new PNCallback<PNUpdateUserResult> () {
        @Override
        public void onResponse(PNUpdateUserResult result, PNStatus status) {
            if (!status.isError()) {
                PNUser user = result.getUser(); // the updated user object
                System.out.println(user.getEmail()); // prints foo@bar.com
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }
        }
    });
The updateUser() operation returns a PNUpdateUserResult object which contains the following operations:
MethodTypeDescription
updateUser()PNUserReturns the updated user.
  1. PNUser pnUser = new PNUser("user_1", "foo"); // assume this user is already created
    pnUser.setEmail("foo@bar.com"); // set a new email address
    
    // set another custom object
    HashMap <String, Object> customUserMap = new HashMap<> ();
    customUserMap.put("city", "SF");
    customUserMap.put("age", 22);
    pnUser.setCustom(customUserMap);
    
    pubnub.updateUser()
        .includeFields(PNUserFields.CUSTOM)
        .user(pnUser)
        .async(new PNCallback < PNUpdateUserResult > () {
            @Override
            public void onResponse(PNUpdateUserResult result, PNStatus status) {
                if (!status.isError()) {
                    PNUser user = result.getUser(); // the updated user object
                    user.getCustom(); // user's custom data
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });

Deletes the specified user object.

To Delete a User you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    userIdStringYesID of the user to delete.
    syncPNDeleteUserResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNDeleteUserResult>NoExecutes the call asynchronously.
pubnub.deleteUser()
    .userId("user_1")
    .async(new PNCallback<PNDeleteUserResult> () {
        @Override
        public void onResponse(PNDeleteUserResult result, PNStatus status) {
            if (!status.isError()) {
                // no actionable data
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }

        }
    });
The deleteUser() operation returns a PNDeleteUserResult object which has no actionable data.

Returns a paginated list of user objects, optionally including each user's custom data object.

To Get Users you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    includeFieldsPNUserFields[]NoArray of additional/complex user attributes to include in response.
    limitIntegerNoNumber of users to return in response.
    startStringNoPreviously-returned cursor bookmark for fetching the next page.
    endStringNoPreviously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.
    withTotalCountBooleanNoRequest totalCount to be included in paginated response.
    By default, totalCount is omitted.
    filterStringNoExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.

    In addition to custom attributes, the expressions can refer to attributes on associated entities one level deep (that is, the association and its target entities).
    syncPNGetUsersResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNGetUsersResult>NoExecutes the call asynchronously.
pubnub.getUsers()
    .async(new PNCallback<PNGetUsersResult> () {
        @Override
        public void onResponse(PNGetUsersResult result, PNStatus status) {
            if (!status.isError()) {
                List<PNUser> users = result.getData(); // the requested user list
                result.getNext(); // cursor bookmark for the next page
                result.getPrev(); // cursor bookmark for the previous page result
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }
        }
    });
The getUsers() operation returns a PNGetUsersResult object which contains the following operations:
MethodTypeDescription
getData()List<PNUser>Returns the requested user list.
getNext()StringReturns cursor bookmark for fetching the next page.
getPrev()StringReturns cursor bookmark for fetching the previous page.
getTotalCount()IntegerReturns the total count of objects without pagination.
  1. pubnub.getUsers()
        .includeFields(PNUserFields.CUSTOM)
        .async(new PNCallback<PNGetUsersResult>() {
            @Override
            public void onResponse(PNGetUsersResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNUser> users = result.getData(); // the requested users
                    for (PNUser user : users) {
                        user.getCustom(); // user's custom data (if any)
                    }
                    result.getNext(); // cursor bookmark for the next page
                    result.getPrev(); // cursor bookmark for the previous page result
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });
  2. void main() {
        fetchUsers(null, new FetchCallback() {
            @Override
            public void done(PNGetUsersResult result) {
                List<PNUser> users = result.getData(); // the requested users
            }
        });
    }
    
    interface FetchCallback {
    
        void done(PNGetUsersResult result);
    }
    
    /**
     * Fetches 10 users at a time, recursively and in a paged manner.
     *
     * @param next     The cursor bookmark for the next page.
     * @param callback The callback to dispatch fetched users to.
     */
    void fetchUsers(String next, FetchCallback callback) {
        GetUsers getUsersBuilder = pubnub.getUsers()
            .includeFields(PNUserFields.CUSTOM)
            .limit(10)
            .withTotalCount(true);
    
        if (next != null)
            getUsersBuilder.start(next);
    
        getUsersBuilder.async(new PNCallback<PNGetUsersResult> () {
            @Override
            public void onResponse(PNGetUsersResult result, PNStatus status) {
                if (!status.isError()) {
                    if (!(result.getData().isEmpty())) {
                        callback.done(result);
                        fetchUsers(result.getNext(), callback);
                    }
                }
            }
        });
    }
  3. pubnub.getUsers()
        .filter("email like '*@pubnub.com'")
        .async(new PNCallback<PNGetUsersResult>() {
            @Override
            public void onResponse(PNGetUsersResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNUser> users = result.getData();
                    // the requested users which match the criteria
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });

Returns the specified user object, optionally including the user's custom data object.

To Get User you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    userIdStringYesThe ID of the user to retrieve.
    includeFieldsPNGetUserResultNoAdditional JSON fields to be returned in the response.
    syncPNGetUserResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNGetUserResult>NoExecutes the call asynchronously.
pubnub.getUser()
    .userId("user_1")
    .async(new PNCallback<PNGetUserResult> () {
        @Override
        public void onResponse(PNGetUserResult result, PNStatus status) {
            if (!status.isError()) {
                PNUser user = result.getUser(); // the requested user object
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }
        }
    });
The getUser() operation returns a PNGetUserResult object which contains the following operations:
MethodTypeDescription
getUser()PNUserReturns the requested user.
  1. pubnub.getUser()
        .userId("user_1")
        .includeFields(PNUserFields.CUSTOM)
        .async(new PNCallback<PNGetUserResult> () {
            @Override
            public void onResponse(PNGetUserResult result, PNStatus status) {
                if (!status.isError()) {
                    PNUser user = result.getUser(); // the requested user object
                    Object custom = user.getCustom(); // the requested custom payload (if any)
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });

In the Android V4 SDK, and in terms of the Objects API, a Space is represented as an instance of PNSpace. A PNSpace is instantiated as follows:

PNSpace pnSpace = new PNSpace("space_1", "foo");

The spaces's id and name are mandatory and as such need to be passed directly to the constructor.

Other properties (except the id) are settable via setters:

pnSpace.setDescription("A lovely space.");

HashMap<String, Object> customSpaceMap = new HashMap<>();
customSpaceMap.put("color", "blue");
customSpaceMap.put("public", true);
pnSpace.setCustom(customSpaceMap);

The PNSpace class features other properties too, which are not settable directly. Instead, the server is responsible for them and assigns values in different scenarios (e.g. when getting a space from PubNub).

pnSpace.getCreated(); // space creation date
pnSpace.getUpdated(); // space update date
pnSpace.getETag();    // etag
MethodReturn typeDescription
getId()StringReturns the space's unique identifier.
getName()StringReturns the space's name.
getDescription()StringReturns the space's description.
getCustom()ObjectReturns the space's deserializable custom data.
getCreated()StringReturns the date and time the object was created.
getUpdated()StringReturns the date and time the object was updated.
getETag()StringReturns the the object's content fingerprint used in conditional requests.
MethodParameter TypeDescription
PNSpace()String, StringCreates a new instance of PNSpace with id and name provided.
setName()StringSets the name of the space.
setDescription()StringSets the description of the space.
setCustom()ObjectSets a space's custom data. Serialization is done automatically, but the end result must be a Json object with scalar values only.
 
The setters are chainable and offer a fluent API as such.

Creates a space with the specified properties. Returns the created space object, optionally including the space's custom data object.

To Create a Space you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    spacePNSpaceYesThe space you wish to create.
    includeFieldsPNSpaceFields[]NoArray of additional/complex space attributes to include in response.
    syncPNCreateSpaceResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNCreateSpaceResult>NoExecutes the call asynchronously.
PNSpace pnSpace = new PNSpace("space_1", "foo");

pubnub.createSpace()
    .space(pnSpace)
    .async(new PNCallback<PNCreateSpaceResult>() {
        @Override
        public void onResponse(PNCreateSpaceResult result, PNStatus status) {
            if (!status.isError()) {
                PNSpace space = result.getSpace(); // the created space object
                } else {
                status.getErrorData().getThrowable().printStackTrace();
            }
        }
    });
The createSpace() operation returns a PNCreateSpaceResult object which contains the following operations:
MethodTypeDescription
getSpace()PNSpaceReturns the created space.
  1. PNSpace pnSpace = new PNSpace("space_1", "foo");
    
    JsonObject customData = new JsonObject();
    customData.addProperty("color", "red");
    customData.addProperty("city", "SF");
    
    pnSpace.setCustom(customData);
    
    pubnub.createSpace()
        .space(pnSpace)
        .includeFields(PNSpaceFields.CUSTOM)
        .async(new PNCallback<PNCreateSpaceResult> () {
            @Override
            public void onResponse(PNCreateSpaceResult result, PNStatus status) {
                if (!status.isError()) {
                    PNSpace space = result.getSpace(); // the created space object
                    Object custom = space.getCustom(); // the requested custom payload (if any)
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });

Updates a space with the specified properties. Returns the updated space object, optionally including the space's custom data object.

To Update a Space you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    spacePNSpaceNoThe space to update.
    includeFieldsPNSpaceFields[]NoArray of additional/complex space attributes to include in response.
    syncPNUpdateSpaceResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNUpdateSpaceResult>NoExecutes the call asynchronously.
     
    • You can change all of the space object's properties, except its ID.
    • Invalid property names are silently ignored and will not cause a request to fail.
    • If you update the custom property, you must completely replace it; partial updates are not supported.
PNSpace pnSpace = new PNSpace("space_1", "foo"); // assume this space is already created
pnSpace.setEmail("foo@bar.com"); // set a new email address

pubnub.updateSpace()
    .space(pnSpace)
    .async(new PNCallback<PNUpdateSpaceResult> () {
        @Override
        public void onResponse(PNUpdateSpaceResult result, PNStatus status) {
            if (!status.isError()) {
                PNSpace space = result.getSpace(); // the updated space object
                System.out.println(space.getEmail()); // prints foo@bar.com
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }
        }
    });
The updateSpace() operation returns a PNUpdateSpaceResult object which contains the following operations:
MethodTypeDescription
updateSpace()PNSpaceReturns the updated space.
  1. PNSpace pnSpace = new PNSpace("space_1", "foo"); // assume this space is already created
    pnSpace.setEmail("foo@bar.com"); // set a new email address
    
    // set another custom object
    HashMap <String, Object> customSpaceMap = new HashMap<> ();
    customSpaceMap.put("city", "SF");
    customSpaceMap.put("limit", 30);
    pnSpace.setCustom(customSpaceMap);
    
    pubnub.updateSpace()
        .includeFields(PNSpaceFields.CUSTOM)
        .space(pnSpace)
        .async(new PNCallback<PNUpdateSpaceResult> () {
            @Override
            public void onResponse(PNUpdateSpaceResult result, PNStatus status) {
                if (!status.isError()) {
                    PNSpace space = result.getSpace(); // the updated space object
                    space.getCustom(); // space's custom data
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });

Deletes the specified space object.

To Delete a Space you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    spaceIdStringYesID of the space to delete.
    syncPNDeleteSpaceResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNDeleteSpaceResult>NoExecutes the call asynchronously.
pubnub.deleteSpace()
    .spaceId("space_1")
    .async(new PNCallback<PNDeleteSpaceResult> () {
        @Override
        public void onResponse(PNDeleteSpaceResult result, PNStatus status) {
            if (!status.isError()) {
                // no actionable data
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }

        }
    });
The deleteSpace() operation returns a PNDeleteSpaceResult object which has no actionable data.

Returns the paginated list of space objects, optionally including the space's custom data object.

To Get Spaces you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    includeFieldsPNSpaceFields[]NoArray of additional/complex space attributes to include in response.
    limitIntegerNoNumber of spaces to return in response.
    Default is 100, which is also the maximum value.
    startStringNoPreviously-returned cursor bookmark for fetching the next page.
    endStringNoPreviously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.
    withTotalCountBooleanNoRequest totalCount to be included in paginated response.
    By default, totalCount is omitted.
    filterStringNoExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.

    In addition to custom attributes, the expressions can refer to attributes on associated entities one level deep (that is, the association and its target entities).
    syncPNGetSpacesResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNGetSpacesResult>NoExecutes the call asynchronously.
pubnub.getSpaces()
    .async(new PNCallback<PNGetSpacesResult> () {
        @Override
        public void onResponse(PNGetSpacesResult result, PNStatus status) {
            if (!status.isError()) {
                List<PNSpace> spaces = result.getData(); // the requested space list
                result.getNext(); // cursor bookmark for the next page
                result.getPrev(); // cursor bookmark for the previous page result
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }
        }
    });
The getSpaces() operation returns a PNGetSpacesResult object which contains the following operations:
MethodTypeDescription
getData()List<PNSpace>Returns the requested space list.
getNext()StringReturns cursor bookmark for fetching the next page.
getPrev()StringReturns cursor bookmark for fetching the previous page.
getTotalCount()IntegerReturns the total count of objects without pagination.
  1. pubnub.getSpaces()
        .includeFields(PNSpaceFields.CUSTOM)
        .async(new PNCallback<PNGetSpacesResult> () {
            @Override
            public void onResponse(PNGetSpacesResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNSpace> spaces = result.getData(); // the requested spaces
                    for (PNSpace space: spaces) {
                        space.getCustom(); // space's custom data (if any)
                    }
                    result.getNext(); // cursor bookmark for the next page
                    result.getPrev(); // cursor bookmark for the previous page result
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });
  2. void main() {
        fetchSpaces(null, new FetchCallback() {
            @Override
            public void done(PNGetSpacesResult result) {
                List<PNSpace> spaces = result.getData(); // the requested spaces
            }
        });
    }
    
    interface FetchCallback {
    
        void done(PNGetSpacesResult result);
    }
    
    /**
     * Fetches 10 spaces at a time, recursively and in a paged manner.
     *
     * @param next     The cursor bookmark for the next page.
     * @param callback The callback to dispatch fetched spaces to.
     */
    void fetchSpaces(String next, FetchCallback callback) {
        GetSpaces getSpacesBuilder = pubnub.getSpaces()
            .includeFields(PNSpaceFields.CUSTOM)
            .limit(10)
            .withTotalCount(true);
    
        if (next != null)
            getSpacesBuilder.start(next);
    
        getSpacesBuilder.async(new PNCallback<PNGetSpacesResult> () {
            @Override
            public void onResponse(PNGetSpacesResult result, PNStatus status) {
                if (!status.isError()) {
                    if (!(result.getData().isEmpty())) {
                        callback.done(result);
                        fetchSpaces(result.getNext(), callback);
                    }
                }
            }
        });
    }
  3. pubnub.getSpaces()
        .filter("custom.public == true")
        .async(new PNCallback<PNGetSpacesResult>() {
            @Override
            public void onResponse(PNGetSpacesResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNSpace> spaces = result.getData();
                    // the requested spaces which match the criteria
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });

Returns the specified space object, optionally including the space's custom data object.

To Get a Space you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    spaceIdStringYesThe ID of the space to retrieve.
    includeFieldsPNGetSpaceResultNoAdditional JSON fields to be returned in the response.
    syncPNGetSpaceResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNGetSpaceResult>NoExecutes the call asynchronously.
pubnub.getSpace()
    .spaceId("space_1")
    .async(new PNCallback<PNGetSpaceResult> () {
        @Override
        public void onResponse(PNGetSpaceResult result, PNStatus status) {
            if (!status.isError()) {
                PNSpace space = result.getSpace(); // the requested space object
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }
        }
    });
The getSpace() operation returns a PNGetSpaceResult object which contains the following operations:
MethodTypeDescription
getSpace()PNSpaceReturns the requested space.
  1. pubnub.getSpace()
        .spaceId("space_1")
        .includeFields(PNSpaceFields.CUSTOM)
        .async(new PNCallback<PNGetSpaceResult> () {
            @Override
            public void onResponse(PNGetSpaceResult result, PNStatus status) {
                if (!status.isError()) {
                    PNSpace space = result.getSpace(); // the requested space object
                    Object custom = space.getCustom(); // the requested custom payload (if any)
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });

In the Android V4 SDK, and in terms of the Objects API, a Member is represented as an instance of PNMember. A PNMember can't be instantiated, as it's created indirectly in different scenarios (e.g. when getting members from PubNub). A PNMember is just a wrapper around PNUser.

MethodReturn typeDescription
getUser()PNUserReturns the belonging user.
getCustom()ObjectReturns the members's deserializable custom data.
getCreated()StringReturns the date and time the object was created.
getUpdated()StringReturns the date and time the object was updated.
getETag()StringReturns the the object's content fingerprint used in conditional requests.

However, to manage members on your own and to avoid creating ad-hoc json data, a tiny helper class is available to do so: Member. It's a easy-to-use wrapper class:

Member memberFoo = Member.userId("foo"); // instantiates a Member

HashMap<String, Object> customMap = new HashMap<>();
customMap.put("starred", true);
Member memberBar = Member.userId("bar").custom(customMap); // instantiates a Member and also sets its custom data

Get the specified space’s member users.

To Get Members you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    spaceIdStringYesID of the space whose members you wish to retrieve.
    includeFieldsPNMemberFields[]NoList of additional/complex attributes to include in response.
    limitIntegerNoNumber of members to return in response.
    startStringNoPreviously-returned cursor bookmark for fetching the next page.
    endStringNoPreviously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.
    withTotalCountBooleanNoRequest totalCount to be included in paginated response.
    By default, totalCount is omitted.
    filterStringNoExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.

    In addition to custom attributes, the expressions can refer to attributes on associated entities one level deep (that is, the association and its target entities).
    syncPNGetMembersResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNGetMembersResult>NoExecutes the call asynchronously.
pubnub.getMembers()
    .spaceId("space_1")
    .async(new PNCallback<PNGetMembersResult> () {
        @Override
        public void onResponse(PNGetMembersResult result, PNStatus status) {
            if (!status.isError()) {
                List<PNMember> memberList = result.getData(); // requested member list
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }
        }
    });
The getMembers() operation returns a PNGetMembersResult object which contains the following operations:
MethodTypeDescription
getData()List<PNMember>Returns the requested members list.
getNext()StringReturns cursor bookmark for fetching the next page.
getPrev()StringReturns cursor bookmark for fetching the previous page.
getTotalCount()IntegerReturns the total count of objects without pagination.
  1. pubnub.getMembers()
        .spaceId("space_1")
        .includeFields(PNMemberFields.CUSTOM, PNMemberFields.USER, PNMemberFields.USER_CUSTOM)
        .async(new PNCallback<PNGetMembersResult> () {
            @Override
            public void onResponse(PNGetMembersResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNMember> memberList = result.getData(); // requested member list
                    for (PNMember pnMember: memberList) {
                        pnMember.getCustom(); // requested via PNMemberFields.CUSTOM
                        pnMember.getUser(); // requested via PNMemberFields.USER
                        pnMember.getUser().getCustom(); // requested via PNMemberFields.USER_CUSTOM
                    }
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });
  2. void main() {
        fetchMembers(null, new FetchCallback() {
            @Override
            public void done(PNGetMembersResult result) {
                List<PNMember> members = result.getData(); // the requested members
            }
        });
    }
    
    interface FetchCallback {
    
        void done(PNGetMembersResult result);
    }
    
    /**
     * Fetches 10 members at a time, recursively and in a paged manner.
     *
     * @param next     The cursor bookmark for the next page.
     * @param callback The callback to dispatch fetched members to.
     */
    void fetchMembers(String next, FetchCallback callback) {
        GetMembers getMembersBuilder = pubnub.getMembers()
            .limit(10)
            .withTotalCount(true);
    
        if (next != null)
            getMembersBuilder.start(next);
    
        getMembersBuilder.async(new PNCallback<PNGetMembersResult> () {
            @Override
            public void onResponse(PNGetMembersResult result, PNStatus status) {
                if (!status.isError()) {
                    if (!(result.getData().isEmpty())) {
                        callback.done(result);
                        fetchMembers(result.getNext(), callback);
                    }
                }
            }
        });
    }
  3. pubnub.getMembers()
        .spaceId("space_1")
        .filter("(custom.value > 2) && (custom.description != null)")
        .async(new PNCallback<PNGetMembersResult> () {
            @Override
            public void onResponse(PNGetMembersResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNMember> memberList = result.getData();
                    // the requested members which match the criteria
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });

Manage the specified space’s member users. You can Add, Remove, and Update a space's members.

To Manage Members you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    spaceIdStringYesID of the space whose members you wish to manage (add, update or remove).
    addMember[]NoArray of members to add to the space, with optional custom data for each.
    updateMember[]NoArray of members indicating the complete list of user(s) who should belong to the space, along with optional custom data.
    removeMember[]NoArray of members to be removed from the space.
    includeFieldsPNMemberFields[]NoArray of additional/complex attributes to include in response.
    limitIntegerNoNumber of members to return in response.
    startStringNoPreviously-returned cursor bookmark for fetching the next page.
    endStringNoPreviously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.
    withTotalCountBooleanNoRequest totalCount to be included in paginated response.
    By default, totalCount is omitted.
    syncPNManageMembersResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNManageMembersResult>NoExecutes the call asynchronously.
pubnub.manageMembers()
    .spaceId("space_1")
    .add(Member.userId("user_1"))
    .async(new PNCallback<PNManageMembersResult> () {
        @Override
        public void onResponse(PNManageMembersResult result, PNStatus status) {
            if (!status.isError()) {
                List<PNMember> members = result.getData(); // list of members currently in the requested space
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }
        }
    });
The manageMembers() operation returns a PNManageMembersResult object which contains the following operations:
MethodTypeDescription
getData()List<PNMember>Returns the current member list.
getNext()StringReturns cursor bookmark for fetching the next page.
getPrev()StringReturns cursor bookmark for fetching the previous page.
getTotalCount()IntegerReturns the total count of objects without pagination.
  1. HashMap<String, Object> customMap = new HashMap<>();
    customMap.put("color", "yellow");
    customMap.put("private", true);
    customMap.put("stars", 25);
    
    pubnub.manageMembers()
        .spaceId("space_1")
        .add(Member.userId("user_1").custom(customMap)) // add custom data
        .includeFields(PNMemberFields.CUSTOM) // let's retreive it too
        .async(new PNCallback<PNManageMembersResult> () {
            @Override
            public void onResponse(PNManageMembersResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNMember> members = result.getData(); // list of members currently in the requested space
                    for (PNMember member: members) {
                        member.getCustom(); // requested via PNMemberFields.CUSTOM (if any)
                    }
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });
    HashMap<String, Object> customMap = new HashMap<>();
    customMap.put("color", "green");
    customMap.put("starred", false);
    
    pubnub.manageMembers()
        .spaceId("space_1")
        .update(Member.userId("user_1"),
                Member.userId("user_2").custom(customMap),
                Member.userId("user_3"))
        .async(new PNCallback<PNManageMembersResult> () {
            @Override
            public void onResponse(PNManageMembersResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNMember> members = result.getData(); // list of members currently in the requested space
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });
    pubnub.manageMembers()
        .spaceId("space_1")
        .remove(Member.userId("user_1"),
                Member.userId("user_2"),
                Member.userId("user_3"))
        .async(new PNCallback<PNManageMembersResult> () {
            @Override
            public void onResponse(PNManageMembersResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNMember> members = result.getData(); // list of members currently in the requested space
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });

In the Android V4 SDK, and in terms of the Objects API, a Membership is represented as an instance of PNMembership. A PNMembership can't be instantiated, as it's created indirectly in different scenarios (e.g. when getting memberships from PubNub). A PNMembership is just a wrapper around PNSpace.

MethodReturn typeDescription
getSpace()PNSpaceReturns the belonging space.
getCustom()ObjectReturns the memberships' deserializable custom data.
getCreated()StringReturns the date and time the object was created.
getUpdated()StringReturns the date and time the object was updated.
getETag()StringReturns the the object's content fingerprint used in conditional requests.

However, to manage memberships on your own and to avoid creating ad-hoc json data, a tiny helper class is available to do so: Membership. It's a easy-to-use wrapper class:

Membership membershipFoo = Membership.spaceId("foo"); // instantiates a Membership

HashMap<String, Object> customMap = new HashMap<>();
customMap.put("starred", true);
Membership membershipBar = Membership.spaceId("bar").custom(customMap); // instantiates a Membership and also sets its custom data

Get the specified user's space memberships.

To Get Memberships you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    userIdStringYesID of the user whose memberships you wish to retrieve.
    includeFieldsPNMembershipFields[]NoList of additional/complex attributes to include in response.
    limitIntegerNoNumber of memberships to return in response.
    startStringNoPreviously-returned cursor bookmark for fetching the next page.
    endStringNoPreviously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.
    withTotalCountBooleanNoRequest totalCount to be included in paginated response.
    By default, totalCount is omitted.
    filterStringNoExpression used to filter the results. Only objects whose properties satisfy the given expression are returned.
    For consistency, Objects API supports the same language as used in filter expressions for Subscribe requests.

    In addition to custom attributes, the expressions can refer to attributes on associated entities one level deep (that is, the association and its target entities).
    syncPNGetMembershipsResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNGetMembershipsResult>NoExecutes the call asynchronously.
pubnub.getMemberships()
    .userId("user_1")
    .async(new PNCallback<PNGetMembershipsResult> () {
        @Override
        public void onResponse(PNGetMembershipsResult result, PNStatus status) {
            if (!status.isError()) {
                List<PNMembership> membershipList = result.getData(); // requested membership list
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }
        }
    });
The getMemberships() operation returns a PNGetMembershipsResult object which contains the following operations:
MethodTypeDescription
getData()List<PNMembership>Returns the requested memberships list.
getNext()StringReturns cursor bookmark for fetching the next page.
getPrev()StringReturns cursor bookmark for fetching the previous page.
getTotalCount()IntegerReturns the total count of objects without pagination.
  1. pubnub.getMemberships()
        .userId("user_1")
        .includeFields(PNMembershipFields.CUSTOM, PNMembershipFields.SPACE, PNMembershipFields.SPACE_CUSTOM)
        .async(new PNCallback<PNGetMembershipsResult> () {
            @Override
            public void onResponse(PNGetMembershipsResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNMembership> membershipList = result.getData(); // requested membership list
                    for (PNMembership pnMembership: membershipList) {
                        pnMembership.getCustom(); // requested via PNMembershipFields.CUSTOM
                        pnMembership.getSpace(); // requested via PNMembershipFields.SPACE
                        pnMembership.getSpace().getCustom(); // requested via PNMembershipFields.SPACE_CUSTOM
                    }
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });
  2. void main() {
        fetchMemberships(null, new FetchCallback() {
            @Override
            public void done(PNGetMembershipsResult result) {
                List<PNMembership> memberships = result.getData(); // the requested memberships
            }
        });
    }
    
    interface FetchCallback {
    
        void done(PNGetMembershipsResult result);
    }
    
    /**
     * Fetches 10 membersips at a time, recursively and in a paged manner.
     *
     * @param next     The cursor bookmark for the next page.
     * @param callback The callback to dispatch fetched memberships to.
     */
    void fetchMemberships(String next, FetchCallback callback) {
        GetMemberships getMembershipsBuilder = pubnub.getMemberships()
            .limit(10)
            .withTotalCount(true);
    
        if (next != null)
            getMembershipsBuilder.start(next);
    
        getMembershipsBuilder.async(new PNCallback<PNGetMembershipsResult> () {
            @Override
            public void onResponse(PNGetMembershipsResult result, PNStatus status) {
                if (!status.isError()) {
                    if (!(result.getData().isEmpty())) {
                        callback.done(result);
                        fetchMemberships(result.getNext(), callback);
                    }
                }
            }
        });
    }
  3. pubnub.getMemberships()
        .userId("user_1")
        .filter("custom.migration_date >= '2020-02-02T00:00:00Z'")
        .async(new PNCallback<PNGetMembershipsResult> () {
            @Override
            public void onResponse(PNGetMembershipsResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNMembership> membershipList = result.getData();
                    // the requested memberships which match the criteria
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });

Manage the specified user's memberships. You can Add, Remove, and Update a user's memberships.

To Manage Memberships you can use the following method(s) in the Android V4 SDK:
  1. ParameterTypeRequiredDescription
    userIdStringYesID of the user whose memberships you wish to manage (add, update or remove).
    addMembership[]NoArray of objects indicating the space(s) to be joined, along with optional custom data.
    updateMembership[]NoArray of objects indicating the complete list of space(s) to which the user should belong, along with optional custom data.
    removeMembership[]NoArray of spaces from which to remove the user.
    includeFieldsPNMembershipFields[]NoArray of additional/complex attributes to include in response.
    limitIntegerNoNumber of memberships to return in response.
    startStringNoPreviously-returned cursor bookmark for fetching the next page.
    endStringNoPreviously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.
    withTotalCountBooleanNoRequest totalCount to be included in paginated response.
    By default, totalCount is omitted.
    syncPNManageMembershipsResultNoExecutes the call. Blocks the thread, exception is thrown if something goes wrong.
    asyncPNCallback<PNManageMembershipsResult>NoExecutes the call asynchronously.
pubnub.manageMemberships()
    .userId("user_1")
    .add(Membership.spaceId("space_1"))
    .async(new PNCallback<PNManageMembershipsResult> () {
        @Override
        public void onResponse(PNManageMembershipsResult result, PNStatus status) {
            if (!status.isError()) {
                List<PNMembership> memberships = result.getData(); // list of memberships currently in the requested space
            } else {
                status.getErrorData().getThrowable().printStackTrace();
            }
        }
    });
The manageMemberships() operation returns a PNManageMembershipsResult object which contains the following operations:
MethodTypeDescription
getData()List<PNMembership>Returns the current membership list.
getNext()StringReturns cursor bookmark for fetching the next page.
getPrev()StringReturns cursor bookmark for fetching the previous page.
getTotalCount()IntegerReturns the total count of objects without pagination.
  1. HashMap<String, Object> customMap = new HashMap<>();
    customMap.put("color", "yellow");
    customMap.put("private", true);
    customMap.put("stars", 25);
    
    pubnub.manageMemberships()
        .userId("user_1")
        .add(Membership.spaceId("space_1").custom(customMap))
        .includeFields(PNMembershipFields.CUSTOM) // let's retreive it too
        .async(new PNCallback<PNManageMembershipsResult> () {
            @Override
            public void onResponse(PNManageMembershipsResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNMembership> memberships = result.getData(); // list of memberships currently in the requested space
                    for (PNMembership membership: memberships) {
                        membership.getCustom(); // requested via PNMembershipFields.CUSTOM (if any)
                    }
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });
    HashMap<String, Object> customMap = new HashMap<>();
    customMap.put("color", "green");
    customMap.put("starred", false);
    
    pubnub.manageMemberships()
        .userId("user_1")
        .update(Membership.spaceId("space_1"),
                Membership.spaceId("space_2").custom(customMap),
                Membership.spaceId("space_3"))
        .async(new PNCallback<PNManageMembershipsResult> () {
            @Override
            public void onResponse(PNManageMembershipsResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNMembership> memberships = result.getData(); // list of memberships currently in the requested space
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });
    pubnub.manageMemberships()
        .userId("user_1")
        .remove(Membership.spaceId("space_1"),
                Membership.spaceId("space_2"),
                Membership.spaceId("space_3"))
        .async(new PNCallback<PNManageMembershipsResult> () {
            @Override
            public void onResponse(PNManageMembershipsResult result, PNStatus status) {
                if (!status.isError()) {
                    List<PNMembership> memberships = result.getData(); // list of memberships currently in the requested space
                } else {
                    status.getErrorData().getThrowable().printStackTrace();
                }
            }
        });