You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by ni...@apache.org on 2018/04/02 03:22:44 UTC
[incubator-servicecomb-saga] 01/04: SCB-452 Write java doc for some
class
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 <ch...@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
ningjiang@apache.org.