Merge branch 'feature/loadbalancer' into develop

examples/7.1-plugin-loadbalancer.php

+<?php
+require('init.php');
+
+htmlHeader();
+
+// create a client instance and get loadbalancer plugin instance
+$client = new Solarium_Client($config);
+$loadbalancer = $client->getPlugin('loadbalancer');
+
+// apply loadbalancer settings
+$optionsSolrOne = array('host' => '127.0.0.1', 'port' => 8983);
+$optionsSolrTwo = array('host' => '127.0.0.1', 'port' => 7574);
+$loadbalancer->addServer('solr1', $optionsSolrOne, 100);
+$loadbalancer->addServer('solr2', $optionsSolrTwo, 200);
+$loadbalancer->addServer('solr3', $optionsSolrTwo, 1);
+
+// create a basic query to execute
+$query = $client->createSelect();
+
+// execute the query multiple times, displaying the server for each execution
+for($i=1; $i<=8; $i++) {
+    $resultset = $client->select($query);
+    echo 'Query execution #' . $i . '<br/>';
+    echo 'NumFound: ' . $resultset->getNumFound(). '<br/>';
+    echo 'Server: ' . $loadbalancer->getLastServerKey() .'<hr/>';
+}
+
+// force a server for a query (normally solr 3 is extremely unlikely based on it's weight)
+$loadbalancer->setForcedServerForNextQuery('solr3');
+$resultset = $client->select($query);
+echo 'Query execution with server forced to solr3<br/>';
+echo 'NumFound: ' . $resultset->getNumFound(). '<br/>';
+echo 'Server: ' . $loadbalancer->getLastServerKey() .'<hr/>';
+
+// test a ping query
+$query = $client->createPing();
+$client->ping($query);
+echo 'Loadbalanced ping query, should display a loadbalancing server:<br/>';
+echo 'Ping server: ' . $loadbalancer->getLastServerKey() .'<hr/>';
+
+// exclude ping query from loadbalancing
+$loadbalancer->addBlockedQueryType(Solarium_Client::QUERYTYPE_PING);
+$client->ping($query);
+echo 'Non-loadbalanced ping query, should not display a loadbalancing server:<br/>';
+echo 'Ping server: ' . $loadbalancer->getLastServerKey() .'<hr/>';
+
+htmlFooter();
\ No newline at end of file

examples/index.html

@@ -110,6 +110,11 @@
                 <li><a href="6.3-placeholder-syntax.php">6.3 Placeholder syntax</a></li>
             </ul>
 
+            <li>7. Plugins</li>
+            <ul style="list-style:none;">
+                <li><a href="7.1-plugin-loadbalancer.php">7.1 Loadbalancer</a></li>
+            </ul>
+
         </ul>
     </body>
 </html>
\ No newline at end of file

library/Solarium/Client.php

@@ -134,12 +134,21 @@ class Solarium_Client extends Solarium_Configurable
         ),
     );
 
+    /**
+     * Plugin types
+     *
+     * @var array
+     */
+    protected $_pluginTypes = array(
+        'loadbalancer' => 'Solarium_Plugin_Loadbalancer',
+    );
+
     /**
      * Registered plugin instances
      *
      * @var array
      */
-    protected $_plugins = array();
+    protected $_pluginInstances = array();
 
     /**
      * Adapter instance
@@ -329,7 +338,7 @@ class Solarium_Client extends Solarium_Configurable
 
         $plugin->init($this, $options);
 
-        $this->_plugins[$key] = $plugin;
+        $this->_pluginInstances[$key] = $plugin;
 
         return $this;
     }
@@ -363,19 +372,27 @@ class Solarium_Client extends Solarium_Configurable
      */
     public function getPlugins()
     {
-        return $this->_plugins;
+        return $this->_pluginInstances;
     }
 
     /**
      * Get a plugin instance
      *
      * @param string $key
+     * @param boolean $autocreate
      * @return Solarium_Plugin_Abstract|null
      */
