Package com.pusher.rest

Class PusherAbstract<T>

java.lang.Object
com.pusher.rest.PusherAbstract<T>
Type Parameters:
T - The return type of the IO calls. See Pusher for the synchronous implementation, PusherAsync for the asynchronous implementation.
Direct Known Subclasses:
Pusher, PusherAsync
public abstract class PusherAbstract<T> extends Object
Parent class for Pusher clients, deals with anything that isn't IO related.

  • Field Details

  • Constructor Details

    • PusherAbstract

      public PusherAbstract(String appId, String key, String secret)
      Construct an instance of the Pusher object through which you may interact with the Pusher API.

      The parameters to use are found on your dashboard at https://app.pusher.com and are specific per App.

      Parameters:
      appId - The ID of the App you will to interact with.
      key - The App Key, the same key you give to websocket clients to identify your app when they connect to Pusher.
      secret - The App Secret. Used to sign requests to the API, this should be treated as sensitive and not distributed.

    • PusherAbstract

      public PusherAbstract(String appId, String key, String secret, String encryptionMasterKeyBase64)
      Construct an instance of the Pusher object through which you may interact with the Pusher API.

      The parameters to use are found on your dashboard at https://app.pusher.com and are specific per App.

      Parameters:
      appId - The ID of the App you will to interact with.
      key - The App Key, the same key you give to websocket clients to identify your app when they connect to Pusher.
      secret - The App Secret. Used to sign requests to the API, this should be treated as sensitive and not distributed.
      encryptionMasterKeyBase64 - 32 byte key, base64 encoded. This key, along with the channel name, are used to derive per-channel encryption keys.

    • PusherAbstract

      public PusherAbstract(String url)

  • Method Details

    • setCryptoUtil

      protected void setCryptoUtil(CryptoUtil crypto)

    • setHost

      public void setHost(String host)
      For testing or specifying an alternative cluster. See also setCluster(String) for the latter.

      Default: api.pusherapp.com

      Parameters:
      host - the API endpoint host

    • setCluster

      public void setCluster(String cluster)
      For Specifying an alternative cluster.

      See also setHost(String) for targetting an arbitrary endpoint.

      Parameters:
      cluster - the Pusher cluster to target

    • setEncrypted

      public void setEncrypted(boolean encrypted)
      Set whether to use a secure connection to the API (SSL).

      Authentication is secure even without this option, requests cannot be faked or replayed with access to their plain text, a secure connection is only required if the requests or responses contain sensitive information.

      Default: false

      Parameters:
      encrypted - whether to use SSL to contact the API

    • setGsonSerialiser

      public void setGsonSerialiser(com.google.gson.Gson gson)
      Set the Gson instance used to marshal Objects passed to trigger(List, String, Object) Set the marshaller used to serialize Objects passed to trigger(List, String, Object) and friends. By default, the library marshals the objects provided to JSON using the Gson library (see https://code.google.com/p/google-gson/ for more details). By providing an instance here, you may exert control over the marshalling, for example choosing how Java property names are mapped on to the field names in the JSON representation, allowing you to match the expected scheme on the client side. We added the setDataMarshaller(DataMarshaller) method to allow specification of other marshalling libraries. This method was kept around to maintain backwards compatibility.
      Parameters:
      gson - a GSON instance configured to your liking

    • setDataMarshaller

      public void setDataMarshaller(DataMarshaller marshaller)
      Set a custom marshaller used to serialize Objects passed to trigger(List, String, Object) and friends.

      By default, the library marshals the objects provided to JSON using the Gson library (see https://code.google.com/p/google-gson/ for more details). By providing an instance here, you may exert control over the marshalling, for example choosing how Java property names are mapped on to the field names in the JSON representation, allowing you to match the expected scheme on the client side.

      Parameters:
      marshaller - a DataMarshaller instance configured to your liking

    • serialise

      protected String serialise(Object data)
      This method provides an override point if the default Gson based serialisation is absolutely unsuitable for your use case, even with customisation of the Gson instance doing the serialisation.

      For example, in the simplest case, you might already have your data pre-serialised and simply want to elide the default serialisation: 

       Pusher pusher = new Pusher(appId, key, secret) {
     protected String serialise(final Object data) {
         return (String)data;
     }
 };

 pusher.trigger("my-channel", "my-event", "{\"my-data\":\"my-value\"}");
      Parameters:
      data - an unserialised event payload
      Returns:
      a serialised event payload

    • trigger

      public T trigger(String channel, String eventName, Object data)
      Publish a message to a single channel.

      The message data should be a POJO, which will be serialised to JSON for submission. Use setDataMarshaller(DataMarshaller) to control the serialisation

      Note that if you do not wish to create classes specifically for the purpose of specifying the message payload, use Map<String, Object>. These maps will nest just fine.

      Parameters:
      channel - the channel name on which to trigger the event
      eventName - the name given to the event
      data - an object which will be serialised to create the event body
      Returns:
      a Result object encapsulating the success state and response to the request

    • trigger

      public T trigger(List<String> channels, String eventName, Object data)
      Publish identical messages to multiple channels.
      Parameters:
      channels - the channel names on which to trigger the event
      eventName - the name given to the event
      data - an object which will be serialised to create the event body
      Returns:
      a Result object encapsulating the success state and response to the request

    • trigger

      public T trigger(String channel, String eventName, Object data, String socketId)
      Publish a message to a single channel, excluding the specified socketId from receiving the message.
      Parameters:
      channel - the channel name on which to trigger the event
      eventName - the name given to the event
      data - an object which will be serialised to create the event body
      socketId - a socket id which should be excluded from receiving the event
      Returns:
      a Result object encapsulating the success state and response to the request

    • trigger

      public T trigger(List<String> channels, String eventName, Object data, String socketId)
      Publish identical messages to multiple channels, excluding the specified socketId from receiving the message.
      Parameters:
      channels - the channel names on which to trigger the event
      eventName - the name given to the event
      data - an object which will be serialised to create the event body
      socketId - a socket id which should be excluded from receiving the event
      Returns:
      a Result object encapsulating the success state and response to the request

    • trigger

      public T trigger(List<Event> batch)
      Publish a batch of different events with a single API call.

      The batch is limited to 10 events on our multi-tenant clusters.

      Parameters:
      batch - a list of events to publish
      Returns:
      a Result object encapsulating the success state and response to the request

    • get

      public T get(String path)
      Make a generic HTTP call to the Pusher API.

      See: http://pusher.com/docs/rest_api

      NOTE: the path specified here is relative to that of your app. For example, to access the channel list for your app, simply pass "/channels". Do not include the "/apps/[appId]" at the beginning of the path.

      Parameters:
      path - the path (e.g. /channels) to query
      Returns:
      a Result object encapsulating the success state and response to the request

    • get

      public T get(String path, Map<String,String> parameters)
      Make a generic HTTP call to the Pusher API.

      See: http://pusher.com/docs/rest_api

      Parameters should be a map of query parameters for the HTTP call, and may be null if none are required.

      NOTE: the path specified here is relative to that of your app. For example, to access the channel list for your app, simply pass "/channels". Do not include the "/apps/[appId]" at the beginning of the path.

      Parameters:
      path - the path (e.g. /channels) to query
      parameters - query parameters to submit with the request
      Returns:
      a Result object encapsulating the success state and response to the request

    • doGet

      protected abstract T doGet(URI uri)

    • post

      public T post(String path, String body)
      Make a generic HTTP call to the Pusher API.

      The body should be a UTF-8 encoded String

      See: http://pusher.com/docs/rest_api

      NOTE: the path specified here is relative to that of your app. For example, to access the channel list for your app, simply pass "/channels". Do not include the "/apps/[appId]" at the beginning of the path.

      Parameters:
      path - the path (e.g. /channels) to submit
      body - the body to submit
      Returns:
      a Result object encapsulating the success state and response to the request

    • doPost

      protected abstract T doPost(URI uri, String body)

    • signedUri

      public URI signedUri(String method, String path, String body)
      If you wanted to send the HTTP API requests manually (e.g. using a different HTTP client), this method will return a java.net.URI which includes all of the appropriate query parameters which sign the request.
      Parameters:
      method - the HTTP method, e.g. GET, POST
      path - the HTTP path, e.g. /channels
      body - the HTTP request body, if there is one (otherwise pass null)
      Returns:
      a URI object which includes the necessary query params for request authentication

    • signedUri

      public URI signedUri(String method, String path, String body, Map<String,String> parameters)
      If you wanted to send the HTTP API requests manually (e.g. using a different HTTP client), this method will return a java.net.URI which includes all of the appropriate query parameters which sign the request.

      Note that any further query parameters you wish to be add must be specified here, as they form part of the signature.

      Parameters:
      method - the HTTP method, e.g. GET, POST
      path - the HTTP path, e.g. /channels
      body - the HTTP request body, if there is one (otherwise pass null)
      parameters - HTTP query parameters to be included in the request
      Returns:
      a URI object which includes the necessary query params for request authentication

    • authenticate

      public String authenticate(String socketId, String channel)
      Generate authentication response to authorise a user on a private channel

      The return value is the complete body which should be returned to a client requesting authorisation.

      Parameters:
      socketId - the socket id of the connection to authenticate
      channel - the name of the channel which the socket id should be authorised to join
      Returns:
      an authentication string, suitable for return to the requesting client

    • authenticate

      public String authenticate(String socketId, String channel, PresenceUser user)
      Generate authentication response to authorise a user on a presence channel

      The return value is the complete body which should be returned to a client requesting authorisation.

      Parameters:
      socketId - the socket id of the connection to authenticate
      channel - the name of the channel which the socket id should be authorised to join
      user - a PresenceUser object which represents the channel data to be associated with the user
      Returns:
      an authentication string, suitable for return to the requesting client

    • validateWebhookSignature

      public Validity validateWebhookSignature(String xPusherKeyHeader, String xPusherSignatureHeader, String body)
      Check the signature on a webhook received from Pusher
      Parameters:
      xPusherKeyHeader - the X-Pusher-Key header as received in the webhook request
      xPusherSignatureHeader - the X-Pusher-Signature header as received in the webhook request
      body - the webhook body
      Returns:
      enum representing the possible validities of the webhook request