WJL3333 commented on a change in pull request #3987: URL: https://github.com/apache/rocketmq/pull/3987#discussion_r826586924
########## File path: apis/src/main/java/org/apache/rocketmq/apis/message/MessageBuilder.java ########## @@ -0,0 +1,93 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.rocketmq.apis.message; + +import java.util.Collection; +import java.util.Map; +import org.apache.rocketmq.apis.producer.Producer; + +/** + * Builder to config {@link Message}. + */ +public interface MessageBuilder { + /** + * Set the topic for message. + * + * @param topic topic for the message. + * @return the message builder instance. + */ + MessageBuilder setTopic(String topic); Review comment: if we remove set prefix the api will be more clean to the developer. ########## File path: apis/src/main/java/org/apache/rocketmq/apis/message/MessageView.java ########## @@ -0,0 +1,116 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.rocketmq.apis.message; + +import java.util.Collection; +import java.util.Map; +import java.util.Optional; +import org.apache.rocketmq.apis.MessageQueue; + +public interface MessageView { + /** + * Get the unique id of message. + * + * @return unique id. + */ + MessageId getMessageId(); + + /** + * Get the topic of message. + * + * @return topic of message. + */ + String getTopic(); + + /** + * Get the {@link MessageQueue} of message. + * + * @return message queue. + */ + MessageQueue getMessageQueue(); + + /** + * Get the position of message in {@link MessageQueue}. + */ + long getOffset(); + + /** + * Get the <strong>deep copy</strong> of message body, which makes the modification of return value does not + * affect the message itself. + * + * @return the <strong>deep copy</strong> of message body. + */ + byte[] getBody(); Review comment: deep copy seems will harm the performance. but there seems no better return type here. ########## File path: apis/src/main/java/org/apache/rocketmq/apis/producer/Producer.java ########## @@ -0,0 +1,132 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.rocketmq.apis.producer; + +import com.google.common.util.concurrent.Service; +import java.util.concurrent.CompletableFuture; +import java.io.Closeable; +import java.util.Collection; +import org.apache.rocketmq.apis.exception.AuthenticationException; +import org.apache.rocketmq.apis.exception.AuthorisationException; +import org.apache.rocketmq.apis.exception.ClientException; +import org.apache.rocketmq.apis.exception.MessageTypeDoesNotMatchException; +import org.apache.rocketmq.apis.exception.PersistenceException; +import org.apache.rocketmq.apis.exception.ProducerClosedAlreadyException; +import org.apache.rocketmq.apis.exception.NetworkConnectionException; +import org.apache.rocketmq.apis.exception.NetworkTimeoutException; +import org.apache.rocketmq.apis.exception.TopicDoesNotExistException; +import org.apache.rocketmq.apis.exception.TransactionCheckerNotSetException; +import org.apache.rocketmq.apis.message.Message; +import org.apache.rocketmq.apis.message.MessageId; + +/** + * Producer is a thread-safe rocketmq client which is used to publish messages. + * + * <p>On account of network timeout or other reasons, rocketmq producer only promised the at-least-once semantics. + * For producer, at-least-once semantics means potentially attempts are made at sending it, messages may be + * duplicated but not lost. + */ +public interface Producer extends Closeable { + /** + * Sends a message synchronously. + * + * <p>This method does not return until it gets the definitive result. + * + * @param message message to send. + * @return the message id assigned to the appointed message. + * @throws TopicDoesNotExistException if the topic of message does not exist. + * @throws AuthorisationException if no permission to send message. + * @throws AuthenticationException if identification could not be recognized by server. + * @throws ProducerClosedAlreadyException if producer is closed already. + * @throws MessageTypeDoesNotMatchException if message type does not match with the topic. + * @throws NetworkTimeoutException if encountered network timeout to communicate with server. + * @throws NetworkConnectionException if there is a network connection problem. + * @throws PersistenceException if encountered persistence failure from server. + */ + MessageId send(Message message) throws ClientException; + + /** + * Sends a transactional message synchronously. + * + * @param message message to send. + * @param transaction transaction to bind. + * @return the message id assigned to the appointed message. + * @throws TopicDoesNotExistException if the topic of message does not exist. + * @throws AuthorisationException if no permission to send message. + * @throws AuthenticationException if identification could not be recognized by server. + * @throws ProducerClosedAlreadyException if producer is closed already. + * @throws MessageTypeDoesNotMatchException if message type does not match with the topic. + * @throws NetworkTimeoutException if encountered network timeout to communicate with server. + * @throws NetworkConnectionException if there is a network connection problem. + * @throws PersistenceException if encountered persistence failure from server. + * @throws TransactionCheckerNotSetException if {@link TransactionChecker} is not set. + */ + MessageId send(Message message, Transaction transaction) throws ClientException; + + /** + * Send a message asynchronously. + * + * <p>This method returns immediately, the result is included in the {@link CompletableFuture}; + * + * @param message message to send. + * @return a future that indicates the result. + */ + CompletableFuture<MessageId> sendAsync(Message message); + + /** + * Send batch messages synchronously. + * + * <p>This method does not return until it gets the definitive result. + * + * <p>All messages to send should have the same topic. + * + * @param messages batch messages to send. + * @return collection indicates the message id assigned to the appointed message, which keep the same order + * messages collection. + * @throws TopicDoesNotExistException if the topic of message does not exist. + * @throws AuthorisationException if no permission to send message. + * @throws AuthenticationException if identification could not be recognized by server. + * @throws ProducerClosedAlreadyException if producer is closed already. + * @throws MessageTypeDoesNotMatchException if message type does not match with the topic. + * @throws NetworkTimeoutException if encountered network timeout to communicate with server. + * @throws NetworkConnectionException if there is a network connection problem. + * @throws PersistenceException if encountered persistence failure from server. + */ + Collection<MessageId> send(Collection<Message> messages) throws ClientException; + + /** + * Begin transaction, which follows the + * <a href="https://en.wikipedia.org/wiki/Two-phase_commit_protocol";>two-phase commit protocol</a>. + * + * @return a transaction entity to execute commit/rollback operation. + * @throws TransactionCheckerNotSetException if {@link TransactionChecker} is not set. + * @throws ProducerClosedAlreadyException if producer is closed already. + */ + Transaction beginTransaction() throws ClientException; + + /** + * Close the producer and release all related resources. + * + * <p>This method does not return until all related resource is released. Once producer is closed, <strong>it could + * not be started once again.</strong> we maintained an FSM (finite-state machine) to record the different states + * for each producer, which is similar to {@link Service.State}. + */ + @SuppressWarnings("UnstableApiUsage") + @Override + void close(); Review comment: will close throw exception here? ########## File path: apis/src/main/java/org/apache/rocketmq/apis/producer/ProducerBuilder.java ########## @@ -0,0 +1,92 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.rocketmq.apis.producer; + +import org.apache.rocketmq.apis.ClientConfiguration; +import org.apache.rocketmq.apis.retry.BackoffRetryPolicy; +import org.apache.rocketmq.apis.exception.AuthenticationException; +import org.apache.rocketmq.apis.exception.AuthorisationException; +import org.apache.rocketmq.apis.exception.ClientException; +import org.apache.rocketmq.apis.exception.NetworkConnectionException; +import org.apache.rocketmq.apis.exception.NetworkTimeoutException; +import org.apache.rocketmq.apis.exception.TopicDoesNotExistException; +import org.apache.rocketmq.apis.message.Message; + +/** + * Builder to config and start {@link Producer}. + */ +public interface ProducerBuilder { + /** + * Set the client configuration for producer. + * + * @param clientConfiguration client's configuration. + * @return the producer builder instance. + */ + ProducerBuilder setClientConfiguration(ClientConfiguration clientConfiguration); + + /** + * Declare topics ahead of message sending/preparation. + * + * <p>Even though the declaration is not essential, we <strong>highly recommend</strong> to declare the topics in + * advance, which could help to discover potential mistakes. + * + * @param topics topics to send/prepare. + * @return the producer builder instance. + */ + ProducerBuilder withTopics(String... topics); + + /** + * Set the threads count for {@link Producer#sendAsync(Message)}. + * + * @return the producer builder instance. + */ + ProducerBuilder setAsyncThreadCount(int count); + + /** + * Set the retry policy to send message. + * + * @param retryPolicy policy to re-send message when failure encountered. + * @return the producer builder instance. + */ + ProducerBuilder setRetryPolicy(BackoffRetryPolicy retryPolicy); Review comment: `RetryPolicy` interface here will be better. ########## File path: apis/src/main/java/org/apache/rocketmq/apis/message/MessageView.java ########## @@ -0,0 +1,116 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.rocketmq.apis.message; + +import java.util.Collection; +import java.util.Map; +import java.util.Optional; +import org.apache.rocketmq.apis.MessageQueue; + +public interface MessageView { Review comment: need java doc here. what is an MessageView ? ########## File path: apis/src/main/java/org/apache/rocketmq/apis/exception/ClientException.java ########## @@ -0,0 +1,32 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.rocketmq.apis.exception; + +public class ClientException extends Exception { Review comment: it seems this is the root Exception for all the rocketmq client exception. when we will throw this exception. if maintainer want to add an exception which kind of exception can extend this clientException. add java doc will be more formal ########## File path: apis/src/main/java/org/apache/rocketmq/apis/message/MessageId.java ########## @@ -0,0 +1,38 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.rocketmq.apis.message; + +/** + * Abstract message id, the implement must override {@link Object#toString()}, which indicates the message id using + * string form. + */ +public interface MessageId { + /** + * Get the version of message id. + * + * @return the version of message id. + */ + MessageIdVersion getVersion(); + + /** + * The implementation <strong>must</strong> override this method, which indicates the message id using string form. + * + * @return string-formed string id. + */ + String toString(); Review comment: this name is the same as the java origin Object.toString. i think we can change the method name. the origin is anti-parttern naming. ########## File path: apis/src/main/java/org/apache/rocketmq/apis/producer/Producer.java ########## @@ -0,0 +1,132 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.rocketmq.apis.producer; + +import com.google.common.util.concurrent.Service; +import java.util.concurrent.CompletableFuture; +import java.io.Closeable; +import java.util.Collection; +import org.apache.rocketmq.apis.exception.AuthenticationException; +import org.apache.rocketmq.apis.exception.AuthorisationException; +import org.apache.rocketmq.apis.exception.ClientException; +import org.apache.rocketmq.apis.exception.MessageTypeDoesNotMatchException; +import org.apache.rocketmq.apis.exception.PersistenceException; +import org.apache.rocketmq.apis.exception.ProducerClosedAlreadyException; +import org.apache.rocketmq.apis.exception.NetworkConnectionException; +import org.apache.rocketmq.apis.exception.NetworkTimeoutException; +import org.apache.rocketmq.apis.exception.TopicDoesNotExistException; +import org.apache.rocketmq.apis.exception.TransactionCheckerNotSetException; +import org.apache.rocketmq.apis.message.Message; +import org.apache.rocketmq.apis.message.MessageId; + +/** + * Producer is a thread-safe rocketmq client which is used to publish messages. + * + * <p>On account of network timeout or other reasons, rocketmq producer only promised the at-least-once semantics. + * For producer, at-least-once semantics means potentially attempts are made at sending it, messages may be + * duplicated but not lost. + */ +public interface Producer extends Closeable { + /** + * Sends a message synchronously. + * + * <p>This method does not return until it gets the definitive result. + * + * @param message message to send. + * @return the message id assigned to the appointed message. + * @throws TopicDoesNotExistException if the topic of message does not exist. + * @throws AuthorisationException if no permission to send message. + * @throws AuthenticationException if identification could not be recognized by server. + * @throws ProducerClosedAlreadyException if producer is closed already. + * @throws MessageTypeDoesNotMatchException if message type does not match with the topic. + * @throws NetworkTimeoutException if encountered network timeout to communicate with server. + * @throws NetworkConnectionException if there is a network connection problem. + * @throws PersistenceException if encountered persistence failure from server. + */ + MessageId send(Message message) throws ClientException; + + /** + * Sends a transactional message synchronously. + * + * @param message message to send. + * @param transaction transaction to bind. + * @return the message id assigned to the appointed message. + * @throws TopicDoesNotExistException if the topic of message does not exist. + * @throws AuthorisationException if no permission to send message. + * @throws AuthenticationException if identification could not be recognized by server. + * @throws ProducerClosedAlreadyException if producer is closed already. + * @throws MessageTypeDoesNotMatchException if message type does not match with the topic. + * @throws NetworkTimeoutException if encountered network timeout to communicate with server. + * @throws NetworkConnectionException if there is a network connection problem. + * @throws PersistenceException if encountered persistence failure from server. + * @throws TransactionCheckerNotSetException if {@link TransactionChecker} is not set. + */ + MessageId send(Message message, Transaction transaction) throws ClientException; + + /** + * Send a message asynchronously. + * + * <p>This method returns immediately, the result is included in the {@link CompletableFuture}; + * + * @param message message to send. + * @return a future that indicates the result. + */ + CompletableFuture<MessageId> sendAsync(Message message); + + /** + * Send batch messages synchronously. + * + * <p>This method does not return until it gets the definitive result. + * + * <p>All messages to send should have the same topic. + * + * @param messages batch messages to send. + * @return collection indicates the message id assigned to the appointed message, which keep the same order + * messages collection. + * @throws TopicDoesNotExistException if the topic of message does not exist. + * @throws AuthorisationException if no permission to send message. + * @throws AuthenticationException if identification could not be recognized by server. + * @throws ProducerClosedAlreadyException if producer is closed already. + * @throws MessageTypeDoesNotMatchException if message type does not match with the topic. + * @throws NetworkTimeoutException if encountered network timeout to communicate with server. + * @throws NetworkConnectionException if there is a network connection problem. + * @throws PersistenceException if encountered persistence failure from server. + */ + Collection<MessageId> send(Collection<Message> messages) throws ClientException; + + /** + * Begin transaction, which follows the + * <a href="https://en.wikipedia.org/wiki/Two-phase_commit_protocol";>two-phase commit protocol</a>. + * + * @return a transaction entity to execute commit/rollback operation. + * @throws TransactionCheckerNotSetException if {@link TransactionChecker} is not set. + * @throws ProducerClosedAlreadyException if producer is closed already. + */ + Transaction beginTransaction() throws ClientException; Review comment: maybe an interface extand producer add some Transaction relate method will be better. ########## File path: apis/src/main/java/org/apache/rocketmq/apis/producer/ProducerBuilder.java ########## @@ -0,0 +1,92 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.rocketmq.apis.producer; + +import org.apache.rocketmq.apis.ClientConfiguration; +import org.apache.rocketmq.apis.retry.BackoffRetryPolicy; +import org.apache.rocketmq.apis.exception.AuthenticationException; +import org.apache.rocketmq.apis.exception.AuthorisationException; +import org.apache.rocketmq.apis.exception.ClientException; +import org.apache.rocketmq.apis.exception.NetworkConnectionException; +import org.apache.rocketmq.apis.exception.NetworkTimeoutException; +import org.apache.rocketmq.apis.exception.TopicDoesNotExistException; +import org.apache.rocketmq.apis.message.Message; + +/** + * Builder to config and start {@link Producer}. + */ +public interface ProducerBuilder { + /** + * Set the client configuration for producer. + * + * @param clientConfiguration client's configuration. + * @return the producer builder instance. + */ + ProducerBuilder setClientConfiguration(ClientConfiguration clientConfiguration); Review comment: same as Messagebuilder. no set prefix will make api more clean in fluent api call. ########## File path: apis/src/main/java/org/apache/rocketmq/apis/producer/ProducerBuilder.java ########## @@ -0,0 +1,92 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.rocketmq.apis.producer; + +import org.apache.rocketmq.apis.ClientConfiguration; +import org.apache.rocketmq.apis.retry.BackoffRetryPolicy; +import org.apache.rocketmq.apis.exception.AuthenticationException; +import org.apache.rocketmq.apis.exception.AuthorisationException; +import org.apache.rocketmq.apis.exception.ClientException; +import org.apache.rocketmq.apis.exception.NetworkConnectionException; +import org.apache.rocketmq.apis.exception.NetworkTimeoutException; +import org.apache.rocketmq.apis.exception.TopicDoesNotExistException; +import org.apache.rocketmq.apis.message.Message; + +/** + * Builder to config and start {@link Producer}. + */ +public interface ProducerBuilder { + /** + * Set the client configuration for producer. + * + * @param clientConfiguration client's configuration. + * @return the producer builder instance. + */ + ProducerBuilder setClientConfiguration(ClientConfiguration clientConfiguration); + + /** + * Declare topics ahead of message sending/preparation. + * + * <p>Even though the declaration is not essential, we <strong>highly recommend</strong> to declare the topics in + * advance, which could help to discover potential mistakes. + * + * @param topics topics to send/prepare. + * @return the producer builder instance. + */ + ProducerBuilder withTopics(String... topics); + + /** + * Set the threads count for {@link Producer#sendAsync(Message)}. + * + * @return the producer builder instance. + */ + ProducerBuilder setAsyncThreadCount(int count); + + /** + * Set the retry policy to send message. + * + * @param retryPolicy policy to re-send message when failure encountered. + * @return the producer builder instance. + */ + ProducerBuilder setRetryPolicy(BackoffRetryPolicy retryPolicy); + + /** + * Set the transaction checker for producer. + * + * @param checker transaction checker. + * @return the produce builder instance. + */ + ProducerBuilder setTransactionChecker(TransactionChecker checker); + + /** + * Finalize the build of {@link Producer} instance and start. + * + * <p>The producer does a series of preparatory work during startup, which could help to identify more unexpected + * error earlier. + * + * <p>Especially, if this method is invoked more than once, different producer will be created and started. + * + * @return the producer instance. + * @throws TopicDoesNotExistException if there are nonexistent topic(s). + * @throws AuthorisationException if no permission to communicate with server. + * @throws AuthenticationException if identification could not be recognized by server. + * @throws NetworkTimeoutException if encountered network timeout to communicate with server. + * @throws NetworkConnectionException if there is a network connection problem. + */ + Producer start() throws ClientException; Review comment: may be move start to the producer. some case will just build the producer without start. ########## File path: apis/src/main/java/org/apache/rocketmq/apis/producer/Transaction.java ########## @@ -0,0 +1,50 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.rocketmq.apis.producer; + +/** + * An entity to describe an independent transaction, which follows + * <a href="https://en.wikipedia.org/wiki/Two-phase_commit_protocol";>two-phase commit protocol</a>. + * + * <p>once {@link Transaction#commit()} or {@link Transaction#rollback()} is invoked, subsequent commit or rollback in + * {@link Transaction} is ignored by client. + * + * <p>Neither of {@link Transaction#commit()} and {@link Transaction#rollback()} ensures the success on account of + * network timeout or other issues, that's why it does not make any sense to execute {@link Transaction#commit()} or + * {@link Transaction#rollback()} after is has been executed once already. The suspended transaction will be + * solved by {@link TransactionChecker}. + */ +public interface Transaction { + /** + * Try to commit the transaction, which would expose the message before the transaction is closed. + * + * <p>We don't ensure this operation is successful even though no exception is thrown after invocation, + * <strong>actually we omit the exception on purpose because {@link TransactionChecker} is the unique right way + * to solve the suspended transaction rather than commit or roll-back repeatedly.</strong> + */ + void commit(); Review comment: will commit throw exception need the caller process? ########## File path: apis/src/main/java/org/apache/rocketmq/apis/message/MessageView.java ########## @@ -0,0 +1,116 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.rocketmq.apis.message; + +import java.util.Collection; +import java.util.Map; +import java.util.Optional; +import org.apache.rocketmq.apis.MessageQueue; + +public interface MessageView { + /** + * Get the unique id of message. + * + * @return unique id. + */ + MessageId getMessageId(); + + /** + * Get the topic of message. + * + * @return topic of message. + */ + String getTopic(); + + /** + * Get the {@link MessageQueue} of message. + * + * @return message queue. + */ + MessageQueue getMessageQueue(); + + /** + * Get the position of message in {@link MessageQueue}. + */ + long getOffset(); + + /** + * Get the <strong>deep copy</strong> of message body, which makes the modification of return value does not + * affect the message itself. + * + * @return the <strong>deep copy</strong> of message body. + */ + byte[] getBody(); Review comment: how about ByteBuffer here which can be set as unmodifable -- 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]
