View Javadoc

1   /**
2    *
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *     http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   */
19  package org.apache.hadoop.hbase.client.replication;
20  
21  import java.io.Closeable;
22  import java.io.IOException;
23  import java.util.ArrayList;
24  import java.util.Collection;
25  import java.util.HashMap;
26  import java.util.HashSet;
27  import java.util.List;
28  import java.util.Map;
29  import java.util.Map.Entry;
30  import java.util.Set;
31  
32  import org.apache.commons.lang.StringUtils;
33  import org.apache.commons.logging.Log;
34  import org.apache.commons.logging.LogFactory;
35  import org.apache.hadoop.hbase.classification.InterfaceAudience;
36  import org.apache.hadoop.hbase.classification.InterfaceStability;
37  import org.apache.hadoop.conf.Configuration;
38  import org.apache.hadoop.hbase.Abortable;
39  import org.apache.hadoop.hbase.HColumnDescriptor;
40  import org.apache.hadoop.hbase.HConstants;
41  import org.apache.hadoop.hbase.HTableDescriptor;
42  import org.apache.hadoop.hbase.TableName;
43  import org.apache.hadoop.hbase.classification.InterfaceAudience;
44  import org.apache.hadoop.hbase.classification.InterfaceStability;
45  import org.apache.hadoop.hbase.client.Admin;
46  import org.apache.hadoop.hbase.client.HBaseAdmin;
47  import org.apache.hadoop.hbase.client.Connection;
48  import org.apache.hadoop.hbase.client.ConnectionFactory;
49  import org.apache.hadoop.hbase.replication.ReplicationException;
50  import org.apache.hadoop.hbase.replication.ReplicationFactory;
51  import org.apache.hadoop.hbase.replication.ReplicationPeerConfig;
52  import org.apache.hadoop.hbase.replication.ReplicationPeers;
53  import org.apache.hadoop.hbase.replication.ReplicationQueuesClient;
54  import org.apache.hadoop.hbase.zookeeper.ZooKeeperWatcher;
55  
56  import com.google.common.annotations.VisibleForTesting;
57  import com.google.common.collect.Lists;
58  
59  /**
60   * <p>
61   * This class provides the administrative interface to HBase cluster
62   * replication. In order to use it, the cluster and the client using
63   * ReplicationAdmin must be configured with <code>hbase.replication</code>
64   * set to true.
65   * </p>
66   * <p>
67   * Adding a new peer results in creating new outbound connections from every
68   * region server to a subset of region servers on the slave cluster. Each
69   * new stream of replication will start replicating from the beginning of the
70   * current WAL, meaning that edits from that past will be replicated.
71   * </p>
72   * <p>
73   * Removing a peer is a destructive and irreversible operation that stops
74   * all the replication streams for the given cluster and deletes the metadata
75   * used to keep track of the replication state.
76   * </p>
77   * <p>
78   * To see which commands are available in the shell, type
79   * <code>replication</code>.
80   * </p>
81   */
82  @InterfaceAudience.Public
83  @InterfaceStability.Evolving
84  public class ReplicationAdmin implements Closeable {
85    private static final Log LOG = LogFactory.getLog(ReplicationAdmin.class);
86  
87    public static final String TNAME = "tableName";
88    public static final String CFNAME = "columnFamlyName";
89  
90    // only Global for now, can add other type
91    // such as, 1) no global replication, or 2) the table is replicated to this cluster, etc.
92    public static final String REPLICATIONTYPE = "replicationType";
93    public static final String REPLICATIONGLOBAL = Integer
94        .toString(HConstants.REPLICATION_SCOPE_GLOBAL);
95  
96    private final Connection connection;
97    // TODO: replication should be managed by master. All the classes except ReplicationAdmin should
98    // be moved to hbase-server. Resolve it in HBASE-11392.
99    private final ReplicationQueuesClient replicationQueuesClient;
100   private final ReplicationPeers replicationPeers;
101   /**
102    * A watcher used by replicationPeers and replicationQueuesClient. Keep reference so can dispose
103    * on {@link #close()}.
104    */
105   private final ZooKeeperWatcher zkw;
106 
107   /**
108    * Constructor that creates a connection to the local ZooKeeper ensemble.
109    * @param conf Configuration to use
110    * @throws IOException if an internal replication error occurs
111    * @throws RuntimeException if replication isn't enabled.
112    */
113   public ReplicationAdmin(Configuration conf) throws IOException {
114     if (!conf.getBoolean(HConstants.REPLICATION_ENABLE_KEY,
115         HConstants.REPLICATION_ENABLE_DEFAULT)) {
116       throw new RuntimeException("hbase.replication isn't true, please " +
117           "enable it in order to use replication");
118     }
119     this.connection = ConnectionFactory.createConnection(conf);
120     zkw = createZooKeeperWatcher();
121     try {
122       this.replicationPeers = ReplicationFactory.getReplicationPeers(zkw, conf, this.connection);
123       this.replicationPeers.init();
124       this.replicationQueuesClient =
125           ReplicationFactory.getReplicationQueuesClient(zkw, conf, this.connection);
126       this.replicationQueuesClient.init();
127 
128     } catch (ReplicationException e) {
129       throw new IOException("Error initializing the replication admin client.", e);
130     }
131   }
132 
133   private ZooKeeperWatcher createZooKeeperWatcher() throws IOException {
134     // This Abortable doesn't 'abort'... it just logs.
135     return new ZooKeeperWatcher(connection.getConfiguration(), "ReplicationAdmin", new Abortable() {
136       @Override
137       public void abort(String why, Throwable e) {
138         LOG.error(why, e);
139         // We used to call system.exit here but this script can be embedded by other programs that
140         // want to do replication stuff... so inappropriate calling System.exit. Just log for now.
141       }
142 
143       @Override
144       public boolean isAborted() {
145         return false;
146       }
147     });
148   }
149 
150   /**
151    * Add a new peer cluster to replicate to.
152    * @param id a short name that identifies the cluster
153    * @param clusterKey the concatenation of the slave cluster's
154    * <code>hbase.zookeeper.quorum:hbase.zookeeper.property.clientPort:zookeeper.znode.parent</code>
155    * @throws IllegalStateException if there's already one slave since
156    * multi-slave isn't supported yet.
157    * @deprecated Use addPeer(String, ReplicationPeerConfig, Map) instead.
158    */
159   @Deprecated
160   public void addPeer(String id, String clusterKey) throws ReplicationException {
161     this.addPeer(id, new ReplicationPeerConfig().setClusterKey(clusterKey), null);
162   }
163 
164   @Deprecated
165   public void addPeer(String id, String clusterKey, String tableCFs)
166     throws ReplicationException {
167     this.replicationPeers.addPeer(id,
168       new ReplicationPeerConfig().setClusterKey(clusterKey), tableCFs);
169   }
170 
171   /**
172    * Add a new remote slave cluster for replication.
173    * @param id a short name that identifies the cluster
174    * @param peerConfig configuration for the replication slave cluster
175    * @param tableCfs the table and column-family list which will be replicated for this peer.
176    * A map from tableName to column family names. An empty collection can be passed
177    * to indicate replicating all column families. Pass null for replicating all table and column
178    * families
179    */
180   public void addPeer(String id, ReplicationPeerConfig peerConfig,
181       Map<TableName, ? extends Collection<String>> tableCfs) throws ReplicationException {
182     this.replicationPeers.addPeer(id, peerConfig, getTableCfsStr(tableCfs));
183   }
184 
185   public static Map<TableName, List<String>> parseTableCFsFromConfig(String tableCFsConfig) {
186     if (tableCFsConfig == null || tableCFsConfig.trim().length() == 0) {
187       return null;
188     }
189 
190     Map<TableName, List<String>> tableCFsMap = null;
191     // TODO: This should be a PB object rather than a String to be parsed!! See HBASE-11393
192     // parse out (table, cf-list) pairs from tableCFsConfig
193     // format: "table1:cf1,cf2;table2:cfA,cfB"
194     String[] tables = tableCFsConfig.split(";");
195     for (String tab : tables) {
196       // 1 ignore empty table config
197       tab = tab.trim();
198       if (tab.length() == 0) {
199         continue;
200       }
201       // 2 split to "table" and "cf1,cf2"
202       //   for each table: "table:cf1,cf2" or "table"
203       String[] pair = tab.split(":");
204       String tabName = pair[0].trim();
205       if (pair.length > 2 || tabName.length() == 0) {
206         LOG.error("ignore invalid tableCFs setting: " + tab);
207         continue;
208       }
209 
210       // 3 parse "cf1,cf2" part to List<cf>
211       List<String> cfs = null;
212       if (pair.length == 2) {
213         String[] cfsList = pair[1].split(",");
214         for (String cf : cfsList) {
215           String cfName = cf.trim();
216           if (cfName.length() > 0) {
217             if (cfs == null) {
218               cfs = new ArrayList<String>();
219             }
220             cfs.add(cfName);
221           }
222         }
223       }
224 
225       // 4 put <table, List<cf>> to map
226       if (tableCFsMap == null) {
227         tableCFsMap = new HashMap<TableName, List<String>>();
228       }
229       tableCFsMap.put(TableName.valueOf(tabName), cfs);
230     }
231     return tableCFsMap;
232   }
233 
234   @VisibleForTesting
235   static String getTableCfsStr(Map<TableName, ? extends Collection<String>> tableCfs) {
236     String tableCfsStr = null;
237     if (tableCfs != null) {
238       // Format: table1:cf1,cf2;table2:cfA,cfB;table3
239       StringBuilder builder = new StringBuilder();
240       for (Entry<TableName, ? extends Collection<String>> entry : tableCfs.entrySet()) {
241         if (builder.length() > 0) {
242           builder.append(";");
243         }
244         builder.append(entry.getKey());
245         if (entry.getValue() != null && !entry.getValue().isEmpty()) {
246           builder.append(":");
247           builder.append(StringUtils.join(entry.getValue(), ","));
248         }
249       }
250       tableCfsStr = builder.toString();
251     }
252     return tableCfsStr;
253   }
254 
255   /**
256    * Removes a peer cluster and stops the replication to it.
257    * @param id a short name that identifies the cluster
258    */
259   public void removePeer(String id) throws ReplicationException {
260     this.replicationPeers.removePeer(id);
261   }
262 
263   /**
264    * Restart the replication stream to the specified peer.
265    * @param id a short name that identifies the cluster
266    */
267   public void enablePeer(String id) throws ReplicationException {
268     this.replicationPeers.enablePeer(id);
269   }
270 
271   /**
272    * Stop the replication stream to the specified peer.
273    * @param id a short name that identifies the cluster
274    */
275   public void disablePeer(String id) throws ReplicationException {
276     this.replicationPeers.disablePeer(id);
277   }
278 
279   /**
280    * Get the number of slave clusters the local cluster has.
281    * @return number of slave clusters
282    */
283   public int getPeersCount() {
284     return this.replicationPeers.getAllPeerIds().size();
285   }
286 
287   /**
288    * Map of this cluster's peers for display.
289    * @return A map of peer ids to peer cluster keys
290    * @deprecated use {@link #listPeerConfigs()}
291    */
292   @Deprecated
293   public Map<String, String> listPeers() {
294     Map<String, ReplicationPeerConfig> peers = this.listPeerConfigs();
295     Map<String, String> ret = new HashMap<String, String>(peers.size());
296 
297     for (Map.Entry<String, ReplicationPeerConfig> entry : peers.entrySet()) {
298       ret.put(entry.getKey(), entry.getValue().getClusterKey());
299     }
300     return ret;
301   }
302 
303   public Map<String, ReplicationPeerConfig> listPeerConfigs() {
304     return this.replicationPeers.getAllPeerConfigs();
305   }
306 
307   public ReplicationPeerConfig getPeerConfig(String id) throws ReplicationException {
308     return this.replicationPeers.getReplicationPeerConfig(id);
309   }
310 
311   /**
312    * Get the replicable table-cf config of the specified peer.
313    * @param id a short name that identifies the cluster
314    */
315   public String getPeerTableCFs(String id) throws ReplicationException {
316     return this.replicationPeers.getPeerTableCFsConfig(id);
317   }
318 
319   /**
320    * Set the replicable table-cf config of the specified peer
321    * @param id a short name that identifies the cluster
322    * @deprecated use {@link #setPeerTableCFs(String, Map)}
323    */
324   @Deprecated
325   public void setPeerTableCFs(String id, String tableCFs) throws ReplicationException {
326     this.replicationPeers.setPeerTableCFsConfig(id, tableCFs);
327   }
328 
329   /**
330    * Append the replicable table-cf config of the specified peer
331    * @param id a short that identifies the cluster
332    * @param tableCfs table-cfs config str
333    * @throws KeeperException
334    */
335   public void appendPeerTableCFs(String id, String tableCfs) throws ReplicationException {
336     appendPeerTableCFs(id, parseTableCFsFromConfig(tableCfs));
337   }
338 
339   /**
340    * Append the replicable table-cf config of the specified peer
341    * @param id a short that identifies the cluster
342    * @param tableCfs A map from tableName to column family names
343    * @throws KeeperException
344    */
345   public void appendPeerTableCFs(String id, Map<TableName, ? extends Collection<String>> tableCfs)
346       throws ReplicationException {
347     if (tableCfs == null) {
348       throw new ReplicationException("tableCfs is null");
349     }
350     Map<TableName, List<String>> preTableCfs = parseTableCFsFromConfig(getPeerTableCFs(id));
351     if (preTableCfs == null) {
352       setPeerTableCFs(id, tableCfs);
353       return;
354     }
355 
356     for (Map.Entry<TableName, ? extends Collection<String>> entry : tableCfs.entrySet()) {
357       TableName table = entry.getKey();
358       Collection<String> appendCfs = entry.getValue();
359       if (preTableCfs.containsKey(table)) {
360         List<String> cfs = preTableCfs.get(table);
361         if (cfs == null || appendCfs == null) {
362           preTableCfs.put(table, null);
363         } else {
364           Set<String> cfSet = new HashSet<String>(cfs);
365           cfSet.addAll(appendCfs);
366           preTableCfs.put(table, Lists.newArrayList(cfSet));
367         }
368       } else {
369         if (appendCfs == null || appendCfs.isEmpty()) {
370           preTableCfs.put(table, null);
371         } else {
372           preTableCfs.put(table, Lists.newArrayList(appendCfs));
373         }
374       }
375     }
376     setPeerTableCFs(id, preTableCfs);
377   }
378 
379   /**
380    * Remove some table-cfs from table-cfs config of the specified peer
381    * @param id a short name that identifies the cluster
382    * @param tableCf table-cfs config str
383    * @throws ReplicationException
384    */
385   public void removePeerTableCFs(String id, String tableCf) throws ReplicationException {
386     removePeerTableCFs(id, parseTableCFsFromConfig(tableCf));
387   }
388 
389   /**
390    * Remove some table-cfs from config of the specified peer
391    * @param id a short name that identifies the cluster
392    * @param tableCfs A map from tableName to column family names
393    * @throws ReplicationException
394    */
395   public void removePeerTableCFs(String id, Map<TableName, ? extends Collection<String>> tableCfs)
396       throws ReplicationException {
397     if (tableCfs == null) {
398       throw new ReplicationException("tableCfs is null");
399     }
400 
401     Map<TableName, List<String>> preTableCfs = parseTableCFsFromConfig(getPeerTableCFs(id));
402     if (preTableCfs == null) {
403       throw new ReplicationException("Table-Cfs for peer" + id + " is null");
404     }
405     for (Map.Entry<TableName, ? extends Collection<String>> entry: tableCfs.entrySet()) {
406       TableName table = entry.getKey();
407       Collection<String> removeCfs = entry.getValue();
408       if (preTableCfs.containsKey(table)) {
409         List<String> cfs = preTableCfs.get(table);
410         if (cfs == null && removeCfs == null) {
411           preTableCfs.remove(table);
412         } else if (cfs != null && removeCfs != null) {
413           Set<String> cfSet = new HashSet<String>(cfs);
414           cfSet.removeAll(removeCfs);
415           if (cfSet.isEmpty()) {
416             preTableCfs.remove(table);
417           } else {
418             preTableCfs.put(table, Lists.newArrayList(cfSet));
419           }
420         } else if (cfs == null && removeCfs != null) {
421           throw new ReplicationException("Cannot remove cf of table: " + table
422               + " which doesn't specify cfs from table-cfs config in peer: " + id);
423         } else if (cfs != null && removeCfs == null) {
424           throw new ReplicationException("Cannot remove table: " + table
425               + " which has specified cfs from table-cfs config in peer: " + id);
426         }
427       } else {
428         throw new ReplicationException("No table: " + table + " in table-cfs config of peer: " + id);
429       }
430     }
431     setPeerTableCFs(id, preTableCfs);
432   }
433 
434   /**
435    * Set the replicable table-cf config of the specified peer
436    * @param id a short name that identifies the cluster
437    * @param tableCfs the table and column-family list which will be replicated for this peer.
438    * A map from tableName to column family names. An empty collection can be passed
439    * to indicate replicating all column families. Pass null for replicating all table and column
440    * families
441    */
442   public void setPeerTableCFs(String id, Map<TableName, ? extends Collection<String>> tableCfs)
443       throws ReplicationException {
444     this.replicationPeers.setPeerTableCFsConfig(id, getTableCfsStr(tableCfs));
445   }
446 
447   /**
448    * Get the state of the specified peer cluster
449    * @param id String format of the Short name that identifies the peer,
450    * an IllegalArgumentException is thrown if it doesn't exist
451    * @return true if replication is enabled to that peer, false if it isn't
452    */
453   public boolean getPeerState(String id) throws ReplicationException {
454     return this.replicationPeers.getStatusOfPeerFromBackingStore(id);
455   }
456 
457   @Override
458   public void close() throws IOException {
459     if (this.zkw != null) {
460       this.zkw.close();
461     }
462     if (this.connection != null) {
463       this.connection.close();
464     }
465   }
466 
467 
468   /**
469    * Find all column families that are replicated from this cluster
470    * @return the full list of the replicated column families of this cluster as:
471    *        tableName, family name, replicationType
472    *
473    * Currently replicationType is Global. In the future, more replication
474    * types may be extended here. For example
475    *  1) the replication may only apply to selected peers instead of all peers
476    *  2) the replicationType may indicate the host Cluster servers as Slave
477    *     for the table:columnFam.
478    */
479   public List<HashMap<String, String>> listReplicated() throws IOException {
480     List<HashMap<String, String>> replicationColFams = new ArrayList<HashMap<String, String>>();
481 
482     Admin admin = connection.getAdmin();
483     HTableDescriptor[] tables;
484     try {
485       tables = admin.listTables();
486     } finally {
487       if (admin!= null) admin.close();
488     }
489 
490     for (HTableDescriptor table : tables) {
491       HColumnDescriptor[] columns = table.getColumnFamilies();
492       String tableName = table.getNameAsString();
493       for (HColumnDescriptor column : columns) {
494         if (column.getScope() != HConstants.REPLICATION_SCOPE_LOCAL) {
495           // At this moment, the columfam is replicated to all peers
496           HashMap<String, String> replicationEntry = new HashMap<String, String>();
497           replicationEntry.put(TNAME, tableName);
498           replicationEntry.put(CFNAME, column.getNameAsString());
499           replicationEntry.put(REPLICATIONTYPE, REPLICATIONGLOBAL);
500           replicationColFams.add(replicationEntry);
501         }
502       }
503     }
504 
505     return replicationColFams;
506   }
507 }