com.google.android.gcm.server

Class Sender

java.lang.Object

com.google.android.gcm.server.Sender

public class Sender
extends 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 Logger	logger
protected static int	MAX_BACKOFF_DELAY Maximum delay before a retry.
protected Random	random
protected static String	UTF8

Constructor Summary

Constructors

Constructor and Description
Sender(String key) Default constructor.

Method Summary

Methods

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

logger

protected final Logger logger

Constructor Detail

Sender

public Sender(String key)

Default constructor.

Parameters:

key - API key obtained through the Google API Console.

Method Detail

send

public Result send(Message message,
          String registrationId,
          int retries)
            throws 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.

registrationId - device 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:

IllegalArgumentException - if registrationId is null.

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

IOException - if message could not be sent.

sendNoRetry

public Result sendNoRetry(Message message,
                 String registrationId)
                   throws 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.

Throws:

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

IllegalArgumentException - if registrationId is null.

IOException

send

public MulticastResult send(Message message,
                   List<String> regIds,
                   int retries)
                     throws 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:

IllegalArgumentException - if registrationIds is null or empty.

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

IOException - if message could not be sent.

sendNoRetry

public MulticastResult sendNoRetry(Message message,
                          List<String> registrationIds)
                            throws IOException

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

Returns:

true if the message was sent successfully, false if it failed but could be retried.

Throws:

IllegalArgumentException - if registrationIds is null or empty.

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

IOException - if message could not be sent or received.

post

protected HttpURLConnection post(String url,
                     String body)
                          throws IOException

Make an HTTP post to a given URL.

Returns:

HTTP response.

Throws:

IOException

post

protected HttpURLConnection post(String url,
                     String contentType,
                     String body)
                          throws IOException

Throws:

IOException

newKeyValues

protected static final Map<String,String> newKeyValues(String key,
                              String value)

Creates a map with just one key-value pair.

newBody

protected static StringBuilder newBody(String name,
                    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(StringBuilder body,
                String name,
                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 HttpURLConnection getConnection(String url)
                                   throws IOException

Gets an HttpURLConnection given an URL.

Throws:

IOException

getString

protected static String getString(InputStream stream)
                           throws IOException

Convenience method to convert an InputStream to a String.

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

Throws:

IOException