javapns.notification
Class Payload

java.lang.Object
  javapns.notification.Payload

Direct Known Subclasses:

MobileConfigPayload, NewsstandNotificationPayload, PushNotificationPayload

public abstract class Payload
extends Object

Abstract class representing a payload that can be transmitted to Apple. By default, this class has no payload content at all. Subclasses are responsible for imposing specific content based on the specifications they are intended to implement (such as the 'aps' dictionnary for APS payloads).

Author:

Sylvain Pedneault

Constructor Summary

Payload()
Construct a Payload object with a blank root JSONObject

Payload(String rawJSON)
Construct a Payload object from a JSON-formatted string

Method Summary

void	addCustomDictionary(String name, int value) Add a custom dictionnary with a int value
void	addCustomDictionary(String name, List values) Add a custom dictionnary with multiple values
void	addCustomDictionary(String name, String value) Add a custom dictionnary with a string value
Payload	asSimulationOnly() Enables a special simulation mode which causes the library to behave as usual *except* that at the precise point where the payload would actually be streamed out to Apple, it is not.
int	estimatePayloadSizeAfterAdding(String propertyName, Object propertyValue) Estimate the size that this payload will take after adding a given property.
String	getCharacterEncoding() Returns the character encoding that will be used by getPayloadAsBytes().
int	getExpiry() Return the number of seconds after which this payload should expire.
int	getMaximumPayloadSize() Return the maximum payload size in bytes.
JSONObject	getPayload() Get the actual JSON object backing this payload.
byte[]	getPayloadAsBytes() Get this payload as a byte array using the preconfigured character encoding.
int	getPayloadSize() Get the number of bytes that the payload will occupy when streamed.
boolean	isEstimatedPayloadSizeAllowedAfterAdding(String propertyName, Object propertyValue) Validate if the estimated payload size after adding a given property will be allowed.
boolean	isPayloadSizeEstimatedWhenAdding() Indicates if payload size is estimated and controlled when adding properties (default is false).
void	setCharacterEncoding(String characterEncoding) Changes the character encoding for streaming the payload.
void	setExpiry(int seconds) Set the number of seconds after which this payload should expire.
void	setPayloadSizeEstimatedWhenAdding(boolean checked) Indicate if payload size should be estimated and controlled when adding properties (default is false).
String	toString() Get the string representation

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Payload

public Payload()

Construct a Payload object with a blank root JSONObject

Payload

public Payload(String rawJSON)
        throws JSONException

Construct a Payload object from a JSON-formatted string

Parameters:

rawJSON - a JSON-formatted string (ex: {"aps":{"alert":"Hello World!"}} )

Throws:

JSONException - thrown if a exception occurs while parsing the JSON string

Method Detail

getPayload

public JSONObject getPayload()

Get the actual JSON object backing this payload.

Returns:

a JSONObject

addCustomDictionary

public void addCustomDictionary(String name,
                                String value)
                         throws JSONException

Add a custom dictionnary with a string value

Parameters:

name -

value -

Throws:

JSONException

addCustomDictionary

public void addCustomDictionary(String name,
                                int value)
                         throws JSONException

Add a custom dictionnary with a int value

Parameters:

name -

value -

Throws:

JSONException

addCustomDictionary

public void addCustomDictionary(String name,
                                List values)
                         throws JSONException

Add a custom dictionnary with multiple values

Parameters:

name -

values -

Throws:

JSONException

toString

public String toString()

Get the string representation

Overrides:

toString in class Object

getPayloadAsBytes

public byte[] getPayloadAsBytes()
                         throws Exception

Get this payload as a byte array using the preconfigured character encoding.

Returns:

byte[] bytes ready to be streamed directly to Apple servers

Throws:

Exception

getPayloadSize

public int getPayloadSize()
                   throws Exception

Get the number of bytes that the payload will occupy when streamed.

Returns:

a number of bytes

Throws:

Exception

estimatePayloadSizeAfterAdding

public int estimatePayloadSizeAfterAdding(String propertyName,
                                          Object propertyValue)

Estimate the size that this payload will take after adding a given property. For performance reasons, this estimate is not as reliable as actually adding the property and checking the payload size afterwards. Currently works well with strings and numbers.

Parameters:

propertyName - the name of the property to use for calculating the estimation

propertyValue - the value of the property to use for calculating the estimation

Returns:

an estimated payload size if the property were to be added to the payload

isEstimatedPayloadSizeAllowedAfterAdding

public boolean isEstimatedPayloadSizeAllowedAfterAdding(String propertyName,
                                                        Object propertyValue)

Validate if the estimated payload size after adding a given property will be allowed. For performance reasons, this estimate is not as reliable as actually adding the property and checking the payload size afterwards.

Parameters:

propertyName - the name of the property to use for calculating the estimation

propertyValue - the value of the property to use for calculating the estimation

Returns:

true if the payload size is not expected to exceed the maximum allowed, false if it might be too big

isPayloadSizeEstimatedWhenAdding

public boolean isPayloadSizeEstimatedWhenAdding()

Indicates if payload size is estimated and controlled when adding properties (default is false).

Returns:

true to throw an exception if the estimated size is too big when adding a property, false otherwise

setPayloadSizeEstimatedWhenAdding

public void setPayloadSizeEstimatedWhenAdding(boolean checked)

Indicate if payload size should be estimated and controlled when adding properties (default is false).

Parameters:

checked - true to throw an exception if the estimated size is too big when adding a property, false otherwise

getMaximumPayloadSize

public int getMaximumPayloadSize()

Return the maximum payload size in bytes. By default, this method returns Integer.MAX_VALUE. Subclasses should override this method to provide their own limit.

Returns:

the maximum payload size in bytes

setCharacterEncoding

public void setCharacterEncoding(String characterEncoding)

Changes the character encoding for streaming the payload. Character encoding is preset to UTF-8, as Apple documentation specifies. Therefore, unless you are working on a special project, you should leave it as is.

Parameters:

characterEncoding - a valid character encoding that String.getBytes(encoding) will accept

getCharacterEncoding

public String getCharacterEncoding()

Returns the character encoding that will be used by getPayloadAsBytes(). Default is UTF-8, as per Apple documentation.

Returns:

a character encoding

setExpiry

public void setExpiry(int seconds)

Set the number of seconds after which this payload should expire. Default is one (1) day.

Parameters:

seconds -

getExpiry

public int getExpiry()

Return the number of seconds after which this payload should expire.

Returns:

a number of seconds

asSimulationOnly

public Payload asSimulationOnly()

Enables a special simulation mode which causes the library to behave as usual *except* that at the precise point where the payload would actually be streamed out to Apple, it is not.

Returns:

the same payload