public class

Sender

extends Object
java.lang.Object
   ↳ com.google.android.gcm.server.Sender

Class Overview

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

Summary

Constants
int BACKOFF_INITIAL_DELAY Initial delay before first retry, without jitter.
int MAX_BACKOFF_DELAY Maximum delay before a retry.
String UTF8
Fields
protected static final Logger logger
protected final Random random
Public Constructors
Sender(String key)
Default constructor.
Public Methods
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.
Result sendNoRetry(Message message, String registrationId)
Sends a message without retrying in case of service unavailability.
MulticastResult sendNoRetry(Message message, List<String> registrationIds)
Sends a message without retrying in case of service unavailability.
Protected Methods
static void addParameter(StringBuilder body, String name, String value)
Adds a new parameter to the HTTP POST body.
HttpURLConnection getConnection(String url)
Gets an HttpURLConnection given an URL.
static String getString(InputStream stream)
Convenience method to convert an InputStream to a String.
static StringBuilder newBody(String name, String value)
Creates a StringBuilder to be used as the body of an HTTP POST.
final static Map<String, String> newKeyValues(String key, String value)
Creates a map with just one key-value pair.
HttpURLConnection post(String url, String contentType, String body)
Makes an HTTP POST request to a given endpoint.
HttpURLConnection post(String url, String body)
Make an HTTP post to a given URL.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

protected static final int BACKOFF_INITIAL_DELAY

Initial delay before first retry, without jitter.

Constant Value: 1000 (0x000003e8)

protected static final int MAX_BACKOFF_DELAY

Maximum delay before a retry.

Constant Value: 1024000 (0x000fa000)

protected static final String UTF8

Constant Value: "UTF-8"

Fields

protected static final Logger logger

protected final Random random

Public Constructors

public Sender (String key)

Default constructor.

Parameters
key API key obtained through the Google API Console.

Public Methods

public MulticastResult send (Message message, List<String> regIds, int retries)

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.

public Result send (Message message, String registrationId, int retries)

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 5xx status.
IOException if message could not be sent.

public Result sendNoRetry (Message message, String registrationId)

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.
Throws
InvalidRequestException if GCM didn't returned a 200 or 5xx status.
IllegalArgumentException if registrationId is null.
IOException

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

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
IllegalArgumentException if registrationIds is null or empty.
InvalidRequestException if GCM didn't returned a 200 status.
IOException if there was a JSON parsing error

Protected Methods

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.

protected HttpURLConnection getConnection (String url)

Gets an HttpURLConnection given an URL.

Throws
IOException

protected static String getString (InputStream stream)

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
IOException

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.

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

Creates a map with just one key-value pair.

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

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
IOException propagated from underlying methods.

protected HttpURLConnection post (String url, String body)

Make an HTTP post to a given URL.

Returns
  • HTTP response.
Throws
IOException