-    public function getPlugin($key)
+    public function getPlugin($key, $autocreate = true)
     {
-        if (isset($this->_plugins[$key])) {
-            return $this->_plugins[$key];
+        if (isset($this->_pluginInstances[$key])) {
+            return $this->_pluginInstances[$key];
+        } elseif ($autocreate) {
+            if (array_key_exists($key, $this->_pluginTypes)) {
+                $this->registerPlugin($key, $this->_pluginTypes[$key]);
+                return $this->_pluginInstances[$key];
+            } else {
+                throw new Solarium_Exception('Cannot autoload plugin of unknown type: ' . $key);
+            }
         } else {
             return null;
         }
@@ -392,20 +409,43 @@ class Solarium_Client extends Solarium_Configurable
     public function removePlugin($plugin)
     {
         if (is_object($plugin)) {
-            foreach ($this->_plugins as $key => $instance) {
+            foreach ($this->_pluginInstances as $key => $instance) {
                 if ($instance === $plugin) {
-                    unset($this->_plugins[$key]);
+                    unset($this->_pluginInstances[$key]);
                     break;
                 }
             }
         } else {
-            if (isset($this->_plugins[$plugin])) {
-                unset($this->_plugins[$plugin]);
+            if (isset($this->_pluginInstances[$plugin])) {
+                unset($this->_pluginInstances[$plugin]);
             }
         }
         return $this;
     }
 
+    /**
+     * Trigger external events for plugins
+     *
+     * This methods adds 'namespacing' to the event name to prevent conflicts with Solariums internal event keys.
+     *
+     * Based on the event name you can always tell if an event was internal (Solarium base classes)
+     * or external (plugins, even if it's a plugin included with Solarium).
+     *
+     * External events always have the 'event' prefix in the event name.
+     *
+     * @param string $event
+     * @param array $params
+     * @param bool $resultOverride
+     * @return void|mixed
+     */
+    public function triggerEvent($event, $params, $resultOverride = false)
+    {
+        // Add namespacing
+        $event = 'event'.$event;
+
+        return $this->_callPlugins($event, $params, $resultOverride);
+    }
+
     /**
      * Forward events to plugins
      *
@@ -416,7 +456,8 @@ class Solarium_Client extends Solarium_Configurable
      */
     protected function _callPlugins($event, $params, $resultOverride = false)
     {
-        foreach ($this->_plugins AS $plugin) {
+        foreach ($this->_pluginInstances AS $plugin) {
+            if (method_exists($plugin, $event)) {
                 $result = call_user_func_array(array($plugin, $event), $params);
 
                 if ($result !== null && $resultOverride) {
@@ -424,6 +465,7 @@ class Solarium_Client extends Solarium_Configurable
                 }
             }
         }
+    }
 
     /**
      * Creates a request based on a query instance
@@ -501,9 +543,11 @@ class Solarium_Client extends Solarium_Configurable
     public function executeRequest($request)
     {
         $pluginResult = $this->_callPlugins('preExecuteRequest', array($request), true);
-        if($pluginResult !== null) return $pluginResult;
-
+        if ($pluginResult !== null) {
+            $response = $pluginResult; //a plugin result overrules the standard execution result
+        } else {
             $response = $this->getAdapter()->execute($request);
+        }
 
         $this->_callPlugins('postExecuteRequest', array($request, $response));
 

library/Solarium/Client/Adapter.php

@@ -150,7 +150,7 @@ abstract class Solarium_Client_Adapter extends Solarium_Configurable
     /**
      * Get path option
      *
-     * @return void
+     * @return string
      */
     public function getPath()
     {
@@ -215,7 +215,7 @@ abstract class Solarium_Client_Adapter extends Solarium_Configurable
      *
      * Based on host, path, port and core options.
      *
-     * @return void
+     * @return string
      */
     public function getBaseUri()
     {

library/Solarium/Plugin/Loadbalancer.php

+<?php
+/**
+ * Copyright 2011 Bas de Nooijer. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this listof conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are
+ * those of the authors and should not be interpreted as representing official
+ * policies, either expressed or implied, of the copyright holder.
+ *
+ * @copyright Copyright 2011 Bas de Nooijer <solarium@raspberry.nl>
+ * @license http://github.com/basdenooijer/solarium/raw/master/COPYING
+ * @link http://www.solarium-project.org/
+ *
+ * @package Solarium
+ */
+
+/**
+ * Loadbalancer plugin
+ *
+ * Using this plugin you can use software loadbalancing over multiple Solr instances.
+ * You can add any number of servers, each with their own weight. The weight influences
+ * the probability of a server being used for a query.
+ *
+ * By default all queries except updates are loadbalanced. This can be customized by setting blocked querytypes.
+ * Any querytype that may not be loadbalanced will be executed by Solarium with the default adapter settings.
+ * In a master-slave setup the default adapter should be connecting to the master server.
+ *
+ * You can also enable the failover mode. In this case a query will be retried on another server in case of error.
+ *
+ * @package Solarium
+ * @subpackage Plugin
+ */
+class Solarium_Plugin_Loadbalancer extends Solarium_Plugin_Abstract
+{
+
+    /**
+     * Default options
+     *
+     * @var array
+     */
+    protected $_options = array(
+        'failoverenabled' => false,
+        'failovermaxretries' => 1,
+    );
+
+    /**
+     * Registered servers
+     *
+     * @var array
+     */
+    protected $_servers = array();
+
+    /**
+     * Query types that are blocked from loadbalancing
+     *
+     * @var array
+     */
+    protected $_blockedQueryTypes = array(
+        Solarium_Client::QUERYTYPE_UPDATE => true
+    );
+
+    /**
+     * Key of the last used server
+     *
+     * The value can be null if no queries have been executed, or if the last executed query didn't use loadbalancing.
+     *
+     * @var null|string
+     */
+    protected $_lastServerKey;
+
+    /**
+     * Server to use for next query (overrules randomizer)
+     *
+     * @var string
+     */
+    protected $_nextServer;
+
+    /**
+     * Presets of the client adapter
+     *
+     * These settings are used to restore the adapter to it's original status for queries
+     * that cannot be loadbalanced (for instance update queries that need to go to the master)
+     *
+     * @var array
+     */
+    protected $_adapterPresets;
+
+    /**
+     * Pool of servers to use for requests
+     *
+     * @var Solarium_Plugin_Loadbalancer_WeightedRandomChoice
+     */
+    protected $_randomizer;
+
+    /**
+     * Query type
+     *
+     * @var string
+     */
+    protected $_queryType;
+
+    /**
+     * Used for failover mechanism
+     *
+     * @var array
+     */
+    protected $_serverExcludes;
+
+    /**
+     * Initialize options
+     *
+     * Several options need some extra checks or setup work, for these options
+     * the setters are called.
+     *
+     * @return void
+     */
+    protected function _init()
+    {
+        foreach ($this->_options AS $name => $value) {
+            switch ($name) {
+                case 'server':
+                    $this->setServers($value);
+                    break;
+                case 'blockedquerytype':
+                    $this->setBlockedQueryTypes($value);
+                    break;
+            }
+        }
+    }
+
+    /**
+     * Set failover enabled option
+     *
+     * @param bool $value
+     * @return self Provides fluent interface
+     */
+    public function setFailoverEnabled($value)
+    {
+        return $this->_setOption('failoverenabled', $value);
+    }
+
+    /**
+     * Get failoverenabled option
+     *
+     * @return boolean
+     */
+    public function getFailoverEnabled()
+    {
+        return $this->getOption('failoverenabled');
+    }
+
+    /**
+     * Set failover max retries
+     *
+     * @param int $value
+     * @return self Provides fluent interface
+     */
+    public function setFailoverMaxRetries($value)
+    {
+        return $this->_setOption('failovermaxretries', $value);
+    }
+
+    /**
+     * Get failovermaxretries option
+     *
+     * @return int
+     */
+    public function getFailoverMaxRetries()
+    {
+        return $this->getOption('failovermaxretries');
+    }
+
+    /**
+     * Add a server to the loadbalacing 'pool'
+     *
+     * @param string $key
+     * @param array $options
+     * @param int $weight Must be a positive number
+     * @return self Provides fluent interface
+     */
+    public function addServer($key, $options, $weight = 1) {
+        if (array_key_exists($key, $this->_servers)) {
+            throw new Solarium_Exception('A server for the loadbalancer plugin must have a unique key');
+        } else {
+            $this->_servers[$key] = array(
+                'options' => $options,
+                'weight' => $weight,
+            );
+        }
+
+        // reset the randomizer as soon as a new server is added
+        $this->_randomizer = null;
+
+        return $this;
+    }
+
+    /**
+     * Get servers in the loadbalancing pool
+     *
+     * @return array
+     */
+    public function getServers()
+    {
+        return $this->_servers;
+    }
+
+    /**
+     * Get a server entry by key
+     *
+     * @param string $key
+     * @return array
+     */
+    public function getServer($key)
+    {
+        if (!isset($this->_servers[$key])) {
+            throw new Solarium_Exception('Unknown server key');
+        }
+
+        return $this->_servers[$key];
+    }
+
+    /**
+     * Set servers, overwriting any existing servers
+     *
+     * @param array $servers Use server key as array key and 'options' and 'weight' as array entries
+     * @return self Provides fluent interface
+     */
+    public function setServers($servers)
+    {
+        $this->clearServers();
+        $this->addServers($servers);
+        return $this;
+    }
+
+    /**
+     * Add multiple servers
+     *
+     * @param array $servers
+     * @return self Provides fluent interface
+     */
+    public function addServers($servers)
+    {
+        foreach ($servers AS $key => $data) {
+            $this->addServer($key, $data['options'], $data['weight']);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Clear all server entries
+     *
+     * @return self Provides fluent interface
+     */
+    public function clearServers()
+    {
+        $this->_servers = array();
+    }
+
+    /**
+     * Remove a server by key
+     *
+     * @param string $key
+     * @return self Provides fluent interface
+     */
+    public function removeServer($key)
+    {
+        if (isset($this->_servers[$key])) {
+            unset($this->_servers[$key]);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Set a forced server (by key) for the next request
+     *
+     * As soon as one query has used the forced server this setting is reset. If you want to remove this setting
+     * pass NULL as the key value.
+     *
+     * If the next query cannot be loadbalanced (for instance based on the querytype) this setting is ignored
+     * but will still be reset.
+     *
+     * @param string|null $key
+     * @return self Provides fluent interface
+     */
+    public function setForcedServerForNextQuery($key)
+    {
+        if ($key !== null && !array_key_exists($key, $this->_servers)) {
+            throw new Solarium_Exception('Unknown server forced for next query');
+        }
+
+        $this->_nextServer = $key;
+        return $this;
+    }
+
+    /**
+     * Get the ForcedServerForNextQuery value
+     *
+     * @return string|null
+     */
+    public function getForcedServerForNextQuery()
+    {
+        return $this->_nextServer;
+    }
+
+    /**
+     * Get an array of blocked querytypes
+     *
+     * @return array
+     */
+    public function getBlockedQueryTypes() {
+        return array_keys($this->_blockedQueryTypes);
+    }
+
+    /**
+     * Set querytypes to block from loadbalancing
+     *
+     * Overwrites any existing types
+     *
+     * @param array $types Use an array with the constants defined in Solarium_Client as values
+     * @return self Provides fluent interface
+     */
+    public function setBlockedQueryTypes($types) {
+        $this->clearBlockedQueryTypes();
+        $this->addBlockedQueryTypes($types);
+        return $this;
+    }
+
+    /**
+     * Add a querytype to block from loadbalancing
+     *
+     * @param string $type Use one of the constants defined in Solarium_Client
+     * @return self Provides fluent interface
+     */
+    public function addBlockedQueryType($type) {
+        if (!array_key_exists($type, $this->_blockedQueryTypes)) {
+            $this->_blockedQueryTypes[$type] = true;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Add querytypes to block from loadbalancing
+     *
+     * Appended to any existing types
+     *
+     * @param array $types Use an array with the constants defined in Solarium_Client as values
+     * @return self Provides fluent interface
+     */
+    public function addBlockedQueryTypes($types) {
+        foreach ($types AS $type) {
+            $this->addBlockedQueryType($type);
+        }
+    }
+
+    /**
+     * Remove a single querytype from the block list
+     *
+     * @param string $type
+     * @return void
+     */
+    public function removeBlockedQueryType($type) {
+        if (array_key_exists($type, $this->_blockedQueryTypes)) {
+            unset($this->_blockedQueryTypes[$type]);
+        }
+    }
+
+    /**
+     * Clear all blocked querytypes
+     *
+     * @return self Provides fluent interface
+     */
+    public function clearBlockedQueryTypes() {
+        $this->_blockedQueryTypes = array();
+    }
+
+    /**
+     * Get the key of the server that was used for the last query
+     *
+     * May return a null value if no query has been executed yet, or the last query could not be loadbalanced.
+     *
+     * @return null|string
+     */
+    public function getLastServerKey()
+    {
+        return $this->_lastServerKey;
+    }
+
+    /**
+     * Event hook to capture querytype
+     *
+     * @param Solarium_Query $query
+     * @return void
+     */
+    public function preCreateRequest($query)
+    {
+        $this->_queryType = $query->getType();
+    }
+
+    /**
+     * Event hook to adjust client settings just before query execution
+     *
+     * @param Solarium_Client_Request $request
+     * @return Solarium_Client_Response
+     */
+    public function preExecuteRequest($request)
+    {
+        $adapter = $this->_client->getAdapter();
+
+        // save adapter presets (once) to allow the settings to be restored later
+        if ($this->_adapterPresets == null) {
+            $this->_adapterPresets = array(
+                'host'    => $adapter->getHost(),
+                'port'    => $adapter->getPort(),
+                'path'    => $adapter->getPath(),
+                'core'    => $adapter->getCore(),
+                'timeout' => $adapter->getTimeout(),
+            );
+        }
+
+        // check querytype: is loadbalancing allowed?
+        if (!array_key_exists($this->_queryType, $this->_blockedQueryTypes)) {
+            return  $this->_getLoadbalancedResponse($request);
+        } else {
+            $options = $this->_adapterPresets;
+            $this->_lastServerKey = null;
+
+            // apply new settings to adapter
+            $adapter->setOptions($options);
+
+            // execute request and return result
+            return $adapter->execute($request);
+        }
+    }
+
+    /**
+     * Execute a request using the adapter
+     *
+     * @param Solarium_Client_Request $request
+     * @return Solarium_Client_Response $response
+     */
+    protected function _getLoadbalancedResponse($request) {
+
+        $this->_serverExcludes = array(); // reset for each query
+        $adapter = $this->_client->getAdapter();
+
+        if ($this->getFailoverEnabled() == true) {
+
+            $e = new Solarium_Exception('Maximum number of loadbalancer retries reached');
+
+            for($i=0; $i<=$this->getFailoverMaxRetries(); $i++) {
+                $options = $this->_getRandomServerOptions();
+                $adapter->setOptions($options);
+                try {
+                    return $adapter->execute($request);
+                } catch(Solarium_Client_HttpException $e) {
+                    // ignore HTTP errors and try again
+                    // but do issue an event for things like logging
+                    $this->_client->triggerEvent('LoadbalancerServerFail', array($options, $e));
+                }
+            }
+
+            // if we get here no more retries available, throw exception
+            throw $e;
+
+        } else {
+            // no failover retries, just execute and let an exception bubble upwards
+            $options = $this->_getRandomServerOptions();
+            $adapter->setOptions($options);
+            return $adapter->execute($request);
+        }
+    }
+
+    /**
+     * Get options array for a randomized server
+     *
+     * @return array
+     */
+    protected function _getRandomServerOptions()
+    {
+        // determine the server to use
+        if ($this->_nextServer !== null) {
+            $serverKey = $this->_nextServer;
+            // reset forced server directly after use
+            $this->_nextServer = null;
+        } else {
+            $serverKey = $this->_getRandomizer()->getRandom($this->_serverExcludes);
+        }
+
+        $this->_serverExcludes[] = $serverKey;
+        $this->_lastServerKey = $serverKey;
+        return $this->_servers[$serverKey]['options'];
+    }
+
+    /**
+     * Get randomizer instance
+     *
+     * @return Solarium_Plugin_Loadbalancer_WeightedRandomChoice
+     */
+    protected function _getRandomizer()
+    {
+        if ($this->_randomizer === null) {
+            $choices = array();
+            foreach($this->_servers AS $key => $settings) {
+                $choices[$key] = $settings['weight'];
+            }
+            $this->_randomizer = new Solarium_Plugin_Loadbalancer_WeightedRandomChoice($choices);
+        }
+
+        return $this->_randomizer;
+    }
+
+}
\ No newline at end of file

library/Solarium/Plugin/Loadbalancer/WeightedRandomChoice.php

+<?php
+/**
+ * Copyright 2011 Bas de Nooijer. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this listof conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are
+ * those of the authors and should not be interpreted as representing official
+ * policies, either expressed or implied, of the copyright holder.
+ *
+ * @copyright Copyright 2011 Bas de Nooijer <solarium@raspberry.nl>
+ * @license http://github.com/basdenooijer/solarium/raw/master/COPYING
+ * @link http://www.solarium-project.org/
+ *
+ * @package Solarium
+ */
+
+/**
+ * Weighted random choice class
+ *
+ * For use in the loadbalancer plugin
+ *
+ * @package Solarium
+ * @subpackage Plugin
+ */
+class Solarium_Plugin_Loadbalancer_WeightedRandomChoice
+{
+
+    /**
+     * Total weight of all choices
+     *
+     * @var int
+     */
+    protected $_totalWeight = 0;
+
+    /**
+     * Choices total lookup array
+     *
+     * @var array
+     */
+    protected $_lookup = array();
+
+    /**
+     * Values lookup array
+     *
+     * @var array
+     */
+    protected $_values = array();
+
+    /**
+     * Constructor
+     *
+     * @param array $choices
+     */
+    public function __construct($choices)
+    {
+        $i = 0;
+        foreach($choices AS $key => $weight) {
+            if ($weight <= 0) throw new Solarium_Exception('Weight must be greater than zero');
+
+            $this->_totalWeight += $weight;
+            $this->_lookup[$i] = $this->_totalWeight;
+            $this->_values[$i] = $key;
+
+            $i++;
+        }
+    }
+
+    /**
+     * Get a (weighted) random entry
+     *
+     * @param array $excludes Keys to exclude
+     * @return string
+     */
+    public function getRandom($excludes = array())
+    {
+        if (count($excludes) == count($this->_values)) {
+            throw new Solarium_Exception('No more server entries available');
+        }
+
+        // continue until a non-excluded value is found
+        // @todo optimize?
+        while(1) {
+            $result = $this->_values[$this->_getKey()];
+            if(!in_array($result, $excludes)) return $result;
+        }
+    }
+
+    /**
+     * Get a (weighted) random entry key
+     *
+     * @return int
+     */
+    protected function _getKey()
+    {
+	    $random = mt_rand(1, $this->_totalWeight);
+        $high = count($this->_lookup)-1;
+        $low = 0;
+
+        while ( $low < $high ) {
+            $probe = (int)(($high + $low) / 2);
+            if ($this->_lookup[$probe] < $random) {
+                $low = $probe + 1;
+            } else if ($this->_lookup[$probe] > $random) {
+                $high = $probe - 1;
+            } else {
+                return $probe;
+            }
+        }
+
+        if ( $low != $high ) {
+            return $random;
+        } else {
+            if ($this->_lookup[$low] >= $random) {
+                return $low;
+            } else {
+                return $low+1;
+            }
+        }
+    }
+
+}
\ No newline at end of file

tests/Solarium/ClientTest.php

@@ -205,10 +205,25 @@ class Solarium_ClientTest extends PHPUnit_Framework_TestCase
     {
         $this->assertEquals(
             null,
-            $this->_client->getPlugin('invalidplugin')
+            $this->_client->getPlugin('invalidplugin', false)
         );
     }
 
+    public function testAutoloadPlugin()
+    {
+        $loadbalancer = $this->_client->getPlugin('loadbalancer');
+        $this->assertThat(
+            $loadbalancer,
+            $this->isInstanceOf('Solarium_Plugin_Loadbalancer')
+        );
+    }
+
+    public function testAutoloadInvalidPlugin()
+    {
+        $this->setExpectedException('Solarium_Exception');
+        $this->_client->getPlugin('invalidpluginname');
+    }
+
     public function testRemoveAndGetPlugins()
     {
         $options = array('option1' => 1);
@@ -773,6 +788,20 @@ class Solarium_ClientTest extends PHPUnit_Framework_TestCase
         $observer->createAnalysisDocument($options);
     }
 
+    public function testTriggerEvent()
+    {
+        $eventName = 'Test';
+        $params = array('a', 'b');
+        $override = true;
+
+        $clientMock = $this->getMock('Solarium_Client', array('_callPlugins'));
+        $clientMock->expects($this->once())
+             ->method('_callPlugins')
+             ->with($this->equalTo('event'.$eventName), $this->equalTo($params), $override);
+
+        $clientMock->triggerEvent($eventName, $params, $override);
+    }
+
 }
 
 class MyAdapter extends Solarium_Client_Adapter_Http{

tests/Solarium/Plugin/Loadbalancer/WeightedRandomChoiceTest.php

+<?php
+/**
+ * Copyright 2011 Bas de Nooijer. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this listof conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are
+ * those of the authors and should not be interpreted as representing official
+ * policies, either expressed or implied, of the copyright holder.
+ */
+
+class Solarium_Plugin_Loadbalancer_WeightedRandomChoiceTest extends PHPUnit_Framework_TestCase
+{
+
+    public function testGetRandom()
+    {
+        $choices = array('key1' => 1, 'key2' => 2, 'key3' => 3);
+
+        $randomizer = new Solarium_Plugin_Loadbalancer_WeightedRandomChoice($choices);
+        $choice = $randomizer->getRandom();
+
+        $this->assertTrue(
+            array_key_exists($choice, $choices)
+        );
+
+        $counts = array('key1' => 0, 'key2' => 0, 'key3' => 0);
+        for ($i = 0; $i<1000; $i++) {
+            $choice = $randomizer->getRandom();
+            $counts[$choice]++;
+        }
+
+        $this->assertTrue($counts['key1'] < $counts['key2']);
+        $this->assertTrue($counts['key2'] < $counts['key3']);
+    }
+
+    public function testGetRandomWithExclude()
+    {
+        $choices = array('key1' => 1, 'key2' => 1, 'key3' => 300);
+        $excludes = array('key3');
+
+        $randomizer = new Solarium_Plugin_Loadbalancer_WeightedRandomChoice($choices);
+
+        $key = $randomizer->getRandom($excludes);
+
+        $this->assertTrue($key !== 'key3');
+    }
+
+    public function testAllEntriesExcluded()
+    {
+        $choices = array('key1' => 1, 'key2' => 2, 'key3' => 3);
+        $excludes = array_keys($choices);
+
+        $randomizer = new Solarium_Plugin_Loadbalancer_WeightedRandomChoice($choices);
+
+        $this->setExpectedException('Solarium_Exception');
+        $randomizer->getRandom($excludes);
+    }
+
+}
\ No newline at end of file

tests/Solarium/Plugin/LoadbalancerTest.php

+<?php
+/**
+ * Copyright 2011 Bas de Nooijer. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this listof conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are
+ * those of the authors and should not be interpreted as representing official
+ * policies, either expressed or implied, of the copyright holder.
+ */
+
+class Solarium_Plugin_LoadbalancerTest extends PHPUnit_Framework_TestCase
+{
+    /**
+     * @var Solarium_Plugin_Loadbalancer
+     */
+    protected $_plugin;
+
+    protected $_serverOptions = array('host' => '192.168.1.10');
+
+    public function setUp()
+    {
+        $this->_plugin = new Solarium_Plugin_Loadbalancer();
+    }
+
+    public function testSetAndGetFailoverEnabled()
+    {
+        $this->_plugin->setFailoverEnabled(true);
+        $this->assertEquals(true, $this->_plugin->getFailoverEnabled());
+    }
+
+    public function testSetAndGetFailoverMaxRetries()
+    {
+        $this->_plugin->setFailoverMaxRetries(16);
+        $this->assertEquals(16, $this->_plugin->getFailoverMaxRetries());
+    }
+
+    public function testAddServer()
+    {
+        $this->_plugin->addServer('s1', $this->_serverOptions, 10);
+
+        $this->assertEquals(
+            array('s1' =>
+                array(
+                    'options' => $this->_serverOptions,
+                    'weight' => 10,
+                )
+            ),
+            $this->_plugin->getServers()
+        );
+    }
+
+    public function testAddServerWithDuplicateKey()
+    {
+        $this->_plugin->addServer('s1', $this->_serverOptions, 10);
+
+        $this->setExpectedException('Solarium_Exception');
+        $this->_plugin->addServer('s1', $this->_serverOptions, 20);
+    }
+
+    public function testGetServer()
+    {
+        $this->_plugin->addServer('s1', $this->_serverOptions, 10);
+
+        $this->assertEquals(
+            array('options' => $this->_serverOptions, 'weight' => 10),
+            $this->_plugin->getServer('s1')
+        );
+    }
+
+    public function testGetInvalidServer()
+    {
+        $this->_plugin->addServer('s1', $this->_serverOptions, 10);
+
+        $this->setExpectedException('Solarium_Exception');
+        $this->_plugin->getServer('s2');
+    }
+
+    public function testClearServers()
+    {
+        $this->_plugin->addServer('s1', $this->_serverOptions, 10);
+        $this->_plugin->clearServers();
+        $this->assertEquals(array(), $this->_plugin->getServers());
+    }
+
+    public function testAddServers()
+    {
+        $servers = array(
+            's1' => array('options' => $this->_serverOptions, 'weight' => 10),
+            's2' => array('options' => $this->_serverOptions, 'weight' => 20),
+        );
+
+        $this->_plugin->addServers($servers);
+        $this->assertEquals($servers, $this->_plugin->getServers());
+    }
+
+    public function testRemoveServer()
+    {
+        $servers = array(
+            's1' => array('options' => $this->_serverOptions, 'weight' => 10),
+            's2' => array('options' => $this->_serverOptions, 'weight' => 20),
+        );
+
+        $this->_plugin->addServers($servers);
+        $this->_plugin->removeServer('s1');
+
+        $this->assertEquals(
+            array('s2' => array('options' => $this->_serverOptions, 'weight' => 20)),
+            $this->_plugin->getServers()
+        );
+    }
+
+    public function testSetServers()
+    {
+        $servers1 = array(
+            's1' => array('options' => $this->_serverOptions, 'weight' => 10),
+            's2' => array('options' => $this->_serverOptions, 'weight' => 20),
+        );
+
+        $servers2 = array(
+            's3' => array('options' => $this->_serverOptions, 'weight' => 50),
+            's4' => array('options' => $this->_serverOptions, 'weight' => 30),
+        );
+
+        $this->_plugin->addServers($servers1);
+        $this->_plugin->setServers($servers2);
+
+        $this->assertEquals(
+            $servers2,
+            $this->_plugin->getServers()
+        );
+    }
+
+    public function testSetAndGetForcedServerForNextQuery()
+    {
+        $servers1 = array(
+            's1' => array('options' => $this->_serverOptions, 'weight' => 10),
+            's2' => array('options' => $this->_serverOptions, 'weight' => 20),
+        );
+        $this->_plugin->addServers($servers1);
+
+        $this->_plugin->setForcedServerForNextQuery('s2');
+        $this->assertEquals('s2', $this->_plugin->getForcedServerForNextQuery());
+    }
+
+    public function testSetForcedServerForNextQueryWithInvalidKey()
+    {
+        $servers1 = array(
+            's1' => array('options' => $this->_serverOptions, 'weight' => 10),
+            's2' => array('options' => $this->_serverOptions, 'weight' => 20),
+        );
+        $this->_plugin->addServers($servers1);
+
+        $this->setExpectedException('Solarium_Exception');
+        $this->_plugin->setForcedServerForNextQuery('s3');
+    }
+
+    public function testAddBlockedQueryType()
+    {
+        $this->_plugin->addBlockedQueryType('type1');
+        $this->_plugin->addBlockedQueryType('type2');
+
+        $this->assertEquals(
+            array(Solarium_Client::QUERYTYPE_UPDATE, 'type1', 'type2'),
+            $this->_plugin->getBlockedQueryTypes()
+        );
+    }
+
+    public function testClearBlockedQueryTypes()
+    {
+        $this->_plugin->addBlockedQueryType('type1');
+        $this->_plugin->addBlockedQueryType('type2');
+        $this->_plugin->clearBlockedQueryTypes();
+        $this->assertEquals(array(), $this->_plugin->getBlockedQueryTypes());
+    }
+
+    public function testAddBlockedQueryTypes()
+    {
+        $blockedQueryTypes = array('type1', 'type2', 'type3');
+
+        $this->_plugin->clearBlockedQueryTypes();
+        $this->_plugin->addBlockedQueryTypes($blockedQueryTypes);
+        $this->assertEquals($blockedQueryTypes, $this->_plugin->getBlockedQueryTypes());
+    }
+
+    public function testRemoveBlockedQueryType()
+    {
+        $blockedQueryTypes = array('type1', 'type2', 'type3');
+
+        $this->_plugin->clearBlockedQueryTypes();
+        $this->_plugin->addBlockedQueryTypes($blockedQueryTypes);
+        $this->_plugin->removeBlockedQueryType('type2');
+
+        $this->assertEquals(
+            array('type1', 'type3'),
+            $this->_plugin->getBlockedQueryTypes()
+        );
+    }
+
+    public function testSetBlockedQueryTypes()
+    {
+        $blockedQueryTypes = array('type1', 'type2', 'type3');
+
+        $this->_plugin->setBlockedQueryTypes($blockedQueryTypes);
+
+        $this->assertEquals(
+            $blockedQueryTypes,
+            $this->_plugin->getBlockedQueryTypes()
+        );
+    }
+
+}
\ No newline at end of file