# ChannelService
Date: 2012-02-24

## com.google.appengine.api.channel
Interface ChannelService

    public interface ChannelService

`ChannelService` allows you to manage manage two-way connections with clients.

Method Summary
`java.lang.String` `createChannel(java.lang.String clientId)` Creates a channel associated with the provided `clientId` and returns a token that is valid for the default amount of time (2 hours)
`java.lang.String` `createChannel(java.lang.String clientId, int durationMinutes)` Creates a channel associated with the provided `clientId` and returns a token that is valid for the specified period of time.
`ChannelMessage` `parseMessage(HttpServletRequest request)` Parse the incoming message in `request`.
`ChannelPresence` `parsePresence(HttpServletRequest request)` Parse the incoming presence in `request`.
`void` `sendMessage(ChannelMessage message)` Sends a `ChannelMessage` to the client.

Method Detail

### createChannel

    java.lang.String createChannel(java.lang.String clientId)

  Creates a channel associated with the provided `clientId` and returns a token that is valid for the default amount of time (2 hours)

  Parameters:
    `clientId` - A string uniquely identifying the client that will use the returned token to connect to this channel. This string must be fewer than 64 bytes when encoded to UTF-8.
  Returns:
    the token the client will use to connect to this channel.
  Throws:
    `ChannelFailureException` - if there is an error encountered while communicating with the channel service.

### createChannel

    java.lang.String createChannel(java.lang.String clientId,
                                   int durationMinutes)

  Creates a channel associated with the provided `clientId` and returns a token that is valid for the specified period of time.

  Parameters:
    `clientId` - A string uniquely identifying the client that will use the returned token to connect to this channel. This string must be fewer than 64 bytes when encoded to UTF-8.
    `durationMinutes` - the amount of time for which the returned token will be valid, in minutes. Must be greater than zero and less than 24 * 60.
  Returns:
    the token the client will use to connect to this channel.
  Throws:
    `ChannelFailureException` - if there is an error encountered while communicating with the channel service.

### sendMessage

    void sendMessage(ChannelMessage message)

  Sends a `ChannelMessage` to the client.

  Parameters:
    `message` - the message to be sent to all connected clients.
  Throws:
    `ChannelFailureException` - if there is an error encountered while communicating with the channel service.

### parseMessage

    ChannelMessage parseMessage(HttpServletRequest request)

  Parse the incoming message in `request`. This method should only be called within a channel webhook.

  Parameters:
    `request` - the source HTTP request.
  Returns:
    the incoming `ChannelMessage`.
  Throws:
    `java.lang.IllegalStateException` - if the required HTTP parameters are not present.

### parsePresence

    ChannelPresence parsePresence(HttpServletRequest request)
                                  throws java.io.IOException

  Parse the incoming presence in `request`. This method should only be called within a channel presence request handler.

  Parameters:
    `request` - the source HTTP request.
  Returns:
    the incoming `ChannelPresence`.
  Throws:
    `java.io.IOException` - if the MIME body isn't parseable.
    `java.lang.IllegalArgumentException` - if the HTTP request doesn't conform to expectations.