<?php/** * @copyright Copyright 2007 Conduit Internet Technologies, Inc. (http://conduit-it.com) * @license Apache Licence, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0) * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * *     http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * * @package Apache * @subpackage Solr * @author Donovan Jimenez <djimenez@conduit-it.com> */require_once('Apache/Solr/Service.php');/** * Reference Implementation for using multiple Solr services in a distribution. Functionality * includes: * 	routing of read / write operations * 	failover (on selection) for multiple read servers */class Apache_Solr_Service_Balancer{	protected $_createDocuments = true;	protected $_readableServices = array();	protected $_writeableServices = array();	protected $_currentReadService = null;	protected $_currentWriteService = null;	protected $_readPingTimeout = 1;	protected $_writePingTimeout = 1;	/**	 * Escape a value for special query characters such as ':', '(', ')', '*', '?', etc.	 *	 * NOTE: inside a phrase fewer characters need escaped, use {@link Apache_Solr_Service::escapePhrase()} instead	 *	 * @param string $value	 * @return string	 */	static public function escape($value)	{		return Apache_Solr_Service::escape($value);	}	/**	 * Escape a value meant to be contained in a phrase for special query characters	 *	 * @param string $value	 * @return string	 */	static public function escapePhrase($value)	{		return Apache_Solr_Service::escapePhrase($value);	}	/**	 * Convenience function for creating phrase syntax from a value	 *	 * @param string $value	 * @return string	 */	static public function phrase($value)	{		return Apache_Solr_Service::phrase($value);	}	/**	 * Constructor. Takes arrays of read and write service instances or descriptions	 *	 * @param array $readableServices	 * @param array $writeableServices	 */	public function __construct($readableServices = array(), $writeableServices = array())	{		//setup readable services		foreach ($readableServices as $service)		{			$this->addReadService($service);		}		//setup writeable services		foreach ($writeableServices as $service)		{			$this->addWriteService($service);		}	}	public function setReadPingTimeout($timeout)	{		$this->_readPingTimeout = $timeout;	}	public function setWritePingTimetou($timeout)	{		$this->_writePingTimeout = $timeout;	}	/**	 * Generates a service ID	 *	 * @param string $host	 * @param integer $port	 * @param string $path	 * @return string	 */	private function _getServiceId($host, $port, $path)	{		return $host . ':' . $port . $path;	}	/**	 * Adds a service instance or service descriptor (if it is already	 * not added)	 *	 * @param mixed $service	 *	 * @throws Exception If service descriptor is not valid	 */	public function addReadService($service)	{		if ($service instanceof Apache_Solr_Service)		{			$id = $this->_getServiceId($service->getHost(), $service->getPort(), $service->getPath());			$this->_readableServices[$id] = $service;		}		else if (is_array($service))		{			if (isset($service['host']) && isset($service['port']) && isset($service['path']))			{				$id = $this->_getServiceId((string)$service['host'], (int)$service['port'], (string)$service['path']);				$this->_readableServices[$id] = $service;			}			else			{				throw new Exception('A Readable Service description array does not have all required elements of host, port, and path');			}		}	}	/**	 * Removes a service instance or descriptor from the available services	 *	 * @param mixed $service	 *	 * @throws Exception If service descriptor is not valid	 */	public function removeReadService($service)	{		$id = '';		if ($service instanceof Apache_Solr_Service)		{			$id = $this->_getServiceId($service->getHost(), $service->getPort(), $service->getPath());		}		else if (is_array($service))		{			if (isset($service['host']) && isset($service['port']) && isset($service['path']))			{				$id = $this->_getServiceId((string)$service['host'], (int)$service['port'], (string)$service['path']);			}			else			{				throw new Exception('A Readable Service description array does not have all required elements of host, port, and path');			}		}		if ($id)		{			unset($this->_readableServices[$id]);		}	}	/**	 * Adds a service instance or service descriptor (if it is already	 * not added)	 *	 * @param mixed $service	 *	 * @throws Exception If service descriptor is not valid	 */	public function addWriteService($service)	{		if ($service instanceof Apache_Solr_Service)		{			$id = $this->_getServiceId($service->getHost(), $service->getPort(), $service->getPath());			$this->_writeableServices[$id] = $service;		}		else if (is_array($service))		{			if (isset($service['host']) && isset($service['port']) && isset($service['path']))			{				$id = $this->_getServiceId((string)$service['host'], (int)$service['port'], (string)$service['path']);				$this->_writeableServices[$id] = $service;			}			else			{				throw new Exception('A Writeable Service description array does not have all required elements of host, port, and path');			}		}	}	/**	 * Removes a service instance or descriptor from the available services	 *	 * @param mixed $service	 *	 * @throws Exception If service descriptor is not valid	 */	public function removeWriteService($service)	{		$id = '';		if ($service instanceof Apache_Solr_Service)		{			$id = $this->_getServiceId($service->getHost(), $service->getPort(), $service->getPath());		}		else if (is_array($service))		{			if (isset($service['host']) && isset($service['port']) && isset($service['path']))			{				$id = $this->_getServiceId((string)$service['host'], (int)$service['port'], (string)$service['path']);			}			else			{				throw new Exception('A Readable Service description array does not have all required elements of host, port, and path');			}		}		if ($id)		{			unset($this->_writeableServices[$id]);		}	}	/**	 * Iterate through available read services and select the first with a ping	 * that satisfies configured timeout restrictions (or the default)	 *	 * @return Apache_Solr_Service	 *	 * @throws Exception If there are no read services that meet requirements	 */	private function _selectReadService($forceSelect = false)	{		if (!$this->_currentReadService || !isset($this->_readableServices[$this->_currentReadService]) || $forceSelect)		{			foreach ($this->_readableServices as $id => $service)			{				if (is_array($service))				{					//convert the array definition to a client object					$service = new Apache_Solr_Service($service['host'], $service['port'], $service['path']);					$service->setCreateDocuments($this->_createDocuments);					$this->_readableServices[$id] = $service;				}				//check the service (make sure it pings quickly)				if ($service->ping($this->_readPingTimeout) !== false)				{					$service->setCreateDocuments($this->_createDocuments);					$this->_currentReadService = $id;					return $this->_readableServices[$this->_currentReadService];				}			}			throw new Exception('No read services were available');		}		return $this->_readableServices[$this->_currentReadService];	}	/**	 * Iterate through available write services and select the first with a ping	 * that satisfies configured timeout restrictions (or the default)	 *	 * @return Apache_Solr_Service	 *	 * @throws Exception If there are no write services that meet requirements	 */	private function _selectWriteService($forceSelect = false)	{		if (!$this->_currentWriteService || !isset($this->_writeableServices[$this->_currentWriteService]) || $forceSelect)		{			foreach ($this->_writeableServices as $id => $service)			{				if (is_array($service))				{					//convert the array definition to a client object					$service = new Apache_Solr_Service($service['host'], $service['port'], $service['path']);					$this->_writeableServices[$id] = $service;				}				//check the service				if ($service->ping($this->_writePingTimeout) !== false)				{					$this->_currentWriteService = $id;					return $this->_writeableServices[$this->_currentWriteService];				}