application/hub/main/listener/class_BaseListener.php

   1 <?php
   2 /**
   3  * A general listener class
   4  *
   5  * @author              Roland Haeder <webmaster@ship-simu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2011 Hub Developer Team
   8  * @license             GNU GPL 3.0 or any newer version
   9  * @link                http://www.ship-simu.org
  10  *
  11  * This program is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation, either version 3 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  23  */
  24 class BaseListener extends BaseHubSystem implements Visitable {
  25         // Exception code constants
  26         const EXCEPTION_INVALID_SOCKET                   = 0xa00;
  27         const EXCEPTION_SOCKET_ALREADY_REGISTERED        = 0xa01;
  28         const EXCEPTION_SOCKET_CREATION_FAILED           = 0xa02;
  29         const EXCEPTION_NO_SOCKET_ERROR                  = 0xa03;
  30         const EXCEPTION_CONNECTION_ALREADY_REGISTERED    = 0xa04;
  31         const EXCEPTION_UNEXPECTED_PACKAGE_STATUS        = 0xa05;
  32         const EXCEPTION_UNSUPPORTED_PACKAGE_CODE_HANDLER = 0xa06;
  33
  34         /**
  35          * Used protocol (Default: invalid, which is indeed invalid...)
  36          */
  37         private $protocol = 'invalid';
  38
  39         /**
  40          * Address (IP mostly) we shall listen on
  41          */
  42         private $listenAddress = '0.0.0.0'; // This is the default and listens on all interfaces
  43
  44         /**
  45          * Port we shall listen on (or wait for incoming data)
  46          */
  47         private $listenPort = 0; // This port MUST be changed by your application
  48
  49         /**
  50          * Wether we are in blocking or non-blocking mode (default: non-blocking
  51          */
  52         private $blockingMode = false;
  53
  54         /**
  55          * A peer pool instance
  56          */
  57         private $poolInstance = NULL;
  58
  59         /**
  60          * Protected constructor
  61          *
  62          * @param       $className      Name of the class
  63          * @return      void
  64          */
  65         protected function __construct ($className) {
  66                 // Call parent constructor
  67                 parent::__construct($className);
  68         }
  69
  70         /**
  71          * Checks wether the given socket resource is a server socket
  72          *
  73          * @param       $socketResource         A valid socket resource
  74          * @return      $isServerSocket         Wether the socket resource is a server socket
  75          */
  76         protected function isServerSocketResource ($socketResource) {
  77                 // Check it
  78                 $isServerSocket = ((is_resource($socketResource)) && (!@socket_getpeername($socketResource, $peerName)));
  79
  80                 // We need to clear the error here if it is a resource
  81                 if ($isServerSocket === true) {
  82                         // Clear the error
  83                         //* DEBUG: */ $this->debugOutput('socketResource[]=' . gettype($socketResource));
  84                         socket_clear_error($socketResource);
  85                 } // END - if
  86
  87                 // Check peer name, it must be empty
  88                 $isServerSocket = (($isServerSocket) && (empty($peerName)));
  89
  90                 // Return result
  91                 return $isServerSocket;
  92         }
  93
  94         /**
  95          * Setter for listen address
  96          *
  97          * @param       $listenAddress  The address this listener should listen on
  98          * @return      void
  99          */
 100         protected final function setListenAddress ($listenAddress) {
 101                 $this->listenAddress = (string) $listenAddress;
 102         }
 103
 104         /**
 105          * Getter for listen address
 106          *
 107          * @return      $listenAddress  The address this listener should listen on
 108          */
 109         public final function getListenAddress () {
 110                 return $this->listenAddress;
 111         }
 112
 113         /**
 114          * Setter for listen port
 115          *
 116          * @param       $listenPort             The port this listener should listen on
 117          * @return      void
 118          */
 119         protected final function setListenPort ($listenPort) {
 120                 $this->listenPort = (int) $listenPort;
 121         }
 122
 123         /**
 124          * Getter for listen port
 125          *
 126          * @return      $listenPort             The port this listener should listen on
 127          */
 128         public final function getListenPort () {
 129                 return $this->listenPort;
 130         }
 131
 132         /**
 133          * Getter for port number to satify ProtocolHandler
 134          *
 135          * @return      $port   The port number
 136          */
 137         public final function getPort () {
 138                 return $this->getListenPort();
 139         }
 140
 141         /**
 142          * "Setter" to set listen address from configuration entry
 143          *
 144          * @param       $configEntry    The configuration entry holding our listen address
 145          * @return      void
 146          */
 147         public final function setListenAddressByConfiguration ($configEntry) {
 148                 $this->setListenAddress($this->getConfigInstance()->getConfigEntry($configEntry));
 149         }
 150
 151         /**
 152          * "Setter" to set listen port from configuration entry
 153          *
 154          * @param       $configEntry    The configuration entry holding our listen port
 155          * @return      void
 156          */
 157         public final function setListenPortByConfiguration ($configEntry) {
 158                 $this->setListenPort($this->getConfigInstance()->getConfigEntry($configEntry));
 159         }
 160
 161         /**
 162          * Setter for protocol
 163          *
 164          * @param       $protocol       Used protocol
 165          * @return      void
 166          */
 167         protected final function setProtocol ($protocol) {
 168                 $this->protocol = (string) $protocol;
 169         }
 170
 171         /**
 172          * Getter for protocol
 173          *
 174          * @return      $protocol       Used protocol
 175          */
 176         public final function getProtocol () {
 177                 return $this->protocol;
 178         }
 179
 180         /**
 181          * Setter for blocking-mode
 182          *
 183          * @param       $blockingMode   Wether blocking-mode is disabled (default) or enabled
 184          * @return      void
 185          */
 186         protected final function setBlockingMode ($blockingMode) {
 187                 $this->blockingMode = (boolean) $blockingMode;
 188         }
 189
 190         /**
 191          * Checks wether blocking-mode is enabled or disabled
 192          *
 193          * @return      $blockingMode   Wether blocking mode is disabled or enabled
 194          */
 195         public final function isBlockingModeEnabled () {
 196                 return $this->blockingMode;
 197         }
 198
 199         /**
 200          * Setter for peer pool instance
 201          *
 202          * @param       $poolInstance   The peer pool instance we shall set
 203          * @return      void
 204          */
 205         protected final function setPoolInstance (PoolablePeer $poolInstance) {
 206                 $this->poolInstance = $poolInstance;
 207         }
 208
 209         /**
 210          * Getter for peer pool instance
 211          *
 212          * @return      $poolInstance   The peer pool instance we shall set
 213          */
 214         public final function getPoolInstance () {
 215                 return $this->poolInstance;
 216         }
 217
 218         /**
 219          * Registeres the given socket resource for "this" listener instance. This
 220          * will be done in a seperate class to allow package writers to use it
 221          * again.
 222          *
 223          * @param       $socketResource         A valid server socket resource
 224          * @return      void
 225          * @throws      InvalidServerSocketException            If the given resource is no server socket
 226          * @throws      SocketAlreadyRegisteredException        If the given resource is already registered
 227          */
 228         protected function registerServerSocketResource ($socketResource) {
 229                 // First check if it is valid
 230                 if (!$this->isServerSocketResource($socketResource)) {
 231                         // No server socket
 232                         throw new InvalidServerSocketException(array($this, $socketResource), self::EXCEPTION_INVALID_SOCKET);
 233                 } elseif ($this->isServerSocketRegistered($socketResource)) {
 234                         // Already registered
 235                         throw new SocketAlreadyRegisteredException($this, self::EXCEPTION_SOCKET_ALREADY_REGISTERED);
 236                 }
 237
 238                 // Get a socket registry instance (singleton)
 239                 $registryInstance = SocketRegistryFactory::createSocketRegistryInstance();
 240
 241                 // Register the socket
 242                 $registryInstance->registerSocket($this, $socketResource);
 243         }
 244
 245         /**
 246          * Checks wether given socket resource is registered in socket registry
 247          *
 248          * @param       $socketResource         A valid server socket resource
 249          * @return      $isRegistered           Wether given server socket is registered
 250          */
 251         protected function isServerSocketRegistered ($socketResource) {
 252                 // Get a socket registry instance (singleton)
 253                 $registryInstance = SocketRegistryFactory::createSocketRegistryInstance();
 254
 255                 // Check it
 256                 $isRegistered = $registryInstance->isSocketRegistered($this, $socketResource);
 257
 258                 // Return result
 259                 return $isRegistered;
 260         }
 261
 262         /**
 263          * Getter for "this" socket resource
 264          *
 265          * @return      $socketResource         A valid socket resource
 266          */
 267         public final function getSocketResource () {
 268                 // Get a socket registry instance (singleton)
 269                 $registryInstance = SocketRegistryFactory::createSocketRegistryInstance();
 270
 271                 // Get the socket resource
 272                 $socketResource = $registryInstance->getRegisteredSocketResource($this);
 273
 274                 // Return it
 275                 return $socketResource;
 276         }
 277
 278         /**
 279          * Accepts the visitor to process the visit "request"
 280          *
 281          * @param       $visitorInstance        An instance of a Visitor class
 282          * @return      void
 283          */
 284         public function accept (Visitor $visitorInstance) {
 285                 // Debug message
 286                 //* DEBUG: */ $this->debugOutput(strtoupper($this->getProtocol()) . '-LISTENER: ' . $visitorInstance->__toString() . ' has visited ' . $this->__toString() . ' - START');
 287
 288                 // Visit this listener
 289                 $visitorInstance->visitListener($this);
 290
 291                 // Visit the pool if set
 292                 if ($this->getPoolInstance() instanceof Poolable) {
 293                         $this->getPoolInstance()->accept($visitorInstance);
 294                 } // END - if
 295
 296                 // Debug message
 297                 //* DEBUG: */ $this->debugOutput(strtoupper($this->getProtocol()) . '-LISTENER: ' . $visitorInstance->__toString() . ' has visited ' . $this->__toString() . ' - FINISHED');
 298         }
 299
 300         /**
 301          * Monitors incoming raw data from the handler and transfers it to the
 302          * given receiver instance. This method should not be called, please call
 303          * the decorator's version instead to separator node/client traffic.
 304          *
 305          * @param       $receiverInstance       An instance of a Receivable class
 306          * @return      void
 307          * @throws      UnsupportedOperatorException    If this method is called by a mistake
 308          */
 309         public function monitorIncomingRawData (Receivable $receiverInstance) {
 310                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $receiverInstance), self::EXCEPTION_UNSPPORTED_OPERATION);
 311         }
 312 }
 313
 314 // [EOF]
 315 ?>