com.google.android.gcm.server

Class Sender

java.lang.Object

com.google.android.gcm.server.Sender

public class Sender
extends java.lang.Object

Helper class to send messages to the GCM service using an API Key.

Field Summary

Fields

Modifier and Type	Field and Description
protected static int	BACKOFF_INITIAL_DELAY Initial delay before first retry, without jitter.
protected static java.util.logging.Logger	logger
protected static int	MAX_BACKOFF_DELAY Maximum delay before a retry.
protected java.util.Random	random
protected static java.lang.String	UTF8

Constructor Summary

Constructors

Constructor and Description
Sender(java.lang.String key) Default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected static void	addParameter(java.lang.StringBuilder body, java.lang.String name, java.lang.String value) Adds a new parameter to the HTTP POST body.
protected java.net.HttpURLConnection	getConnection(java.lang.String url) Gets an HttpURLConnection given an URL.
protected static java.lang.String	getString(java.io.InputStream stream) Convenience method to convert an InputStream to a String.
protected static java.lang.StringBuilder	newBody(java.lang.String name, java.lang.String value) Creates a StringBuilder to be used as the body of an HTTP POST.
protected static java.util.Map<java.lang.String,java.lang.String>	newKeyValues(java.lang.String key, java.lang.String value) Creates a map with just one key-value pair.
protected java.net.HttpURLConnection	post(java.lang.String url, java.lang.String body) Make an HTTP post to a given URL.
protected java.net.HttpURLConnection	post(java.lang.String url, java.lang.String contentType, java.lang.String body) Makes an HTTP POST request to a given endpoint.
MulticastResult	send(Message message, java.util.List<java.lang.String> regIds, int retries) Sends a message to many devices, retrying in case of unavailability.
Result	send(Message message, java.lang.String to, int retries) Sends a message to one device, retrying in case of unavailability.
MulticastResult	sendNoRetry(Message message, java.util.List<java.lang.String> registrationIds) Sends a message without retrying in case of service unavailability.
Result	sendNoRetry(Message message, java.lang.String to) Sends a message without retrying in case of service unavailability.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UTF8

protected static final java.lang.String UTF8

See Also:

Constant Field Values

BACKOFF_INITIAL_DELAY

protected static final int BACKOFF_INITIAL_DELAY

Initial delay before first retry, without jitter.

See Also:

Constant Field Values

MAX_BACKOFF_DELAY

protected static final int MAX_BACKOFF_DELAY

Maximum delay before a retry.

See Also:

Constant Field Values

random

protected final java.util.Random random

logger

protected static final java.util.logging.Logger logger

Constructor Detail

Sender

public Sender(java.lang.String key)

Default constructor.

Parameters:

key - API key obtained through the Google API Console.

Method Detail

send

public Result send(Message message,
          java.lang.String to,
          int retries)
            throws java.io.IOException

Sends a message to one device, retrying in case of unavailability.

Note: this method uses exponential back-off to retry in case of service unavailability and hence could block the calling thread for many seconds.

Parameters:

message - message to be sent, including the device's registration id.

to - registration token, notification key, or topic where the message will be sent.

retries - number of retries in case of service unavailability errors.

Returns:

result of the request (see its javadoc for more details).

Throws:

java.lang.IllegalArgumentException - if to is null.

InvalidRequestException - if GCM didn't returned a 200 or 5xx status.

java.io.IOException - if message could not be sent.

sendNoRetry

public Result sendNoRetry(Message message,
                 java.lang.String to)
                   throws java.io.IOException

Sends a message without retrying in case of service unavailability. See send(Message, String, int) for more info.

Returns:

result of the post, or null if the GCM service was unavailable or any network exception caused the request to fail, or if the response contains more than one result.

Throws:

InvalidRequestException - if GCM didn't returned a 200 status.

java.lang.IllegalArgumentException - if to is null.

java.io.IOException

send

public MulticastResult send(Message message,
                   java.util.List<java.lang.String> regIds,
                   int retries)
                     throws java.io.IOException

Sends a message to many devices, retrying in case of unavailability.

Note: this method uses exponential back-off to retry in case of service unavailability and hence could block the calling thread for many seconds.

Parameters:

message - message to be sent.

regIds - registration id of the devices that will receive the message.

retries - number of retries in case of service unavailability errors.

Returns:

combined result of all requests made.

Throws:

java.lang.IllegalArgumentException - if registrationIds is null or empty.

InvalidRequestException - if GCM didn't returned a 200 or 503 status.

java.io.IOException - if message could not be sent.

sendNoRetry

public MulticastResult sendNoRetry(Message message,
                          java.util.List<java.lang.String> registrationIds)
                            throws java.io.IOException

Sends a message without retrying in case of service unavailability. See send(Message, List, int) for more info.

Returns:

multicast results if the message was sent successfully, null if it failed but could be retried.

Throws:

java.lang.IllegalArgumentException - if registrationIds is null or empty.

InvalidRequestException - if GCM didn't returned a 200 status.

java.io.IOException - if there was a JSON parsing error

post

protected java.net.HttpURLConnection post(java.lang.String url,
                              java.lang.String body)
                                   throws java.io.IOException

Make an HTTP post to a given URL.

Returns:

HTTP response.

Throws:

java.io.IOException

post

protected java.net.HttpURLConnection post(java.lang.String url,
                              java.lang.String contentType,
                              java.lang.String body)
                                   throws java.io.IOException

Makes an HTTP POST request to a given endpoint.

Note: the returned connected should not be disconnected, otherwise it would kill persistent connections made using Keep-Alive.

Parameters:

url - endpoint to post the request.

contentType - type of request.

body - body of the request.

Returns:

the underlying connection.

Throws:

java.io.IOException - propagated from underlying methods.

newKeyValues

protected static final java.util.Map<java.lang.String,java.lang.String> newKeyValues(java.lang.String key,
                                                            java.lang.String value)

Creates a map with just one key-value pair.

newBody

protected static java.lang.StringBuilder newBody(java.lang.String name,
                              java.lang.String value)

Creates a StringBuilder to be used as the body of an HTTP POST.

Parameters:

name - initial parameter for the POST.

value - initial value for that parameter.

Returns:

StringBuilder to be used an HTTP POST body.

addParameter

protected static void addParameter(java.lang.StringBuilder body,
                java.lang.String name,
                java.lang.String value)

Adds a new parameter to the HTTP POST body.

Parameters:

body - HTTP POST body.

name - parameter's name.

value - parameter's value.

getConnection

protected java.net.HttpURLConnection getConnection(java.lang.String url)
                                            throws java.io.IOException

Gets an HttpURLConnection given an URL.

Throws:

java.io.IOException

getString

protected static java.lang.String getString(java.io.InputStream stream)
                                     throws java.io.IOException

Convenience method to convert an InputStream to a String.

If the stream ends in a newline character, it will be stripped.

If the stream is null, returns an empty string.

Throws:

java.io.IOException