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