servicecomb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From GitBox <...@apache.org>
Subject [GitHub] WillemJiang closed pull request #166: [SCB-452] Write java doc for some class and some refactoring.
Date Mon, 02 Apr 2018 03:22:43 GMT
WillemJiang closed pull request #166: [SCB-452] Write java doc for some class and some refactoring.
URL: https://github.com/apache/incubator-servicecomb-saga/pull/166
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/alpha/alpha-core/src/main/java/org/apache/servicecomb/saga/alpha/core/EventScanner.java
b/alpha/alpha-core/src/main/java/org/apache/servicecomb/saga/alpha/core/EventScanner.java
index a52ebe5a..d3fba313 100644
--- a/alpha/alpha-core/src/main/java/org/apache/servicecomb/saga/alpha/core/EventScanner.java
+++ b/alpha/alpha-core/src/main/java/org/apache/servicecomb/saga/alpha/core/EventScanner.java
@@ -21,7 +21,6 @@
 import static org.apache.servicecomb.saga.alpha.core.TaskStatus.NEW;
 import static org.apache.servicecomb.saga.common.EventType.SagaEndedEvent;
 import static org.apache.servicecomb.saga.common.EventType.TxAbortedEvent;
-import static org.apache.servicecomb.saga.common.EventType.TxCompensatedEvent;
 import static org.apache.servicecomb.saga.common.EventType.TxEndedEvent;
 import static org.apache.servicecomb.saga.common.EventType.TxStartedEvent;
 
