Merge pull request #3 from leancloud/fix/hook

hook 1.3

Author: ylgrgyq

game-hook-base/pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>cn.leancloud.play</groupId>
     <artifactId>game-hook-base</artifactId>
-    <version>1.3-SNAPSHOT</version>
+    <version>1.3</version>
 
     <properties>
         <clojure.version>1.10.0</clojure.version>

game-hook-base/src/main/java/cn/leancloud/play/hook/AbstractGameHook.java

@@ -3,6 +3,17 @@
 import cn.leancloud.play.hook.context.*;
 
 public abstract class AbstractGameHook implements GameHook{
+    private final HookedRoom room;
+
+    public AbstractGameHook(HookedRoom room) {
+        this.room = room;
+    }
+
+    @Override
+    public HookedRoom getHookedRoom() {
+        return room;
+    }
+
     @Override
     public void onCreateRoom(CreateRoomContext ctx) {
         ctx.continueProcess();

game-hook-base/src/main/java/cn/leancloud/play/hook/GameHook.java

@@ -3,6 +3,13 @@
 import cn.leancloud.play.hook.context.*;
 
 public interface GameHook {
+    /**
+     * 获取与当前 Game Hook 绑定的 Room 实例
+     *
+     * @return 绑定的 Room 实例
+     */
+    HookedRoom getHookedRoom();
+
     /**
      * 创建房间前调用
      *

game-hook-base/src/main/java/cn/leancloud/play/hook/HookedRoom.java

@@ -6,11 +6,25 @@
 
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.ScheduledExecutorService;
 
 /**
  * 与 Hook 绑定的房间实例，用于获取房间信息以及对房间进行操作。
  */
 public interface HookedRoom {
+    /**
+     * 获取一个 ScheduledExecutorService 用于将某个任务交给与当前房间绑定的线程来执行。在该线程上能保证任务运行期间，房间
+     * 属性不会发生变化，但需要任务尽快执行完以避免过长时间的阻塞线程。
+     *
+     * 因为性能原因，返回的 ScheduledExecutorService 时间精度为 20ms，比如布置一个任务 30ms 后执行则实际
+     * 执行时间在 30ms ~ 50ms 之间，即不会早于预期执行时间且与预期执行时间最大偏差为 20ms。
+     *
+     * 返回的 ScheduledExecutorService 不能被 shutdown，执行 shutdown 没有任何作用。
+     *
+     * @return ScheduledExecutorService
+     */
+    ScheduledExecutorService getScheduler();
+
     /**
      * 获取房间名称
      *
@@ -100,24 +114,24 @@ public interface HookedRoom {
      * 更改房间玩家自定义属性
      *
      * @param targetActorId 目标玩家 Actor Id
-     * @param valuesToSet 待修改的玩家自定义属性
-     * @param expectedValues 设置 CAS 操作用于匹配的玩家自定义属性。设置了用于匹配的玩家自定义属性后，只有当玩家自定义属性符合
+     * @param valuesToSet 待修改的玩家自定义属性，不能为 null
+     * @param expectedValues 不能为 null。设置 CAS 操作用于匹配的玩家自定义属性。设置了用于匹配的玩家自定义属性后，只有当玩家自定义属性符合
      *                       匹配的值后更新玩家自定义属性操作才会生效。
      */
     void updatePlayerProperty(int targetActorId, Map<String, Object> valuesToSet, Map<String, Object> expectedValues);
 
     /**
      * 更改房间自定义属性
      *
-     * @param valuesToSet 待修改的房间自定义属性
-     * @param expectedValues 进行 CAS 操作时使用，用于匹配的房间自定义属性。设置了用于匹配的自定义属性后，只有当房间自定义属性符合
+     * @param valuesToSet 待修改的房间自定义属性, 不能为 null
+     * @param expectedValues 不能为 null。进行 CAS 操作时使用，用于匹配的房间自定义属性。设置了用于匹配的自定义属性后，只有当房间自定义属性符合
      *                       匹配的值后更新房间自定义属性操作才会生效。
      */
     void updateRoomProperty(Map<String, Object> valuesToSet, Map<String, Object> expectedValues);
 
     /**
      * 更改房间系统属性
-     * @param property 待修改的系统属性
+     * @param property 待修改的系统属性，不能为 null
      * @param <K> 具体要改的系统属性
      * @param <V> 待修改后的值
      */
@@ -133,20 +147,20 @@ public interface HookedRoom {
     /**
      * 发送事件给目标 Actor。
      *
-     * @param toActorsIds 目标 Actor Id 列表
-     * @param fromActorId 发送事件的 Actor Id
-     * @param data 事件数据
-     * @param options 发送事件配置选项
+     * @param toActorsIds 目标 Actor Id 列表，不能为 null
+     * @param fromActorId 发送事件的 Actor Id，为 0 表示由系统发出
+     * @param data 事件数据，不能为 null
+     * @param options 发送事件配置选项，不能为 null
      */
     void raiseRpcToActors(List<Integer> toActorsIds, int fromActorId, byte[] data, RaiseRpcOptions options);
 
     /**
      * 发送事件给目标接收组
      *
-     * @param toReceiverGroup 目标接收组
-     * @param fromActorId 发送事件的 Actor Id
-     * @param data 事件数据
-     * @param options 发送事件配置选项
+     * @param toReceiverGroup 目标接收组，不能为 null
+     * @param fromActorId 发送事件的 Actor Id，为 0 表示由系统发出
+     * @param data 事件数据，不能为 null
+     * @param options 发送事件配置选项，不能为 null
      */
     void raiseRpcToReceiverGroup(ReceiverGroup toReceiverGroup, int fromActorId, byte[] data, RaiseRpcOptions options);
 }

game-hook-base/src/main/java/cn/leancloud/play/hook/context/AbstractDeferrableContext.java

@@ -1,7 +1,6 @@
 package cn.leancloud.play.hook.context;
 
 import cn.leancloud.play.hook.HookResponse;
-import cn.leancloud.play.hook.HookedRoom;
 import cn.leancloud.play.hook.request.RoomRequest;
 
 import java.util.concurrent.CompletableFuture;
@@ -10,8 +9,8 @@ abstract class AbstractDeferrableContext<T extends RoomRequest>
         extends AbstractOperationContext<T>
         implements DeferableContext<T>, SkipableContext<T>{
 
-    AbstractDeferrableContext(T req, HookedRoom hookedRoom, CompletableFuture<HookResponse<T>> future) {
-        super(req, hookedRoom, future);
+    AbstractDeferrableContext(T req, CompletableFuture<HookResponse<T>> future) {
+        super(req, future);
     }
 
     @Override

game-hook-base/src/main/java/cn/leancloud/play/hook/context/AbstractOperationContext.java

@@ -1,7 +1,6 @@
 package cn.leancloud.play.hook.context;
 
 import cn.leancloud.play.hook.HookResponse;
-import cn.leancloud.play.hook.HookedRoom;
 import cn.leancloud.play.hook.Reason;
 import cn.leancloud.play.hook.request.RoomRequest;
 
@@ -11,18 +10,16 @@
 abstract class AbstractOperationContext<T extends RoomRequest> implements Context<T> {
     private final CompletableFuture<HookResponse<T>> future;
     private final T req;
-    private final HookedRoom hookedRoom;
 
     private ContextStatus status;
 
-    AbstractOperationContext(T req, HookedRoom hookedRoom, CompletableFuture<HookResponse<T>> future) {
+    AbstractOperationContext(T req, CompletableFuture<HookResponse<T>> future) {
         Objects.requireNonNull(req);
         Objects.requireNonNull(future);
 
         this.req = req;
         this.future = future;
         this.status = ContextStatus.NEW;
-        this.hookedRoom = hookedRoom;
     }
 
     @Override
@@ -35,11 +32,6 @@ public T getRequest() {
         return req;
     }
 
-    @Override
-    public HookedRoom getHookedRoom() {
-        return hookedRoom;
-    }
-
     @Override
     public void continueProcess() {
         updateStatusWhenNotProcessed(ContextStatus.CONTINUED);
@@ -52,11 +44,16 @@ public void rejectProcess(Reason reason) {
         completeHookFuture(HookResponse.reject(reason));
     }
 
+    @Override
+    public boolean isProcessed(){
+        return status.getCode() > ContextStatus.DEFERRED.getCode();
+    }
+
     void updateStatusWhenNotProcessed(ContextStatus newStatus) {
-        if (status == ContextStatus.NEW || status == ContextStatus.DEFERRED) {
-            status = newStatus;
-        } else {
+        if (isProcessed()) {
             throw new IllegalStateException("request already processed");
+        } else {
+            status = newStatus;
         }
     }
 

game-hook-base/src/main/java/cn/leancloud/play/hook/context/BeforeJoinRoomContext.java

@@ -1,18 +1,14 @@
 package cn.leancloud.play.hook.context;
 
 import cn.leancloud.play.hook.HookResponse;
-import cn.leancloud.play.hook.HookedRoom;
-import cn.leancloud.play.hook.Reason;
 import cn.leancloud.play.hook.request.JoinRoomRequest;
-import cn.leancloud.play.utils.Log;
 
 import java.util.concurrent.CompletableFuture;
 
 public final class BeforeJoinRoomContext extends AbstractOperationContext<JoinRoomRequest> {
     public BeforeJoinRoomContext(JoinRoomRequest req,
-                                 HookedRoom hookedRoom,
                                  CompletableFuture<HookResponse<JoinRoomRequest>> future) {
-        super(req, hookedRoom, future);
+        super(req, future);
     }
 
     @Override

game-hook-base/src/main/java/cn/leancloud/play/hook/context/BeforeLeaveRoomContext.java

@@ -1,16 +1,14 @@
 package cn.leancloud.play.hook.context;
 
 import cn.leancloud.play.hook.HookResponse;
-import cn.leancloud.play.hook.HookedRoom;
 import cn.leancloud.play.hook.request.LeaveRoomRequest;
 
 import java.util.concurrent.CompletableFuture;
 
 public final class BeforeLeaveRoomContext extends AbstractOperationContext<LeaveRoomRequest> {
     public BeforeLeaveRoomContext(LeaveRoomRequest req,
-                                  HookedRoom hookedRoom,
                                   CompletableFuture<HookResponse<LeaveRoomRequest>> future) {
-        super(req, hookedRoom, future);
+        super(req, future);
     }
 
     @Override

game-hook-base/src/main/java/cn/leancloud/play/hook/context/BeforeRaiseRpcContext.java

@@ -1,16 +1,14 @@
 package cn.leancloud.play.hook.context;
 
 import cn.leancloud.play.hook.HookResponse;
-import cn.leancloud.play.hook.HookedRoom;
 import cn.leancloud.play.hook.request.RaiseRpcRequest;
 
 import java.util.concurrent.CompletableFuture;
 
 public final class BeforeRaiseRpcContext extends AbstractDeferrableContext<RaiseRpcRequest> {
     public BeforeRaiseRpcContext(RaiseRpcRequest req,
-                                 HookedRoom hookedRoom,
                                  CompletableFuture<HookResponse<RaiseRpcRequest>> future) {
-        super(req, hookedRoom, future);
+        super(req, future);
     }
 
     @Override

game-hook-base/src/main/java/cn/leancloud/play/hook/context/BeforeSetPlayerPropertiesContext.java

@@ -1,16 +1,14 @@
 package cn.leancloud.play.hook.context;
 
 import cn.leancloud.play.hook.HookResponse;
-import cn.leancloud.play.hook.HookedRoom;
 import cn.leancloud.play.hook.request.SetPlayerPropertiesRequest;
 
 import java.util.concurrent.CompletableFuture;
 
 public final class BeforeSetPlayerPropertiesContext extends AbstractDeferrableContext<SetPlayerPropertiesRequest> {
     public BeforeSetPlayerPropertiesContext(SetPlayerPropertiesRequest req,
-                                            HookedRoom hookedRoom,
                                             CompletableFuture<HookResponse<SetPlayerPropertiesRequest>> future) {
-        super(req, hookedRoom, future);
+        super(req, future);
     }
 
     @Override