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
  30         /**
  31          * Used protocol (Default: invalid, which is indeed invalid...)
  32          */
  33         private $protocol = 'invalid';
  34
  35         /**
  36          * Address (IP mostly) we shall listen on
  37          */
  38         private $listenAddress = '0.0.0.0'; // This is the default and listens on all interfaces
  39
  40         /**
  41          * Port we shall listen on (or wait for incoming data)
  42          */
  43         private $listenPort = 0; // This port MUST be changed by your application
  44
  45         /**
  46          * Wether we are in blocking or non-blocking mode (default: non-blocking
  47          */
  48         private $blockingMode = false;
  49
  50         /**
  51          * A peer pool instance
  52          */
  53         private $poolInstance = NULL;
  54
  55         /**
  56          * Protected constructor
  57          *
  58          * @param       $className      Name of the class
  59          * @return      void
  60          */
  61         protected function __construct ($className) {
  62                 // Call parent constructor
  63                 parent::__construct($className);
  64         }
  65
  66         /**
  67          * Checks wether the given socket resource is a server socket
  68          *
  69          * @param       $socketResource         A valid socket resource
  70          * @return      $isServerSocket         Wether the socket resource is a server socket
  71          */
  72         protected function isServerSocketResource ($socketResource) {
  73                 // Check it
  74                 $isServerSocket = ((is_resource($socketResource)) && (!@socket_getpeername($socketResource, $peerName)));
  75
  76                 // We need to clear the error here if it is a resource
  77                 if ($isServerSocket === true) {
  78                         // Clear the error
  79                         //* DEBUG: */ $this->debugOutput('socketResource[]=' . gettype($socketResource));
  80                         socket_clear_error($socketResource);
  81                 } // END - if
  82
  83                 // Check peer name, it must be empty
  84                 $isServerSocket = (($isServerSocket) && (empty($peerName)));
  85
  86                 // Return result
  87                 return $isServerSocket;
  88         }
  89
  90         /**
  91          * Setter for listen address
  92          *
  93          * @param       $listenAddress  The address this listener should listen on
  94          * @return      void
  95          */
  96         protected final function setListenAddress ($listenAddress) {
  97                 $this->listenAddress = (string) $listenAddress;
  98         }
  99
 100         /**
 101          * Getter for listen address
 102          *
 103          * @return      $listenAddress  The address this listener should listen on
 104          */
 105         public final function getListenAddress () {
 106                 return $this->listenAddress;
 107         }
 108
 109         /**
 110          * Setter for listen port
 111          *
 112          * @param       $listenPort             The port this listener should listen on
 113          * @return      void
 114          */
 115         protected final function setListenPort ($listenPort) {
 116                 $this->listenPort = (int) $listenPort;
 117         }
 118
 119         /**
 120          * Getter for listen port
 121          *
 122          * @return      $listenPort             The port this listener should listen on
 123          */
 124         public final function getListenPort () {
 125                 return $this->listenPort;
 126         }
 127
 128         /**
 129          * Getter for port number to satify ProtocolHandler
 130          *
 131          * @return      $port   The port number
 132          */
 133         public final function getPort () {
 134                 return $this->getListenPort();
 135         }
 136
 137         /**
 138          * "Setter" to set listen address from configuration entry
 139          *
 140          * @param       $configEntry    The configuration entry holding our listen address
 141          * @return      void
 142          */
 143         public final function setListenAddressByConfiguration ($configEntry) {
 144                 $this->setListenAddress($this->getConfigInstance()->getConfigEntry($configEntry));
 145         }
 146
 147         /**
 148          * "Setter" to set listen port from configuration entry
 149          *
 150          * @param       $configEntry    The configuration entry holding our listen port
 151          * @return      void
 152          */
 153         public final function setListenPortByConfiguration ($configEntry) {
 154                 $this->setListenPort($this->getConfigInstance()->getConfigEntry($configEntry));
 155         }
 156
 157         /**
 158          * Setter for protocol
 159          *
 160          * @param       $protocol       Used protocol
 161          * @return      void
 162          */
 163         protected final function setProtocol ($protocol) {
 164                 $this->protocol = (string) $protocol;
 165         }
 166
 167         /**
 168          * Getter for protocol
 169          *
 170          * @return      $protocol       Used protocol
 171          */
 172         public final function getProtocol () {
 173                 return $this->protocol;
 174         }
 175
 176         /**
 177          * Setter for blocking-mode
 178          *
 179          * @param       $blockingMode   Wether blocking-mode is disabled (default) or enabled
 180          * @return      void
 181          */
 182         protected final function setBlockingMode ($blockingMode) {
 183                 $this->blockingMode = (boolean) $blockingMode;
 184         }
 185
 186         /**
 187          * Checks wether blocking-mode is enabled or disabled
 188          *
 189          * @return      $blockingMode   Wether blocking mode is disabled or enabled
 190          */
 191         public final function isBlockingModeEnabled () {
 192                 return $this->blockingMode;
 193         }
 194
 195         /**
 196          * Setter for peer pool instance
 197          *
 198          * @param       $poolInstance   The peer pool instance we shall set
 199          * @return      void
 200          */
 201         protected final function setPoolInstance (PoolablePeer $poolInstance) {
 202                 $this->poolInstance = $poolInstance;
 203         }
 204
 205         /**
 206          * Getter for peer pool instance
 207          *
 208          * @return      $poolInstance   The peer pool instance we shall set
 209          */
 210         public final function getPoolInstance () {
 211                 return $this->poolInstance;
 212         }
 213
 214         /**
 215          * Registeres the given socket resource for "this" listener instance. This
 216          * will be done in a seperate class to allow package writers to use it
 217          * again.
 218          *
 219          * @param       $socketResource         A valid server socket resource
 220          * @return      void
 221          * @throws      InvalidServerSocketException            If the given resource is no server socket
 222          * @throws      SocketAlreadyRegisteredException        If the given resource is already registered
 223          */
 224         protected function registerServerSocketResource ($socketResource) {
 225                 // First check if it is valid
 226                 if (!$this->isServerSocketResource($socketResource)) {
 227                         // No server socket
 228                         throw new InvalidServerSocketException(array($this, $socketResource), self::EXCEPTION_INVALID_SOCKET);
 229                 } elseif ($this->isServerSocketRegistered($socketResource)) {
 230                         // Already registered
 231                         throw new SocketAlreadyRegisteredException($this, self::EXCEPTION_SOCKET_ALREADY_REGISTERED);
 232                 }
 233
 234                 // Get a socket registry instance (singleton)
 235                 $registryInstance = SocketRegistryFactory::createSocketRegistryInstance();
 236
 237                 // Register the socket
 238                 $registryInstance->registerSocket($this, $socketResource);
 239         }
 240
 241         /**
 242          * Checks wether given socket resource is registered in socket registry
 243          *
 244          * @param       $socketResource         A valid server socket resource
 245          * @return      $isRegistered           Wether given server socket is registered
 246          */
 247         protected function isServerSocketRegistered ($socketResource) {
 248                 // Get a socket registry instance (singleton)
 249                 $registryInstance = SocketRegistryFactory::createSocketRegistryInstance();
 250
 251                 // Check it
 252                 $isRegistered = $registryInstance->isSocketRegistered($this, $socketResource);
 253
 254                 // Return result
 255                 return $isRegistered;
 256         }
 257
 258         /**
 259          * Getter for "this" socket resource
 260          *
 261          * @return      $socketResource         A valid socket resource
 262          */
 263         public final function getSocketResource () {
 264                 // Get a socket registry instance (singleton)
 265                 $registryInstance = SocketRegistryFactory::createSocketRegistryInstance();
 266
 267                 // Get the socket resource
 268                 $socketResource = $registryInstance->getRegisteredSocketResource($this);
 269
 270                 // Return it
 271                 return $socketResource;
 272         }
 273
 274         /**
 275          * Accepts the visitor to process the visit "request"
 276          *
 277          * @param       $visitorInstance        An instance of a Visitor class
 278          * @return      void
 279          */
 280         public function accept (Visitor $visitorInstance) {
 281                 // Debug message
 282                 //* DEBUG: */ $this->debugOutput(strtoupper($this->getProtocol()) . '-LISTENER: ' . $visitorInstance->__toString() . ' has visited ' . $this->__toString() . ' - START');
 283
 284                 // Visit this listener
 285                 $visitorInstance->visitListener($this);
 286
 287                 // Visit the pool if set
 288                 if ($this->getPoolInstance() instanceof Poolable) {
 289                         $this->getPoolInstance()->accept($visitorInstance);
 290                 } // END - if
 291
 292                 // Debug message
 293                 //* DEBUG: */ $this->debugOutput(strtoupper($this->getProtocol()) . '-LISTENER: ' . $visitorInstance->__toString() . ' has visited ' . $this->__toString() . ' - FINISHED');
 294         }
 295
 296         /**
 297          * Monitors incoming raw data from the handler and transfers it to the
 298          * given receiver instance. This method should not be called, please call
 299          * the decorator's version instead to seperator node/client traffic.
 300          *
 301          * @param       $receiverInstance       An instance of a Receivable class
 302          * @return      void
 303          * @throws      UnsupportedOperatorException    If this method is called by a mistake
 304          */
 305         public function monitorIncomingRawData (Receivable $receiverInstance) {
 306                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $receiverInstance), self::EXCEPTION_UNSPPORTED_OPERATION);
 307         }
 308 }
 309
 310 // [EOF]
 311 ?>