CRZbulabula commented on code in PR #10896:
URL: https://github.com/apache/iotdb/pull/10896#discussion_r1301660452
##########
iotdb-core/consensus/src/main/java/org/apache/iotdb/consensus/IConsensus.java:
##########
@@ -19,137 +19,179 @@
package org.apache.iotdb.consensus;
+import org.apache.iotdb.common.rpc.thrift.TSStatus;
import org.apache.iotdb.commons.consensus.ConsensusGroupId;
+import org.apache.iotdb.consensus.common.DataSet;
import org.apache.iotdb.consensus.common.Peer;
import org.apache.iotdb.consensus.common.request.IConsensusRequest;
-import org.apache.iotdb.consensus.common.response.ConsensusGenericResponse;
-import org.apache.iotdb.consensus.common.response.ConsensusReadResponse;
-import org.apache.iotdb.consensus.common.response.ConsensusWriteResponse;
import org.apache.iotdb.consensus.exception.ConsensusException;
+import
org.apache.iotdb.consensus.exception.ConsensusGroupAlreadyExistException;
+import org.apache.iotdb.consensus.exception.ConsensusGroupNotExistException;
+import org.apache.iotdb.consensus.exception.IllegalPeerEndpointException;
+import org.apache.iotdb.consensus.exception.IllegalPeerNumException;
+import
org.apache.iotdb.consensus.exception.PeerAlreadyInConsensusGroupException;
+import org.apache.iotdb.consensus.exception.PeerNotInConsensusGroupException;
import javax.annotation.concurrent.ThreadSafe;
import java.io.IOException;
import java.util.List;
-/** Consensus module base class. */
+/** Consensus module base interface. */
@ThreadSafe
public interface IConsensus {
+ /**
+ * Start the consensus module.
+ *
+ * @throws IOException when start consensus errors
+ */
void start() throws IOException;
+ /**
+ * Stop the consensus module.
+ *
+ * @throws IOException when stop consensus errors
+ */
void stop() throws IOException;
- // write API
- ConsensusWriteResponse write(ConsensusGroupId groupId, IConsensusRequest
request);
+ /**
+ * Write data to the corresponding consensus group.
+ *
+ * @param groupId the consensus group this request belongs
+ * @param request write request
+ * @return write result
+ * @throws ConsensusGroupNotExistException when the specified consensus
group doesn't exist
+ * @throws ConsensusException when write doesn't success with other reasons
+ */
+ TSStatus write(ConsensusGroupId groupId, IConsensusRequest request) throws
ConsensusException;
- // read API
- ConsensusReadResponse read(ConsensusGroupId groupId, IConsensusRequest
request);
+ /**
+ * Read data from the corresponding consensus group.
+ *
+ * @param groupId the consensus group this request belongs
+ * @param request read request
+ * @return read result
+ * @throws ConsensusGroupNotExistException when the specified consensus
group doesn't exist
+ * @throws ConsensusException when read doesn't success with other reasons
+ */
+ DataSet read(ConsensusGroupId groupId, IConsensusRequest request) throws
ConsensusException;
// multi consensus group API
/**
* Require the <em>local node</em> to create a Peer and become a member of
the given consensus
* group. This node will prepare and initialize local statemachine {@link
IStateMachine} and other
- * data structures. After this method returns, we can call {@link
#addPeer(ConsensusGroupId,
+ * data structures. After this method returns, we can call {@link
#addRemotePeer(ConsensusGroupId,
* Peer)} to notify original group that this new Peer is prepared to be
added into the latest
- * configuration. createPeer should be called on a node that does not
contain any peer of the
+ * configuration. createLocalPeer should be called on a node that does not
contain any peer of the
* consensus group, to avoid one node having more than one replica.
*
- * @param groupId the consensus group this Peer belongs
+ * @param groupId the consensus group this peer belongs
* @param peers other known peers in this group
+ * @throws ConsensusGroupAlreadyExistException when the specified consensus
group already exists
+ * @throws IllegalPeerNumException when the peer num is illegal. The
exception is that it is legal
+ * to pass an empty list for RaftConsensus
+ * @throws IllegalPeerEndpointException when peers don't contain local node.
The exception is that
+ * it is legal to pass an empty list for RaftConsensus
+ * @throws ConsensusException when createLocalPeer doesn't success with
other reasons
*/
- ConsensusGenericResponse createPeer(ConsensusGroupId groupId, List<Peer>
peers);
+ void createLocalPeer(ConsensusGroupId groupId, List<Peer> peers) throws
ConsensusException;
/**
* When the <em>local node</em> is no longer a member of the given consensus
group, call this
* method to do cleanup works. This method will close local statemachine
{@link IStateMachine},
- * delete local data and do other cleanup works. Be sure this method is
called after successfully
- * removing this peer from current consensus group configuration (by calling
{@link
- * #removePeer(ConsensusGroupId, Peer)} or {@link
#changePeer(ConsensusGroupId, List)}).
+ * delete local data and do other cleanup works. deleteLocalPeer should be
called after
+ * successfully removing this peer from current consensus group
configuration (by calling {@link
+ * #removeRemotePeer(ConsensusGroupId, Peer)}).
*
- * @param groupId the consensus group this Peer used to belong
+ * @param groupId the consensus group this peer used to belong
+ * @throws ConsensusGroupAlreadyExistException when the specified consensus
group doesn't exist
+ * @throws ConsensusException when deleteLocalPeer doesn't success with
other reasons
*/
- ConsensusGenericResponse deletePeer(ConsensusGroupId groupId);
+ void deleteLocalPeer(ConsensusGroupId groupId) throws ConsensusException;
// single consensus group API
/**
* Tell the group that a new Peer is prepared to be added into this group.
Call {@link
- * #createPeer(ConsensusGroupId, List)} on the new Peer before calling this
method. When this
+ * #createLocalPeer(ConsensusGroupId, List)} on the new Peer before calling
this method. When this
* method returns, the group data should be already transmitted to the new
Peer. That is, the new
* peer is available to answer client requests by the time this method
successfully returns.
- * addPeer should be called on a living peer of the consensus group. For
example: We'd like to add
- * a peer D to (A, B, C) group. We need to execute addPeer in A, B or C.
+ * addRemotePeer should be called on a living peer of the consensus group.
For example: We'd like
+ * to add a peer D to (A, B, C) group. We need to execute addPeer in A, B or
C.
*
* @param groupId the consensus group this peer belongs
* @param peer the newly added peer
+ * @throws PeerAlreadyInConsensusGroupException when the peer has been added
into this consensus
+ * group
+ * @throws ConsensusException when addRemotePeer doesn't success with other
reasons
*/
- ConsensusGenericResponse addPeer(ConsensusGroupId groupId, Peer peer);
+ void addRemotePeer(ConsensusGroupId groupId, Peer peer) throws
ConsensusException;
/**
* Tell the group to remove an active Peer. The removed peer can no longer
answer group requests
- * when this method successfully returns. Call {@link
#deletePeer(ConsensusGroupId)} on the
- * removed Peer to do cleanup jobs after this method successfully returns.
removePeer should be
- * called on a living peer of its consensus group. For example: a group has
A, B, C. We'd like to
- * remove C, in case C is dead, the removePeer should be sent to A or B.
+ * when this method successfully returns. Call {@link
#deleteLocalPeer(ConsensusGroupId)} on the
+ * removed Peer to do cleanup jobs after this method successfully returns.
removeRemotePeer should
+ * be called on a living peer of its consensus group. For example: a group
has A, B, C. We'd like
+ * to remove C, in case C is dead, the removePeer should be sent to A or B.
*
* @param groupId the consensus group this peer belongs
* @param peer the peer to be removed
+ * @throws PeerNotInConsensusGroupException when the peer hasn't yet joined
this consensus group
+ * @throws ConsensusException when removeRemotePeer doesn't success with
other reasons
*/
- ConsensusGenericResponse removePeer(ConsensusGroupId groupId, Peer peer);
+ void removeRemotePeer(ConsensusGroupId groupId, Peer peer) throws
ConsensusException;
+
+ // management API
/**
- * Tell the group to update an active Peer. The modifiable part of {@link
Peer} is TEndPoint.
+ * Transfer the leadership to other peer to meet some load balancing needs.
*
- * @param groupId the consensus group this peer belongs
- * @param oldPeer the peer to be updated
- * @param newPeer the peer to be updated to
+ * @param groupId the consensus group which should execute this command
+ * @param newLeader the target leader peer
+ * @throws ConsensusGroupAlreadyExistException when the specified consensus
group doesn't exist
Review Comment:
```suggestion
* @throws ConsensusGroupDoesNotExistException when the specified
consensus group doesn't exist
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
