com.funambol.push
Class CTPService

java.lang.Object
  extended by com.funambol.push.CTPService
All Implemented Interfaces:
java.lang.Runnable

public class CTPService
extends java.lang.Object
implements java.lang.Runnable

This class implements the CTPService. A service which opens a CTP connection and communicates with the server via the CTP protocol (see CTP design document). The service is executed in a separate thread, and it can be stopped at any time. The service uses socket connection and therefore requires network access that may result in user questions. The service is implemented by two threads plus a Timer, and all threads can be created within a thread pool. The service shall never throw any exception (even runtime ones) and on errors it is implemented to retry connecting. If too many failures occurs then the service is stopped (at the moment no notification is sent). The class performs connection and MD5 authentication on startup and if this is succesfull then the listening/heartbeat phase starts. The main thread is controlled by the following FSM: open socket socket opened DISCONNECTED ---------------> CONNECTING ----------------> CONNECTED ^ | fail | | V | --------------------------------------------- | | | | send MD5 | ok | | auth LISTENING <--- AUTHENTICATED <---------> AUTHENTICATING <-----| fail


Nested Class Summary
protected  class CTPService.ConnectionTimer
          This class is used (with a Timer) to monitor a connection and interrupt it if it hangs for more than command timeout.
protected  class CTPService.CTPMessage
          This class represents a CTP message.
protected  class CTPService.HeartbeatGenerator
          This class implements an hearbeat generator.
 
Field Summary
protected static int AUTHENTICATED
           
protected static int AUTHENTICATING
           
protected static int CM_AUTH
          Commands
protected static int CM_BYE
           
protected static int CM_READY
           
protected static int CONNECTED
           
protected static int CONNECTING
           
protected static int DISCONNECTED
          CTP server thread state
protected static int LISTENING
           
protected static int ST_ERROR
           
protected static int ST_FORBIDDEN
           
protected static int ST_JUMP
           
protected static int ST_NOT_AUTHENTICATED
           
protected static int ST_OK
          Status
protected static int ST_RETRY
           
protected static int ST_SYNC
           
protected static int ST_UNAUTHORIZED
           
protected  int state
          CTPService status
 
Constructor Summary
protected CTPService()
          Builds an empty service.
 
Method Summary
protected  int authenticate()
          This method performs the CTP authentication.
protected  void closeConnection()
          Close the connection, forcing exceptions if there are pending network IO operations.
protected  void connect(int retry)
          Perform the CTP connecting phase.
protected  void disconnect()
          Disconnect from server.
 void forceDisconnect()
          force disconnection
 PushConfig getConfig()
          make PushConfig available for CTPService clients
 java.lang.String getCTPStringState()
           
static CTPService getInstance()
          Returns the instance of the CTPService.
 int getServiceState()
           
 boolean isOfflineMode()
           
 boolean isPushActive()
          Returns true iff CTP is running and it is properly connected and authenticated to the CTP service.
 boolean isRunning()
          Returns true iff an instance of CTP is already running
protected  CTPService.CTPMessage receiveMessage()
          Receives a message from the server (wait till a message is received or an error is encountered).
protected  CTPService.CTPMessage receiveMessageWithTimeout()
          Receives a message from the server.
 void restartService()
          Restarts the service.
 void restartService(PushConfig config)
          Restarts the service.
 void run()
          This is the thread entry point.
protected  void sendMessage(CTPService.CTPMessage message)
          Sends a message to the server and monitor the operation via a timer.
 void setConfig(PushConfig config)
          set the push config
 void setCTPListener(CTPListener ctpListener)
           
 void setOfflineMode(boolean mode)
          turn offline mode on/off.
 void setPushNotificationListener(CTPNotificationListener pushListener)
          Sets the push events listener.
 void setThreadPool(ThreadPool threadPool)
          Sets the thread pool in which the CTP service will be started (has effect at the next start or restart)
 void startService()
           
 void startService(PushConfig config)
          Start the complete CTP service.
 void stopService()
          Stops the service.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CM_AUTH

protected static final int CM_AUTH
Commands

See Also:
Constant Field Values

CM_READY

protected static final int CM_READY
See Also:
Constant Field Values

CM_BYE

protected static final int CM_BYE
See Also:
Constant Field Values

ST_OK

protected static final int ST_OK
Status

See Also:
Constant Field Values

ST_JUMP

protected static final int ST_JUMP
See Also:
Constant Field Values

ST_ERROR

protected static final int ST_ERROR
See Also:
Constant Field Values

ST_NOT_AUTHENTICATED

protected static final int ST_NOT_AUTHENTICATED
See Also:
Constant Field Values

ST_UNAUTHORIZED

protected static final int ST_UNAUTHORIZED
See Also:
Constant Field Values

ST_FORBIDDEN

protected static final int ST_FORBIDDEN
See Also:
Constant Field Values

ST_SYNC

protected static final int ST_SYNC
See Also:
Constant Field Values

ST_RETRY

protected static final int ST_RETRY
See Also:
Constant Field Values

DISCONNECTED

protected static final int DISCONNECTED
CTP server thread state

See Also:
Constant Field Values

CONNECTING

protected static final int CONNECTING
See Also:
Constant Field Values

CONNECTED

protected static final int CONNECTED
See Also:
Constant Field Values

AUTHENTICATING

