This is an automated email from the ASF dual-hosted git repository. ningjiang pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/incubator-servicecomb-saga.git
commit b8d1a2e36500a02ee175cd803c4de09b37b8b31b Author: Daniel Qian <chanjars...@gmail.com> AuthorDate: Sun Mar 25 19:18:52 2018 +0800 SCB-452 Write java doc for some class --- .../saga/alpha/core/TxEventRepository.java | 83 ++++++++++++++++++++++ .../saga/omega/context/annotations/SagaStart.java | 10 +++ .../omega/transaction/annotations/Compensable.java | 29 ++++++++ 3 files changed, 122 insertions(+) diff --git a/alpha/alpha-core/src/main/java/org/apache/servicecomb/saga/alpha/core/TxEventRepository.java b/alpha/alpha-core/src/main/java/org/apache/servicecomb/saga/alpha/core/TxEventRepository.java index 0af6fb5..4b6c997 100644 --- a/alpha/alpha-core/src/main/java/org/apache/servicecomb/saga/alpha/core/TxEventRepository.java +++ b/alpha/alpha-core/src/main/java/org/apache/servicecomb/saga/alpha/core/TxEventRepository.java @@ -19,21 +19,104 @@ package org.apache.servicecomb.saga.alpha.core; import java.util.List; import java.util.Optional; +import org.apache.servicecomb.saga.common.EventType; +/** + * Repository for {@link TxEvent} + */ public interface TxEventRepository { + + /** + * Save a {@link TxEvent}. + * + * @param event + */ void save(TxEvent event); + /** + * Find a {@link TxEvent} which satisfies below requirements: + * + * <ol> + * <li>{@link TxEvent#type} is {@link EventType#TxAbortedEvent}</li> + * <li>There are no {@link TxEvent} which has the same {@link TxEvent#globalTxId} and {@link TxEvent#type} is {@link EventType#TxEndedEvent} or {@link EventType#SagaEndedEvent}</li> + * </ol> + * @return + */ Optional<TxEvent> findFirstAbortedGlobalTransaction(); + /** + * Find timeout {@link TxEvent}s. A timeout TxEvent satisfies below requirements: + * + * <ol> + * <li>{@link TxEvent#type} is {@link EventType#TxStartedEvent} or {@link EventType#SagaStartedEvent}</li> + * <li>Current time greater than {@link TxEvent#expiryTime}</li> + * <li>There are no corresponding {@link TxEvent} which type is <code>TxEndedEvent</code> or <code>SagaEndedEvent</code></li> + * </ol> + * + * @return + */ List<TxEvent> findTimeoutEvents(); + /** + * Find a {@link TxEvent} which satisfies below requirements: + * <ol> + * <li>{@link TxEvent#type} is {@link EventType#TxStartedEvent}</li> + * <li>{@link TxEvent#globalTxId} equals to param <code>globalTxId</code></li> + * <li>{@link TxEvent#localTxId} equals to param <code>localTxId</code></li> + * </ol> + * + * @param globalTxId + * @param localTxId + * @return {@link TxEvent} + */ Optional<TxEvent> findTxStartedEventToCompensate(String globalTxId, String localTxId); + /** + * Find {@link TxEvent}s which satisfy below requirements: + * <ol> + * <li>{@link TxEvent#globalTxId} equals to param <code>globalTxId</code></li> + * <li>{@link TxEvent#type} equals to param <code>type</code></li> + * </ol> + * + * @param globalTxId globalTxId to search for + * @param type event type to search for + * @return + */ List<TxEvent> findTransactions(String globalTxId, String type); + /** + * Find {@link TxEvent}s which satisfy below requirements: + * <ol> + * <li>{@link TxEvent#surrogateId} greater than param <code>id</code></li> + * <li>{@link TxEvent#type} equals to param <code>type</code></li> + * <li>There is a corresponding <code>TxAbortedEvent</code></li> + * <li>There is no coresponding <code>TxCompensatedEvent</code></li> + * </ol> + * + * @param id + * @param type + * @return + */ List<TxEvent> findFirstUncompensatedEventByIdGreaterThan(long id, String type); + /** + * Find first {@link TxEvent} which satisfies below requirements: + * + * <ol> + * <li>{@link TxEvent#type} equals to param <code>type</code></li> + * <li>{@link TxEvent#surrogateId} greater than param <code>id</code></li> + * </ol> + * + * @param id + * @param type + * @return + */ Optional<TxEvent> findFirstCompensatedEventByIdGreaterThan(long id, String type); + /** + * Delete duplicated {@link TxEvent}s which {@link TxEvent#type} equals param <code>type</code>. + * + * @param type event type + */ void deleteDuplicateEvents(String type); } diff --git a/omega/omega-context/src/main/java/org/apache/servicecomb/saga/omega/context/annotations/SagaStart.java b/omega/omega-context/src/main/java/org/apache/servicecomb/saga/omega/context/annotations/SagaStart.java index 7937061..8b68618 100644 --- a/omega/omega-context/src/main/java/org/apache/servicecomb/saga/omega/context/annotations/SagaStart.java +++ b/omega/omega-context/src/main/java/org/apache/servicecomb/saga/omega/context/annotations/SagaStart.java @@ -23,8 +23,18 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Retention; import java.lang.annotation.Target; +/** + * Indicates the annotated method will start a saga. + */ @Retention(RUNTIME) @Target(METHOD) public @interface SagaStart { + + /** + * Saga timeout, in seconds. <br> + * Default value is 0, which means never timeout. + * + * @return + */ int timeout() default 0; } diff --git a/omega/omega-transaction/src/main/java/org/apache/servicecomb/saga/omega/transaction/annotations/Compensable.java b/omega/omega-transaction/src/main/java/org/apache/servicecomb/saga/omega/transaction/annotations/Compensable.java index c6bbfb6..11ba7c7 100644 --- a/omega/omega-transaction/src/main/java/org/apache/servicecomb/saga/omega/transaction/annotations/Compensable.java +++ b/omega/omega-transaction/src/main/java/org/apache/servicecomb/saga/omega/transaction/annotations/Compensable.java @@ -22,10 +22,39 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Indicates the annotated method will start a sub-transaction. <br> + * A <code>@Compensable</code> method should satisfy below requirements: + * <ol> + * <li>all parameters are serialized</li> + * <li>is idempotent</li> + * <li>the object instance which @Compensable method resides in should be stateless</li> + * <li>if compensationMethod exists, both methods must be commutative, see this <a href="https://servicecomb.incubator.apache.org/docs/distributed_saga_2/">link</a>.</li> + * </ol> + */ @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface Compensable { + + /** + * Compensation method name, should not be null.<br> + * A compensation method should satisfy below requirements: + * <ol> + * <li>has same parameter list as @Compensable method's</li> + * <li>all parameters are serialized</li> + * <li>is idempotent</li> + * <li>be in the same class as @Compensable method is in</li> + * </ol> + * + * @return + */ String compensationMethod(); + /** + * <code>@Compensable</code> method timeout, in seconds. <br> + * Default value is 0, which means never timeout. + * + * @return + */ int timeout() default 0; } -- To stop receiving notification emails like this one, please contact ningji...@apache.org.