3 * Data storage in external repositories.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 * @defgroup ExternalStorage ExternalStorage
28 * Constructor class for data kept in external repositories
30 * External repositories might be populated by maintenance/async
31 * scripts, thus partial moving of data may be possible, as well
32 * as possibility to have any storage format (i.e. for archives)
34 * @ingroup ExternalStorage
39 function __construct( $params = array() ) {
40 $this->mParams
= $params;
44 * Fetch data from given URL
46 * @param $url String: The URL of the text to get
47 * @param $params Array: associative array of parameters for the ExternalStore object.
48 * @return string|bool The text stored or false on error
50 static function fetchFromURL( $url, $params = array() ) {
51 global $wgExternalStores;
53 if( !$wgExternalStores ) {
57 $parts = explode( '://', $url, 2 );
59 if ( count( $parts ) != 2 ) {
63 list( $proto, $path ) = $parts;
65 if ( $path == '' ) { // Bad URL
69 $store = self
::getStoreObject( $proto, $params );
70 if ( $store === false ) {
74 return $store->fetchFromURL( $url );
78 * Get an external store object of the given type, with the given parameters
80 * @param $proto String: type of external storage, should be a value in $wgExternalStores
81 * @param $params Array: associative array of parameters for the ExternalStore object.
82 * @return ExternalStore subclass or false on error
84 static function getStoreObject( $proto, $params = array() ) {
85 global $wgExternalStores;
86 if( !$wgExternalStores ) {
90 /* Protocol not enabled */
91 if( !in_array( $proto, $wgExternalStores ) ) {
95 $class = 'ExternalStore' . ucfirst( $proto );
96 /* Any custom modules should be added to $wgAutoLoadClasses for on-demand loading */
97 if( !MWInit
::classExists( $class ) ) {
101 return new $class($params);
105 * Store a data item to an external store, identified by a partial URL
106 * The protocol part is used to identify the class, the rest is passed to the
107 * class itself as a parameter.
110 * @param $params array
111 * @return string|bool The URL of the stored data item, or false on error
113 static function insert( $url, $data, $params = array() ) {
114 list( $proto, $params ) = explode( '://', $url, 2 );
115 $store = self
::getStoreObject( $proto, $params );
116 if ( $store === false ) {
119 return $store->store( $params, $data );
124 * Like insert() above, but does more of the work for us.
125 * This function does not need a url param, it builds it by
126 * itself. It also fails-over to the next possible clusters.
128 * @param $data String
129 * @param $storageParams Array: associative array of parameters for the ExternalStore object.
130 * @return string The URL of the stored data item, or false on error
132 public static function insertToDefault( $data, $storageParams = array() ) {
133 global $wgDefaultExternalStore;
134 $tryStores = (array)$wgDefaultExternalStore;
136 while ( count( $tryStores ) > 0 ) {
137 $index = mt_rand(0, count( $tryStores ) - 1);
138 $storeUrl = $tryStores[$index];
139 wfDebug( __METHOD__
.": trying $storeUrl\n" );
140 list( $proto, $params ) = explode( '://', $storeUrl, 2 );
141 $store = self
::getStoreObject( $proto, $storageParams );
142 if ( $store === false ) {
143 throw new MWException( "Invalid external storage protocol - $storeUrl" );
146 $url = $store->store( $params, $data ); // Try to save the object
147 } catch ( DBConnectionError
$error ) {
149 } catch( DBQueryError
$error ) {
153 return $url; // Done!
155 unset( $tryStores[$index] ); // Don't try this one again!
156 $tryStores = array_values( $tryStores ); // Must have consecutive keys
157 wfDebugLog( 'ExternalStorage', "Unable to store text to external storage $storeUrl" );
162 // Rethrow the last connection error
165 throw new MWException( "Unable to store text to external storage" );
175 public static function insertToForeignDefault( $data, $wiki ) {
176 return self
::insertToDefault( $data, array( 'wiki' => $wiki ) );