@@ -94,8 +93,8 @@ private void updateTimeoutStatus() {
   }
 
   private void saveUncompensatedEventsToCommands() {
-    eventRepository.findFirstUncompensatedEventByIdGreaterThan(nextEndedEventId, TxEndedEvent.name())
-        .forEach(event -> {
+    eventRepository.findFirstUncompensatedEventByIdGreaterThan(nextEndedEventId)
+        .ifPresent(event -> {
           log.info("Found uncompensated event {}", event);
           nextEndedEventId = event.id();
           commandRepository.saveCompensationCommands(event.globalTxId());
@@ -103,7 +102,7 @@ private void saveUncompensatedEventsToCommands() {
   }
 
   private void updateCompensatedCommands() {
-    eventRepository.findFirstCompensatedEventByIdGreaterThan(nextCompensatedEventId, TxCompensatedEvent.name())
+    eventRepository.findFirstCompensatedEventByIdGreaterThan(nextCompensatedEventId)
         .ifPresent(event -> {
           log.info("Found compensated event {}", event);
           nextCompensatedEventId = event.id();
@@ -135,7 +134,7 @@ private void abortTimeoutEvents() {
       eventRepository.save(toTxAbortedEvent(timeout));
 
       if (timeout.type().equals(TxStartedEvent.name())) {
-        eventRepository.findTxStartedEventToCompensate(timeout.globalTxId(), timeout.localTxId())
+        eventRepository.findTxStartedEvent(timeout.globalTxId(), timeout.localTxId())
             .ifPresent(omegaCallback::compensate);
       }
     });
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 0af6fb5f..9eceaddd 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,103 @@
 
 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();
 
-  Optional<TxEvent> findTxStartedEventToCompensate(String globalTxId, String localTxId);
+  /**
+   * 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> findTxStartedEvent(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);
 
-  List<TxEvent> findFirstUncompensatedEventByIdGreaterThan(long id, String type);
+  /**
+   * Find a {@link TxEvent} which satisfies below requirements:
+   * <ol>
+   *   <li>{@link TxEvent#type} equals to {@link EventType#TxEndedEvent}</li>
+   *   <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
+   * @return
+   */
+  Optional<TxEvent> findFirstUncompensatedEventByIdGreaterThan(long id);
 
-  Optional<TxEvent> findFirstCompensatedEventByIdGreaterThan(long id, String type);
+  /**
+   * Find a {@link TxEvent} which satisfies below requirements:
+   *
+   * <ol>
+   *   <li>{@link TxEvent#type} equals to {@link EventType#TxCompensatedEvent}</li>
+   *   <li>{@link TxEvent#surrogateId} greater than param <code>id</code></li>
+   * </ol>
+   *
+   * @param id
+   * @return
+   */
+  Optional<TxEvent> findFirstCompensatedEventByIdGreaterThan(long id);
 
+  /**
+   * 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/alpha/alpha-core/src/test/java/org/apache/servicecomb/saga/alpha/core/TxConsistentServiceTest.java
b/alpha/alpha-core/src/test/java/org/apache/servicecomb/saga/alpha/core/TxConsistentServiceTest.java
index d2209940..da360665 100644
--- a/alpha/alpha-core/src/test/java/org/apache/servicecomb/saga/alpha/core/TxConsistentServiceTest.java
+++ b/alpha/alpha-core/src/test/java/org/apache/servicecomb/saga/alpha/core/TxConsistentServiceTest.java
@@ -59,7 +59,7 @@ public void save(TxEvent event) {
     }
 
     @Override
-    public Optional<TxEvent> findTxStartedEventToCompensate(String globalTxId, String
localTxId) {
+    public Optional<TxEvent> findTxStartedEvent(String globalTxId, String localTxId)
{
       return events.stream()
           .filter(event -> globalTxId.equals(event.globalTxId()) && localTxId.equals(event.localTxId()))
           .findFirst();
@@ -73,12 +73,12 @@ public void save(TxEvent event) {
     }
 
     @Override
-    public List<TxEvent> findFirstUncompensatedEventByIdGreaterThan(long id, String
type) {
-      return emptyList();
+    public Optional<TxEvent> findFirstUncompensatedEventByIdGreaterThan(long id) {
+      return Optional.empty();
     }
 
     @Override
-    public Optional<TxEvent> findFirstCompensatedEventByIdGreaterThan(long id, String
type) {
+    public Optional<TxEvent> findFirstCompensatedEventByIdGreaterThan(long id) {
       return Optional.empty();
     }
 
diff --git a/alpha/alpha-server/src/main/java/org/apache/servicecomb/saga/alpha/server/SpringTxEventRepository.java
b/alpha/alpha-server/src/main/java/org/apache/servicecomb/saga/alpha/server/SpringTxEventRepository.java
index d6ea21c3..cae64567 100644
--- a/alpha/alpha-server/src/main/java/org/apache/servicecomb/saga/alpha/server/SpringTxEventRepository.java
+++ b/alpha/alpha-server/src/main/java/org/apache/servicecomb/saga/alpha/server/SpringTxEventRepository.java
@@ -23,6 +23,11 @@
 import org.apache.servicecomb.saga.alpha.core.TxEvent;
 import org.apache.servicecomb.saga.alpha.core.TxEventRepository;
 import org.springframework.data.domain.PageRequest;
+import org.springframework.util.CollectionUtils;
+
+import javax.swing.text.html.Option;
+
+import static org.apache.servicecomb.saga.common.EventType.TxCompensatedEvent;
 
 class SpringTxEventRepository implements TxEventRepository {
   private static final PageRequest SINGLE_TX_EVENT_REQUEST = new PageRequest(0, 1);
@@ -48,7 +53,7 @@ public void save(TxEvent event) {
   }
 
   @Override
-  public Optional<TxEvent> findTxStartedEventToCompensate(String globalTxId, String
localTxId) {
+  public Optional<TxEvent> findTxStartedEvent(String globalTxId, String localTxId)
{
     return eventRepo.findFirstStartedEventByGlobalTxIdAndLocalTxId(globalTxId, localTxId);
   }
 
@@ -58,13 +63,17 @@ public void save(TxEvent event) {
   }
 
   @Override
-  public List<TxEvent> findFirstUncompensatedEventByIdGreaterThan(long id, String type)
{
-    return eventRepo.findFirstByTypeAndSurrogateIdGreaterThan(type, id, SINGLE_TX_EVENT_REQUEST);
+  public Optional<TxEvent> findFirstUncompensatedEventByIdGreaterThan(long id) {
+    List<TxEvent> result = eventRepo.findFirstUncompensatedEventByIdGreaterThan(id,
SINGLE_TX_EVENT_REQUEST);
+    if (CollectionUtils.isEmpty(result)) {
+      return Optional.empty();
+    }
+    return Optional.of(result.get(0));
   }
 
   @Override
-  public Optional<TxEvent> findFirstCompensatedEventByIdGreaterThan(long id, String
type) {
-    return eventRepo.findFirstByTypeAndSurrogateIdGreaterThan(type, id);
+  public Optional<TxEvent> findFirstCompensatedEventByIdGreaterThan(long id) {
+    return eventRepo.findFirstByTypeAndSurrogateIdGreaterThan(TxCompensatedEvent.name(),
id);
   }
 
   @Override
diff --git a/alpha/alpha-server/src/main/java/org/apache/servicecomb/saga/alpha/server/TxEventEnvelopeRepository.java
b/alpha/alpha-server/src/main/java/org/apache/servicecomb/saga/alpha/server/TxEventEnvelopeRepository.java
index 0eaf0898..470caa57 100644
--- a/alpha/alpha-server/src/main/java/org/apache/servicecomb/saga/alpha/server/TxEventEnvelopeRepository.java
+++ b/alpha/alpha-server/src/main/java/org/apache/servicecomb/saga/alpha/server/TxEventEnvelopeRepository.java
@@ -78,7 +78,7 @@
   List<TxEvent> findStartedEventsWithMatchingEndedButNotCompensatedEvents(String globalTxId);
 
   @Query("SELECT t FROM TxEvent t "
-      + "WHERE t.type = ?1 AND t.surrogateId > ?2 AND EXISTS ( "
+      + "WHERE t.type = 'TxEndedEvent' AND t.surrogateId > ?1 AND EXISTS ( "
       + "  SELECT t1.globalTxId"
       + "  FROM TxEvent t1 "
       + "  WHERE t1.globalTxId = t.globalTxId "
@@ -90,7 +90,7 @@
       + "  AND t2.localTxId = t.localTxId "
       + "  AND t2.type = 'TxCompensatedEvent') "
       + "ORDER BY t.surrogateId ASC")
-  List<TxEvent> findFirstByTypeAndSurrogateIdGreaterThan(String type, long surrogateId,
Pageable pageable);
+  List<TxEvent> findFirstUncompensatedEventByIdGreaterThan(long surrogateId, Pageable
pageable);
 
   Optional<TxEvent> findFirstByTypeAndSurrogateIdGreaterThan(String type, long surrogateId);
 
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 79370611..8b686187 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 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 c6bbfb6b..11ba7c71 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.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;
 }


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services

Mime
View raw message