net.rim.pushsdk.subscription.web
Class SubscriptionServlet

java.lang.Object
  extended by javax.servlet.GenericServlet
      extended by javax.servlet.http.HttpServlet
          extended by net.rim.pushsdk.subscription.web.SubscriptionServlet
All Implemented Interfaces:
Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig
Direct Known Subclasses:
ResumeServlet, SubscribeServlet, SuspendServlet, UnsubscribeServlet

public abstract class SubscriptionServlet
extends javax.servlet.http.HttpServlet

Subscription servlet base class with abstract methods that must be implemented to perform a subscription operation.

Author:
mdandrea
See Also:
Serialized Form

Field Summary
protected static String CACHE_CONTROL
          The Cache-Control HTTP header name.
protected  ContentProviderAuthenticationService contentProviderAuthenticationService
          An instance of a ContentProviderAuthenticationService implementation.
protected static String NO_CACHE
          The no-cache HTTP header value.
protected static String PRAGMA
          The pragma HTTP header name.
protected static String SUBSCRIBER_USERNAME
          The "name" HTTP header name.
protected  SubscriptionRequestParser subscriptionRequestParser
          An instance of a SubscriptionRequestParser implementation.
protected  SubscriptionService subscriptionService
          An instance of a SubscriptionService implementation.
 
Constructor Summary
SubscriptionServlet()
           
 
Method Summary
protected  void addAuthenticationCredentials(javax.servlet.http.HttpServletResponse resp, SubscriberPrincipal subscriberPrincipal)
          Adds authentication credentials from the subscriber principal to the HTTP response in the form of headers.
protected  String authenticateSubscriber(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, SubscriptionType subType)
          Authenticates a subscriber by:
For container-managed authentication, extract the name (subscriber id) from the user principal stored in the request.
protected  SubscriberPrincipal authenticateSubscriber(javax.servlet.http.HttpServletResponse resp, AuthenticationRequest authenticationRequest)
          Authenticates a subscriber by calling the content provider's authenticateSubscriber(BaseAuthenticationRequest) method.