protected static final int AUTHENTICATING
See Also:
Constant Field Values

AUTHENTICATED

protected static final int AUTHENTICATED
See Also:
Constant Field Values

LISTENING

protected static final int LISTENING
See Also:
Constant Field Values

state

protected int state
CTPService status

Constructor Detail

CTPService

protected CTPService()
Builds an empty service. This class is a singleton, therefore the user is disallowed to create instances. @see getInstance.

Method Detail

setCTPListener

public void setCTPListener(CTPListener ctpListener)

startService

public void startService()

setOfflineMode

public void setOfflineMode(boolean mode)
turn offline mode on/off. in offline mode, ctp will close and not try to connect again. if online mode is set from false to true, ctp service is not restarted automatically.

Parameters:
mode - the new offline mode

isOfflineMode

public boolean isOfflineMode()
Returns:
true if in offline mode

getInstance

public static CTPService getInstance()
Returns the instance of the CTPService. If the service has already been created, then the existing instance is returned, otherwise a new one is created. Before starting the service it is possible to set the CTPNotificationListener and/or the ThreadPool.

Returns:
a valid CTPService instance

restartService

public void restartService(PushConfig config)
Restarts the service. This imply stopping and restarting it. The new instance will work using the new configuration

Parameters:
config - the new push configuration

restartService

public void restartService()
Restarts the service. This imply stopping and restarting it. if no config has been set, the method does nothing


startService

public void startService(PushConfig config)
Start the complete CTP service. This includes the listener and the heartbeat generator. Since this method fires a thread, the actual startService implementation is in the run method.

Parameters:
config - the Push configuration for this CTPService (cannot be null)

isRunning

public boolean isRunning()
Returns true iff an instance of CTP is already running


setConfig

public void setConfig(PushConfig config)
set the push config

Parameters:
config - the new config

isPushActive

public boolean isPushActive()
Returns true iff CTP is running and it is properly connected and authenticated to the CTP service. In other words this method return true iff push notifications can be properly received via CTP.

Returns:
true iff CTP push notifications are active

setPushNotificationListener

public void setPushNotificationListener(CTPNotificationListener pushListener)
Sets the push events listener.

Parameters:
pushListener - the listener or null to remove it.

setThreadPool

public void setThreadPool(ThreadPool threadPool)
Sets the thread pool in which the CTP service will be started (has effect at the next start or restart)

Parameters:
threadPool - the thread pool or null to disable thread pool

stopService

public void stopService()
Stops the service. If a connection is active the server is notified by sending a bye command. If IO operations are pending, they are terminated by closing the socket connection. This will result in exceptions that will resume the threads. They all will stop as the "done" flag is set to true.


run

public void run()
This is the thread entry point. This method implements the real service startup sequence. Such a sequence is described in the CTP design document. Beside performing the service startup, this method activates the heartbeat generator and if authentication is OK it invokes the listen method that waits for server messages.

Specified by:
run in interface java.lang.Runnable

getServiceState

public int getServiceState()
Returns:
current state

getCTPStringState

public java.lang.String getCTPStringState()

closeConnection

protected void closeConnection()
Close the connection, forcing exceptions if there are pending network IO operations.


connect

protected void connect(int retry)
                throws java.io.IOException
Perform the CTP connecting phase. The main purpose of the connecting phase is to open the socket and the IO streams. The server addres is retrived from the push configuration.

Parameters:
retry - the number of tentative
Throws:
java.io.IOException

disconnect

protected void disconnect()
Disconnect from server. This is not the CTP protocol disconnection, as we do not send the BYE command. It is rather a socket disconnect where we close the socket and its streams.


forceDisconnect

public void forceDisconnect()
force disconnection


getConfig

public PushConfig getConfig()
make PushConfig available for CTPService clients


authenticate

protected int authenticate()
                    throws java.io.IOException
This method performs the CTP authentication. The authentication process is described in the CTP design document. Basically we build an authentication message using the last nonce saved in the configuration. If the server authenticates us, then the method terminates, otherwise it grabs the new nonce and retry authentication. The server may responds in several different ways to the authentication request. Depending on such a response we decide if re-authenticating or aborting the authentication process.

Returns:
the last authentication status sent by the server.
Throws:
java.io.IOException

sendMessage

protected void sendMessage(CTPService.CTPMessage message)
                    throws java.io.IOException
Sends a message to the server and monitor the operation via a timer. If the operation does not terminate after the timeout, then the ConnectionTimer will reset the connection, causing the method to trap an exception that will be re-thrown.

Parameters:
message - the CTP message to be sent
Throws:
java.io.IOException - if the socket writing fails

receiveMessageWithTimeout

protected CTPService.CTPMessage receiveMessageWithTimeout()
                                                   throws java.io.IOException
Receives a message from the server. The read operation is guarded by a timeout. If nothing is received within the timeout then ConnectionTimer will reset the connection, causing the method to trap an exception that will be re-thrown.

Returns:
the CTP message received
Throws:
java.io.IOException - if the socket writing fails

receiveMessage

protected CTPService.CTPMessage receiveMessage()
                                        throws java.io.IOException
Receives a message from the server (wait till a message is received or an error is encountered).

Returns:
the CTP message received
Throws:
java.io.IOException - if the socket writing fails


Copyright © 2001-2009 Funambol.