001/*
002 *
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *     http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 */
019package org.apache.hadoop.hbase.replication;
020
021import java.util.Collection;
022import java.util.List;
023import java.util.Map;
024import java.util.Set;
025
026import org.apache.hadoop.conf.Configuration;
027import org.apache.hadoop.hbase.TableName;
028import org.apache.yetus.audience.InterfaceAudience;
029import org.apache.hadoop.hbase.util.Pair;
030
031/**
032 * This provides an interface for maintaining a set of peer clusters. These peers are remote slave
033 * clusters that data is replicated to. A peer cluster can be in three different states:
034 *
035 * 1. Not-Registered - There is no notion of the peer cluster.
036 * 2. Registered - The peer has an id and is being tracked but there is no connection.
037 * 3. Connected - There is an active connection to the remote peer.
038 *
039 * In the registered or connected state, a peer cluster can either be enabled or disabled.
040 */
041@InterfaceAudience.Private
042public interface ReplicationPeers {
043
044  /**
045   * Initialize the ReplicationPeers interface.
046   */
047  void init() throws ReplicationException;
048
049  /**
050   * Add a new remote slave cluster for replication.
051   * @param peerId a short that identifies the cluster
052   * @param peerConfig configuration for the replication slave cluster
053   */
054  default void registerPeer(String peerId, ReplicationPeerConfig peerConfig)
055      throws ReplicationException {
056    registerPeer(peerId, peerConfig, true);
057  }
058
059  /**
060   * Add a new remote slave cluster for replication.
061   * @param peerId a short that identifies the cluster
062   * @param peerConfig configuration for the replication slave cluster
063   * @param enabled peer state, true if ENABLED and false if DISABLED
064   */
065  void registerPeer(String peerId, ReplicationPeerConfig peerConfig, boolean enabled)
066      throws ReplicationException;
067
068  /**
069   * Removes a remote slave cluster and stops the replication to it.
070   * @param peerId a short that identifies the cluster
071   */
072  void unregisterPeer(String peerId) throws ReplicationException;
073
074  /**
075   * Method called after a peer has been connected. It will create a ReplicationPeer to track the
076   * newly connected cluster.
077   * @param peerId a short that identifies the cluster
078   * @return whether a ReplicationPeer was successfully created
079   * @throws ReplicationException
080   */
081  boolean peerConnected(String peerId) throws ReplicationException;
082
083  /**
084   * Method called after a peer has been disconnected. It will remove the ReplicationPeer that
085   * tracked the disconnected cluster.
086   * @param peerId a short that identifies the cluster
087   */
088  void peerDisconnected(String peerId);
089
090  /**
091   * Restart the replication to the specified remote slave cluster.
092   * @param peerId a short that identifies the cluster
093   */
094  void enablePeer(String peerId) throws ReplicationException;
095
096  /**
097   * Stop the replication to the specified remote slave cluster.
098   * @param peerId a short that identifies the cluster
099   */
100  void disablePeer(String peerId) throws ReplicationException;
101
102  /**
103   * Get the table and column-family list string of the peer from the underlying storage.
104   * @param peerId a short that identifies the cluster
105   */
106  public Map<TableName, List<String>> getPeerTableCFsConfig(String peerId)
107      throws ReplicationException;
108
109  /**
110   * Set the table and column-family list string of the peer to the underlying storage.
111   * @param peerId a short that identifies the cluster
112   * @param tableCFs the table and column-family list which will be replicated for this peer
113   */
114  public void setPeerTableCFsConfig(String peerId,
115                                    Map<TableName, ? extends Collection<String>>  tableCFs)
116      throws ReplicationException;
117
118  /**
119   * Returns the ReplicationPeer for the specified connected peer. This ReplicationPeer will
120   * continue to track changes to the Peer's state and config. This method returns null if no
121   * peer has been connected with the given peerId.
122   * @param peerId id for the peer
123   * @return ReplicationPeer object
124   */
125  ReplicationPeer getConnectedPeer(String peerId);
126
127  /**
128   * Returns the set of peerIds of the clusters that have been connected and have an underlying
129   * ReplicationPeer.
130   * @return a Set of Strings for peerIds
131   */
132  public Set<String> getConnectedPeerIds();
133
134  /**
135   * Get the replication status for the specified connected remote slave cluster.
136   * The value might be read from cache, so it is recommended to
137   * use {@link #getStatusOfPeerFromBackingStore(String)}
138   * if reading the state after enabling or disabling it.
139   * @param peerId a short that identifies the cluster
140   * @return true if replication is enabled, false otherwise.
141   */
142  boolean getStatusOfPeer(String peerId);
143
144  /**
145   * Get the replication status for the specified remote slave cluster, which doesn't
146   * have to be connected. The state is read directly from the backing store.
147   * @param peerId a short that identifies the cluster
148   * @return true if replication is enabled, false otherwise.
149   * @throws ReplicationException thrown if there's an error contacting the store
150   */
151  boolean getStatusOfPeerFromBackingStore(String peerId) throws ReplicationException;
152
153  /**
154   * List the cluster replication configs of all remote slave clusters (whether they are
155   * enabled/disabled or connected/disconnected).
156   * @return A map of peer ids to peer cluster keys
157   */
158  Map<String, ReplicationPeerConfig> getAllPeerConfigs();
159
160  /**
161   * List the peer ids of all remote slave clusters (whether they are enabled/disabled or
162   * connected/disconnected).
163   * @return A list of peer ids
164   */
165  List<String> getAllPeerIds();
166
167  /**
168   * Returns the configured ReplicationPeerConfig for this peerId
169   * @param peerId a short name that identifies the cluster
170   * @return ReplicationPeerConfig for the peer
171   */
172  ReplicationPeerConfig getReplicationPeerConfig(String peerId) throws ReplicationException;
173
174  /**
175   * Returns the configuration needed to talk to the remote slave cluster.
176   * @param peerId a short that identifies the cluster
177   * @return the configuration for the peer cluster, null if it was unable to get the configuration
178   */
179  Pair<ReplicationPeerConfig, Configuration> getPeerConf(String peerId) throws ReplicationException;
180
181  /**
182   * Update the peerConfig for the a given peer cluster
183   * @param id a short that identifies the cluster
184   * @param peerConfig new config for the peer cluster
185   * @throws ReplicationException
186   */
187  void updatePeerConfig(String id, ReplicationPeerConfig peerConfig) throws ReplicationException;
188}