protected  void checkEncoding(javax.servlet.http.HttpServletRequest req)
          Checks the character encoding of the HTTP request.
 void doGet(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Delegates to doPost().
 void doPost(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          Accepts and processes a subscription request by:
Checking the character encoding of the request by calling the checkEncoding method. Performing authentication of the subscriber by calling the authenticateSubscriber(HttpServletRequest, HttpServletResponse, SubscriptionType) method. Extracting the details from the HTTP request by calling the getRequest method. Performing the subscription operation by calling the performSubscriptionOperation method.
protected  AuthenticationRequest getAuthenticationRequest(javax.servlet.http.HttpServletRequest req, SubscriptionType subscriptionType)
          Gets the authentication request by parsing it out from the HTTP request and setting its subscription type.
abstract  BaseRequest getRequest(javax.servlet.http.HttpServletRequest req)
          Returns the subscription operation details parsed out of the HTTP request.
abstract  SubscriptionType getSubscriptionType()
          Returns the type of subscription operation being performed.
 void init()
          Initializes the subscription servlet by loading an instance of the SubscriptionRequestParser, SubscriptionService, and setContentProviderAuthenticationService from the spring context.
abstract  void performSubscriptionOperation(BaseRequest baseRequest, javax.servlet.http.HttpServletResponse resp)
          Performs the subscription operation.
protected  void setContentProviderAuthenticationService(ContentProviderAuthenticationService contentProviderAuthenticationService)
          Sets the instance of setContentProviderAuthenticationService to use.
protected  void setResponse(javax.servlet.http.HttpServletResponse resp, SubscriptionStatusCode statusCode)
          Sets the specified status code into the HTTP response.
protected  void setSubscriptionRequestParser(SubscriptionRequestParser subscriptionRequestParser)
          Sets the instance of SubscriptionRequestParser to use.
protected  void setSubscriptionService(SubscriptionService subscriptionService)
          Sets the instance of SubscriptionService to use.
 
Methods inherited from class javax.servlet.http.HttpServlet
doDelete, doHead, doOptions, doPut, doTrace, getLastModified, service, service
 
Methods inherited from class javax.servlet.GenericServlet
destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PRAGMA

protected static final String PRAGMA
The pragma HTTP header name.

See Also:
Constant Field Values

CACHE_CONTROL

protected static final String CACHE_CONTROL
The Cache-Control HTTP header name.

See Also:
Constant Field Values

NO_CACHE

protected static final String NO_CACHE
The no-cache HTTP header value.

See Also:
Constant Field Values

SUBSCRIBER_USERNAME

protected static final String SUBSCRIBER_USERNAME
The "name" HTTP header name.

See Also:
Constant Field Values

subscriptionRequestParser

protected SubscriptionRequestParser subscriptionRequestParser
An instance of a SubscriptionRequestParser implementation.


contentProviderAuthenticationService

protected ContentProviderAuthenticationService contentProviderAuthenticationService
An instance of a ContentProviderAuthenticationService implementation.


subscriptionService

protected SubscriptionService subscriptionService
An instance of a SubscriptionService implementation.

Constructor Detail

SubscriptionServlet

public SubscriptionServlet()
Method Detail

setSubscriptionRequestParser

protected void setSubscriptionRequestParser(SubscriptionRequestParser subscriptionRequestParser)
Sets the instance of SubscriptionRequestParser to use.

Parameters:
pushApplicationService - an instance of SubscriptionRequestParser

setSubscriptionService

protected void setSubscriptionService(SubscriptionService subscriptionService)
Sets the instance of SubscriptionService to use.

Parameters:
pushApplicationService - an instance of SubscriptionService

setContentProviderAuthenticationService

protected void setContentProviderAuthenticationService(ContentProviderAuthenticationService contentProviderAuthenticationService)
Sets the instance of setContentProviderAuthenticationService to use.

Parameters:
pushApplicationService - an instance of setContentProviderAuthenticationService

init

public void init()
          throws javax.servlet.ServletException
Initializes the subscription servlet by loading an instance of the SubscriptionRequestParser, SubscriptionService, and setContentProviderAuthenticationService from the spring context.

Overrides:
init in class javax.servlet.GenericServlet
Throws:
javax.servlet.ServletException

getSubscriptionType

public abstract SubscriptionType getSubscriptionType()
Returns the type of subscription operation being performed.

Returns:
the subscription type

getRequest

public abstract BaseRequest getRequest(javax.servlet.http.HttpServletRequest req)
Returns the subscription operation details parsed out of the HTTP request.

Parameters:
req - the HTTP request
Returns:
the subscription operation request details

performSubscriptionOperation

public abstract void performSubscriptionOperation(BaseRequest baseRequest,
                                                  javax.servlet.http.HttpServletResponse resp)
                                           throws IOException
Performs the subscription operation.

Parameters:
baseRequest - the subscription operation request details
resp - the HTTP response
Throws:
IOException - if any IO errors occurred

doPost

public void doPost(javax.servlet.http.HttpServletRequest req,
                   javax.servlet.http.HttpServletResponse resp)
            throws javax.servlet.ServletException,
                   IOException
Accepts and processes a subscription request by:
  1. Checking the character encoding of the request by calling the checkEncoding method.
  2. Performing authentication of the subscriber by calling the authenticateSubscriber(HttpServletRequest, HttpServletResponse, SubscriptionType) method.
  3. Extracting the details from the HTTP request by calling the getRequest method.
  4. Performing the subscription operation by calling the performSubscriptionOperation method.

Overrides:
doPost in class javax.servlet.http.HttpServlet
Parameters:
req - the request sent by the client to the server
resp - the response sent by the server to the client
Throws:
javax.servlet.ServletException - if an error occurred
IOException - if any IO errors occurred

doGet

public void doGet(javax.servlet.http.HttpServletRequest request,
                  javax.servlet.http.HttpServletResponse response)
           throws javax.servlet.ServletException,
                  IOException
Delegates to doPost().

Overrides:
doGet in class javax.servlet.http.HttpServlet
Parameters:
request - the request sent by the client to the server
response - the response sent by the server to the client
Throws:
javax.servlet.ServletException - if an error occurred
IOException - if any IO errors occurred

checkEncoding

protected void checkEncoding(javax.servlet.http.HttpServletRequest req)
                      throws UnsupportedEncodingException
Checks the character encoding of the HTTP request. If no encoding was specified, uses the default character set.

Parameters:
req - the HTTP request
Throws:
UnsupportedEncodingException - if the default character set is unsupported

authenticateSubscriber

protected String authenticateSubscriber(javax.servlet.http.HttpServletRequest req,
                                        javax.servlet.http.HttpServletResponse resp,
                                        SubscriptionType subType)
                                 throws IOException
Authenticates a subscriber by:
  1. For container-managed authentication, extract the name (subscriber id) from the user principal stored in the request. OR
  2. For non-container managed authentication, call the authenticateSubscriber(HttpServletResponse, AuthenticationRequest) method and extract the name (subscriber id) from the subscriber principal returned.

Parameters:
req - the HTTP request
resp - the HTTP response
subType - the subscription operation type
Returns:
the subscriber id or null if there were errors during the authentication or problems extracting the name from the principal; if null, the information will be logged and the appropriate error code will be set into the HTTP response
Throws:
IOException - if any IO errors occur

authenticateSubscriber

protected SubscriberPrincipal authenticateSubscriber(javax.servlet.http.HttpServletResponse resp,
                                                     AuthenticationRequest authenticationRequest)
                                              throws IOException
Authenticates a subscriber by calling the content provider's authenticateSubscriber(BaseAuthenticationRequest) method.

If the authentication was successful, the authentication credentials from the subscriber principal are added to the HTTP response.

If the authentication failed, the SubscriptionStatusCodes.SUBSCRIBER_AUTHENTICATION_FAILED error code is set into the HTTP response, and null is returned.

If authentication fields that were required were missing from the request, then the SubscriptionStatusCodes.INVALID_USERNAME error code is set into the HTTP response for a missing username, the SubscriptionStatusCodes.INVALID_PASSWORD error code is set into the HTTP response for a missing password, or the SubscriptionStatusCodes.INVALID_PUSH_APPLICATION error code is set into the HTTP response for a missing app id. In these cases, null will be returned by this method.

If any other errors were encountered while trying to authenticate, a generic SubscriptionStatusCodes.SYSTEM_ERROR error code is set into the HTTP response, and null is returned. The logs should be checked to determine the exact extraction error.

Parameters:
resp - the HTTP response to be set (authentication credentials are added on a success, an error return code is added on an authentication failure)
authenticationRequest - the subscriber's details (e.g. username, password) needed to authenticate
Returns:
the subscriber principal retrieved from the authentication process or null if there were errors during authentication
Throws:
IOException - if there were errors trying to write the return code to the HTTP response
See Also:
ContentProviderAuthenticationService

getAuthenticationRequest

protected AuthenticationRequest getAuthenticationRequest(javax.servlet.http.HttpServletRequest req,
                                                         SubscriptionType subscriptionType)
Gets the authentication request by parsing it out from the HTTP request and setting its subscription type.

Parameters:
req - the HTTP request to parse the authentication request from
subscriptionType - the subscription operation type associated with this request
Returns:
the parsed out authentication request

addAuthenticationCredentials

protected void addAuthenticationCredentials(javax.servlet.http.HttpServletResponse resp,
                                            SubscriberPrincipal subscriberPrincipal)
Adds authentication credentials from the subscriber principal to the HTTP response in the form of headers. A header is added with a header name of "name" and a value of the subscriber principal's name. Individual headers are also added for each of the key-value pairs from the subscriber principal's properties.

Parameters:
resp - the HTTP response to add the credentials to
subscriberPrincipal - the subscriber principal with the authentication credentials

setResponse

protected void setResponse(javax.servlet.http.HttpServletResponse resp,
                           SubscriptionStatusCode statusCode)
                    throws IOException
Sets the specified status code into the HTTP response. Also, sets the response to no caching (i.e. the Pragma and Cache-Control headers are set to no-cache) and the content type to plain text. The response is by default encoded to be UTF-8.

Parameters:
resp - the HTTP response to be set
statusCode - code the status code of a subscription operation
Throws:
IOException - if there were errors trying to write the return code to the HTTP response


Copyright © 2011 Research In Motion. All Rights Reserved.