com.google.android.gcm.server
Class Sender

java.lang.Object
  extended by 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
protected static int BACKOFF_INITIAL_DELAY
          Initial delay before first retry, without jitter.
protected  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
Sender(java.lang.String key)
          Default constructor.
 
Method Summary
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)
           
 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 registrationId, 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 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 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 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 registrationId,
                   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.
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:
java.lang.IllegalArgumentException - if registrationId is null.
InvalidRequestException - if GCM didn't returned a 200 or 503 status.
java.io.IOException - if message could not be sent.

sendNoRetry

public Result sendNoRetry(Message message,
                          java.lang.String registrationId)
                   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.
Throws:
InvalidRequestException - if GCM didn't returned a 200 or 503 status.
java.lang.IllegalArgumentException - if registrationId 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:
true if the message was sent successfully, false 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 message could not be sent or received.

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
Throws:
java.io.IOException

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