Package com.kii.cloud.storage
Class KiiPushSubscription
- java.lang.Object
-
- com.kii.cloud.storage.KiiPushSubscription
-
public class KiiPushSubscription extends java.lang.Object
This class is responsible for the subscription of push notification. Three types of push message supported by KiiCloud.- Push to App : Message sent to the subscribers when an event happens in the KiiBucket.
- Push to User : Message sent to the subscribers of topic that is created explicitly.
Following section describes the contents of both event based and explicit push message.
- Direct Push: Message sent to the app user directly by the app admin
Subscription is not required to receive this type of push.
Contents of Push to App Message
Each Push to App message contains the following information:- appID: Source app which generated the notification.
- sender: The user who caused the notification.
- when: Timestamp of the notification.
- origin: Origin of the message. "EVENT" in this case.
- Type of notification
- DATA_OBJECT_CREATED New file/object has created.
- DATA_OBJECT_DELETED A file/object has deleted.
- DATA_OBJECT_UPDATED File-metadata/object-data has updated.
- DATA_OBJECT_BODY_UPDATED File/object body has updated.
- DATA_OBJECT_BODY_DELETED File/object body has deleted.
- DATA_OBJECT_ACL_MODIFIED ACL of file/object has modified.
- objectScopeAppID : App ID of bucket.
- objectScopeUserID : User ID of bucket owner. Push message has this field only if the subscribed bucket is user scoped.
- objectScopeGroupID : ID of the group that the subscribed bucket belongs to. Push message has this field only if the subscribed bucket is group scoped.
- objectScopeType: Scope of bucket.
- APP : Event triggered in app scope bucket.
- APP_AND_USER : Event triggered in user scope bucket.
- APP_AND_GROUP : Event triggered in group scope bucket.
- Collapse Key: Same as bucketID. When the device is offline, and there is already message in gcm server with same collapse key and registration id, old message is collapsed by new message and deliver when the device connects.(i.e. Push message triggered by event occurred in same bucket will be collapsed and only the latest message will be delivered.)
- bucketID: Bucket name of push subscribed.
- objectID: ID of the object operated.
- modifiedAt: Timestamp of the modification of object in milliseconds (Since January 1, 1970 00:00:00 UTC)
Contents of Push to User Message
Push to User message contains the basic message as key-value pair that is sent to the topic and KiiCloud specific fields.KiiUser who send the message to the topic can configure KiiCloud specific fields byKiiPushMessage
. Push message only contains the KiiCloud specific fields that are selected by the message sender.KiiCloud specific fields are as follows:- appID: Source app which generated the notification.
- sender: The user send message to the topic.
- origin: Origin of the message. "EXPLICIT" in this case.
- topic: Topic name in which the message is sent.
- when: Timestamp of the notification.
- objectScopeAppID : App ID of topic.
- objectScopeUserID : ID of the user who own the topic.
- objectScopeGroupID : ID of the group that own the topic. Push message has this field only if the subscribed topic is group scoped.
- objectScopeType: Scope of topic.
- APP : App scope topic.
- APP_AND_USER : Group scope topic.
- APP_AND_GROUP : User scope topic.
- Collapse Key: When the device is offline, and there is already message in gcm server with same collapse key and registration id, old message is collapsed by new message and deliver when the device connects.(i.e. All undelivered topic message will be collapsed and only the latest message will be delivered.)
Contents of Direct Push
Direct push message contains the basic message as key-value pair that is sent to the user directly by app admin. In addition, configuration is necessary to set the following fields.- sender: originator of the push message.
- origin: Origin of the message. "EXPLICIT" in this case.
- when: Timestamp of the notification.
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
isSubscribed(KiiSubscribable target)
Checks whether the target is already subscribed by current user or not.int
isSubscribed(KiiSubscribable target, KiiPushCallBack callback)
Asynchronous call ofisSubscribed(KiiSubscribable)
Background task will be initiated to execute the task.void
subscribe(KiiSubscribable target)
Subscribe push notification of the target.int
subscribe(KiiSubscribable target, KiiPushCallBack callback)
Asynchronous call ofsubscribe(KiiSubscribable)
Background task will be initiated to execute the task.void
subscribeBucket(KiiBucket bucket)
Subscribe current login user with the provided bucket for the push message.int
subscribeBucket(KiiBucket bucket, KiiPushCallBack callback)
Asynchronous call forsubscribeBucket(KiiBucket)
.void
unsubscribe(KiiSubscribable target)
Unsubscribe push notification of the target.int
unsubscribe(KiiSubscribable target, KiiPushCallBack callback)
Asynchronous call ofunsubscribe(KiiSubscribable)
Background task will be initiated to execute the task.void
unsubscribeBucket(KiiBucket bucket)
Unsubscribe the bucket for the push message.int
unsubscribeBucket(KiiBucket bucket, KiiPushCallBack callback)
Asynchronous call forunsubscribeBucket(KiiBucket)
.
-
-
-
Method Detail
-
subscribeBucket
@WorkerThread public void subscribeBucket(@NonNull KiiBucket bucket) throws java.io.IOException, BadRequestException, UnauthorizedException, ForbiddenException, ConflictException, NotFoundException, UndefinedException
Subscribe current login user with the provided bucket for the push message. When subscribe, it will receive push message if any one event(refer to the "Type" of push message contents inKiiPushSubscription
) happen in the bucket.
NOTE: This api access to server. Should not be executed in UI/Main thread.- Parameters:
bucket
- KiiBucket which is going to be subscribe.- Throws:
java.lang.IllegalArgumentException
- If bucket is null.java.lang.IllegalStateException
- SDK has not initialized or No user logged in.java.io.IOException
- If network related error has happened.UndefinedException
NotFoundException
ForbiddenException
ConflictException
BadRequestException
UnauthorizedException
-
subscribeBucket
public int subscribeBucket(@NonNull KiiBucket bucket, @NonNull KiiPushCallBack callback)
Asynchronous call forsubscribeBucket(KiiBucket)
. A background task will be initiated to execute the task.- Parameters:
bucket
- KiiBucket which is going to be subscribe.callback
- Notifies event.- Returns:
- unique ID which is used to identify this async Task.
-
unsubscribeBucket
@WorkerThread public void unsubscribeBucket(@NonNull KiiBucket bucket) throws java.io.IOException, BadRequestException, UnauthorizedException, ForbiddenException, ConflictException, NotFoundException, UndefinedException
Unsubscribe the bucket for the push message.
NOTE: This api access to server. Should not be executed in UI/Main thread.- Parameters:
bucket
- KiiBucket which is going to unsubscribe.- Throws:
java.lang.IllegalArgumentException
- If bucket is null.java.lang.IllegalStateException
- SDK has not initialized or No user logged in.java.io.IOException
- If network related error has happened.UndefinedException
NotFoundException
ForbiddenException
ConflictException
BadRequestException
UnauthorizedException
-
unsubscribeBucket
public int unsubscribeBucket(@NonNull KiiBucket bucket, @NonNull KiiPushCallBack callback)
Asynchronous call forunsubscribeBucket(KiiBucket)
. A background task will be initiated to execute the task.- Parameters:
bucket
- KiiBucket which is going to be unsubscribe.callback
- Notifies event.- Returns:
- unique ID which is used to identify this async Task.
-
subscribe
@WorkerThread public void subscribe(@NonNull KiiSubscribable target) throws BadRequestException, UnauthorizedException, ForbiddenException, ConflictException, NotFoundException, UndefinedException, java.io.IOException
Subscribe push notification of the target. If the target is instance ofKiiBucket
, same as callingsubscribeBucket(KiiBucket)
.
If the target is instance ofKiiTopic
, push message would be delivered to the logged in user when message has posted on the topic.
NOTE: This api access to server. Should not be executed in UI/Main thread.- Parameters:
target
- to be subscribed.- Throws:
BadRequestException
UnauthorizedException
- when not granted to subscribe.ForbiddenException
- when not granted to subscribe.ConflictException
- when already subscribed to this.NotFoundException
- target of subscription not found.UndefinedException
java.io.IOException
java.lang.IllegalArgumentException
- when target is null.java.lang.IllegalStateException
- when no user logged in.
-
subscribe
public int subscribe(@NonNull KiiSubscribable target, @NonNull KiiPushCallBack callback)
Asynchronous call ofsubscribe(KiiSubscribable)
Background task will be initiated to execute the task.- Parameters:
target
- to be subscribedcallback
- notifies event- Returns:
- id of this task. Can be used to cancel this operation by
Kii.cancelTask(int)
-
unsubscribe
@WorkerThread public void unsubscribe(@NonNull KiiSubscribable target) throws BadRequestException, UnauthorizedException, ForbiddenException, ConflictException, NotFoundException, UndefinedException, java.io.IOException
Unsubscribe push notification of the target. If the target is instance ofKiiBucket
, same as callingunsubscribeBucket(KiiBucket)
NOTE: This api access to server. Should not be executed in UI/Main thread.- Parameters:
target
- to be unsubscribed- Throws:
java.io.IOException
UndefinedException
NotFoundException
- not exist or already unsubscribed.ConflictException
ForbiddenException
UnauthorizedException
BadRequestException
java.lang.IllegalArgumentException
- when target is null.java.lang.IllegalStateException
- when no user logged in.
-
unsubscribe
public int unsubscribe(@NonNull KiiSubscribable target, @NonNull KiiPushCallBack callback)
Asynchronous call ofunsubscribe(KiiSubscribable)
Background task will be initiated to execute the task.- Parameters:
target
- to be unsubscribed.callback
- notifies event.- Returns:
- id of this task. Can be used to cancel this operation by
Kii.cancelTask(int)
-
isSubscribed
@WorkerThread public boolean isSubscribed(@NonNull KiiSubscribable target) throws BadRequestException, UnauthorizedException, ForbiddenException, ConflictException, NotFoundException, UndefinedException, java.io.IOException
Checks whether the target is already subscribed by current user or not.
NOTE: This api access to server. Should not be executed in UI/Main thread.- Parameters:
target
- to be checked for subscription existence.- Returns:
- true if the target is subscribed, otherwise false.
- Throws:
BadRequestException
UnauthorizedException
- when not granted to subscribe.ForbiddenException
- when not granted to subscribe.ConflictException
- when already subscribed to this.NotFoundException
- target not exists in the cloud. For example, if the target is topic and this API is called for a topic which is not exists in the cloud, NotFoundException is thrown.If the topic itself exists in the cloud but subscription is not found, it returns false.UndefinedException
java.io.IOException
java.lang.IllegalArgumentException
- when target is null.java.lang.IllegalStateException
- when no user logged in.
-
isSubscribed
public int isSubscribed(@NonNull KiiSubscribable target, @NonNull KiiPushCallBack callback)
Asynchronous call ofisSubscribed(KiiSubscribable)
Background task will be initiated to execute the task.- Parameters:
target
- to be subscribedcallback
- notifies event- Returns:
- id of this task. Can be used to cancel this operation by
Kii.cancelTask(int)
-
-