Add support of RESTful services (#872)

Author: artem-v

services-api/src/main/java/io/scalecube/services/Reflect.java

@@ -8,6 +8,7 @@
 import io.scalecube.services.annotations.ExecuteOn;
 import io.scalecube.services.annotations.RequestType;
 import io.scalecube.services.annotations.ResponseType;
+import io.scalecube.services.annotations.RestMethod;
 import io.scalecube.services.annotations.Service;
 import io.scalecube.services.annotations.ServiceMethod;
 import io.scalecube.services.annotations.Tag;
@@ -176,7 +177,8 @@ public static Map<Method, MethodInfo> methodsInfo(Class<?> serviceInterface) {
                             requestType(method),
                             isRequestTypeServiceMessage(method),
                             isSecured(method),
-                            null))));
+                            null,
+                            restMethod(method)))));
   }
 
   /**
@@ -277,6 +279,11 @@ public static String methodName(Method method) {
     return methodAnnotation.value().length() > 0 ? methodAnnotation.value() : method.getName();
   }
 
+  public static String restMethod(Method method) {
+    RestMethod methodAnnotation = method.getAnnotation(RestMethod.class);
+    return methodAnnotation != null ? methodAnnotation.value() : null;
+  }
+
   /**
    * Handy method to get qualifier String from service's interface and method.
    *

services-api/src/main/java/io/scalecube/services/ServiceCall.java

@@ -192,7 +192,7 @@ public Mono<ServiceMessage> requestOne(ServiceMessage request, Type responseType
             () -> {
               ServiceMethodInvoker methodInvoker;
               if (serviceRegistry != null
-                  && (methodInvoker = serviceRegistry.getInvoker(request.qualifier())) != null) {
+                  && (methodInvoker = serviceRegistry.getInvoker(request)) != null) {
                 // local service
                 return methodInvoker.invokeOne(request).map(this::throwIfError);
               } else {
@@ -248,7 +248,7 @@ public Flux<ServiceMessage> requestMany(ServiceMessage request, Type responseTyp
             () -> {
               ServiceMethodInvoker methodInvoker;
               if (serviceRegistry != null
-                  && (methodInvoker = serviceRegistry.getInvoker(request.qualifier())) != null) {
+                  && (methodInvoker = serviceRegistry.getInvoker(request)) != null) {
                 // local service
                 return methodInvoker.invokeMany(request).map(this::throwIfError);
               } else {
@@ -303,7 +303,7 @@ public Flux<ServiceMessage> requestBidirectional(
                 ServiceMessage request = first.get();
                 ServiceMethodInvoker methodInvoker;
                 if (serviceRegistry != null
-                    && (methodInvoker = serviceRegistry.getInvoker(request.qualifier())) != null) {
+                    && (methodInvoker = serviceRegistry.getInvoker(request)) != null) {
                   // local service
                   return methodInvoker.invokeBidirectional(messages).map(this::throwIfError);
                 } else {
@@ -412,10 +412,7 @@ private ServiceMessage toServiceMessage(MethodInfo methodInfo, Object request) {
 
   private static ServiceUnavailableException noReachableMemberException(ServiceMessage request) {
     return new ServiceUnavailableException(
-        "No reachable member with such service: "
-            + request.qualifier()
-            + ", failed request: "
-            + request);
+        "No reachable member with such service: " + request.qualifier());
   }
 
   /**

services-api/src/main/java/io/scalecube/services/ServiceMethodDefinition.java

@@ -4,6 +4,7 @@
 import java.io.IOException;
 import java.io.ObjectInput;
 import java.io.ObjectOutput;
+import java.lang.reflect.Method;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
@@ -22,6 +23,7 @@ public class ServiceMethodDefinition implements Externalizable {
   private String action;
   private Map<String, String> tags;
   private boolean isSecured;
+  private String restMethod;
 
   /**
    * Constructor for de/serialization purpose.
@@ -32,25 +34,42 @@ public class ServiceMethodDefinition implements Externalizable {
   public ServiceMethodDefinition() {}
 
   /**
-   * Create a new Service Method Definition.
+   * Constructor.
    *
    * @param action method name
    */
   public ServiceMethodDefinition(String action) {
-    this(action, Collections.emptyMap(), false);
+    this(action, Collections.emptyMap(), false, null);
   }
 
   /**
-   * Create a new Service Method Definition.
+   * Constructor.
    *
    * @param action method name
    * @param tags tags of this method
    * @param isSecured is method protected by authentication
+   * @param restMethod REST method (optional)
    */
-  public ServiceMethodDefinition(String action, Map<String, String> tags, boolean isSecured) {
+  public ServiceMethodDefinition(
+      String action, Map<String, String> tags, boolean isSecured, String restMethod) {
     this.action = Objects.requireNonNull(action, "ServiceMethodDefinition.action is required");
     this.tags = Collections.unmodifiableMap(new HashMap<>(tags));
     this.isSecured = isSecured;
+    this.restMethod = restMethod;
+  }
+
+  /**
+   * Factory method that creates {@link ServiceMethodDefinition} instance from the service method.
+   *
+   * @param method servuce method
+   * @return {@link ServiceMethodDefinition} instance
+   */
+  public static ServiceMethodDefinition fromMethod(Method method) {
+    return new ServiceMethodDefinition(
+        Reflect.methodName(method),
+        Reflect.serviceMethodTags(method),
+        Reflect.isSecured(method),
+        Reflect.restMethod(method));
   }
 
   public String action() {
@@ -65,12 +84,17 @@ public boolean isSecured() {
     return isSecured;
   }
 
+  public String restMethod() {
+    return restMethod;
+  }
+
   @Override
   public String toString() {
     return new StringJoiner(", ", ServiceMethodDefinition.class.getSimpleName() + "[", "]")
-        .add("action=" + action)
+        .add("action='" + action + "'")
         .add("tags=" + tags)
         .add("isSecured=" + isSecured)
+        .add("restMethod='" + restMethod + "'")
         .toString();
   }
 
@@ -88,6 +112,9 @@ public void writeExternal(ObjectOutput out) throws IOException {
 
     // auth
     out.writeBoolean(isSecured);
+
+    // rest method
+    out.writeUTF(restMethod != null ? restMethod : "");
   }
 
   @Override
@@ -107,5 +134,9 @@ public void readExternal(ObjectInput in) throws IOException, ClassNotFoundExcept
 
     // auth
     this.isSecured = in.readBoolean();
+
+    // rest method
+    final var restMethod = in.readUTF();
+    this.restMethod = !restMethod.isEmpty() ? restMethod : null;
   }
 }

services-api/src/main/java/io/scalecube/services/ServiceReference.java

@@ -23,6 +23,7 @@ public class ServiceReference {
   private final Map<String, String> tags;
   private final Address address;
   private final boolean isSecured;
+  private final String restMethod;
 
   /**
    * Constructor for service reference.
@@ -44,6 +45,7 @@ public ServiceReference(
     this.tags = mergeTags(serviceMethodDefinition, serviceRegistration, serviceEndpoint);
     this.address = serviceEndpoint.address();
     this.isSecured = serviceMethodDefinition.isSecured();
+    this.restMethod = serviceMethodDefinition.restMethod();
   }
 
   public String endpointId() {
@@ -82,6 +84,10 @@ public boolean isSecured() {
     return isSecured;
   }
 
+  public String restMethod() {
+    return restMethod;
+  }
+
   private Map<String, String> mergeTags(
       ServiceMethodDefinition serviceMethodDefinition,
       ServiceRegistration serviceRegistration,
@@ -105,6 +111,7 @@ public String toString() {
         .add("tags=" + tags)
         .add("address=" + address)
         .add("isSecured=" + isSecured)
+        .add("restMethod='" + restMethod + "'")
         .toString();
   }
 }

services-api/src/main/java/io/scalecube/services/ServiceScanner.java

@@ -39,12 +39,7 @@ public static List<ServiceRegistration> scanServiceInfo(ServiceInfo serviceInfo)
               List<ServiceMethodDefinition> actions =
                   Arrays.stream(serviceInterface.getMethods())
                       .filter(method -> method.isAnnotationPresent(ServiceMethod.class))
-                      .map(
-                          method ->
-                              new ServiceMethodDefinition(
-                                  Reflect.methodName(method),
-                                  Reflect.serviceMethodTags(method),
-                                  Reflect.isSecured(method)))
+                      .map(ServiceMethodDefinition::fromMethod)
                       .collect(Collectors.toList());
               return new ServiceRegistration(namespace, serviceTags, actions);
             })

services-api/src/main/java/io/scalecube/services/annotations/AfterConstruct.java

@@ -10,7 +10,7 @@
 /**
  * This annotation is used to mark the method which will be executed after constructing of service
  * and dependency injection is done. <br>
- * Scalecube services doesn't support {@link javax.annotation.PostConstruct} since Java API
+ * NOTE: scalecube services doesn't support {@code javax.annotation.PostConstruct} since Java API
  * Specification for it has strict limitation for annotated method.
  */
 @Documented

services-api/src/main/java/io/scalecube/services/annotations/BeforeDestroy.java

@@ -8,8 +8,9 @@
 import java.lang.annotation.Target;
 
 /**
- * This annotation is used to mark the method which will be executed before shutdown of service <br>
- * Scalecube services doesn't support {@link javax.annotation.PreDestroy} since Java API *
+ * This annotation is used to mark the method which will be executed before shutdown of service.
+ * <br>
+ * NOTE: scalecube services doesn't support {@code javax.annotation.PreDestroy} since Java API
  * Specification for it has strict limitation for annotated method.
  */
 @Documented

services-api/src/main/java/io/scalecube/services/annotations/RestMethod.java

@@ -0,0 +1,20 @@
+package io.scalecube.services.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Indicates that annotated method is a REST service method. */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
+public @interface RestMethod {
+
+  /**
+   * Name of the HTTP method. Supported methods: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS,
+   * TRACE.
+   *
+   * @return http method
+   */
+  String value();
+}

services-api/src/main/java/io/scalecube/services/annotations/Service.java

@@ -5,7 +5,7 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-/** Indicates that annotated class is a ScaleCube service object. */
+/** Indicates that annotated class is a scalecube service object. */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface Service {

services-api/src/main/java/io/scalecube/services/annotations/ServiceMethod.java

@@ -5,9 +5,7 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-/**
- * Indicates that annotated method is a ScaleCube service method.
- */
+/** Indicates that annotated method is a scalecube service method. */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
 public @interface ServiceMethod {

services-api/src/main/java/io/scalecube/services/api/ServiceMessage.java

@@ -4,7 +4,6 @@
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Objects;
-import java.util.Optional;
 import java.util.StringJoiner;
 
 public final class ServiceMessage {
@@ -28,6 +27,9 @@ public final class ServiceMessage {
   /** Error type header. */
   public static final String HEADER_ERROR_TYPE = "errorType";
 
+  /** Request method header. */
+  public static final String HEADER_REQUEST_METHOD = "requestMethod";
+
   /** Null value for error type. */
   public static final int NULL_ERROR_TYPE = -1;
 
@@ -126,7 +128,8 @@ public String dataFormat() {
    * @return data format of the data or default one
    */
   public String dataFormatOrDefault() {
-    return Optional.ofNullable(dataFormat()).orElse(DEFAULT_DATA_FORMAT);
+    final var dataFormat = dataFormat();
+    return dataFormat != null ? dataFormat : DEFAULT_DATA_FORMAT;
   }
 
   /**
@@ -164,7 +167,7 @@ public boolean hasData(Class<?> dataClass) {
   /**
    * Describes whether the message is an error.
    *
-   * @return <code>true</code> if error, otherwise <code>false</code>.
+   * @return result
    */
   public boolean isError() {
     return headers.containsKey(HEADER_ERROR_TYPE);
@@ -187,6 +190,15 @@ public int errorType() {
     }
   }
 
+  /**
+   * Returns request method header.
+   *
+   * @return request method, or null if such header doesn't exist.
+   */
+  public String requestMethod() {
+    return headers.get(HEADER_REQUEST_METHOD);
+  }
+
   @Override
   public String toString() {
     return new StringJoiner(", ", "ServiceMessage" + "[", "]")

services-api/src/main/java/io/scalecube/services/methods/MethodInfo.java

@@ -21,6 +21,7 @@ public final class MethodInfo {
   private final boolean isRequestTypeServiceMessage;
   private final boolean isSecured;
   private final Scheduler scheduler;
+  private final String restMethod;
 
   /**
    * Create a new service info.
@@ -35,6 +36,7 @@ public final class MethodInfo {
    * @param isRequestTypeServiceMessage is request service message
    * @param isSecured is method protected by authentication
    * @param scheduler scheduler
+   * @param restMethod restMethod
    */
   public MethodInfo(
       String serviceName,
@@ -46,7 +48,8 @@ public MethodInfo(
       Class<?> requestType,
       boolean isRequestTypeServiceMessage,
       boolean isSecured,
-      Scheduler scheduler) {
+      Scheduler scheduler,
+      String restMethod) {
     this.parameterizedReturnType = parameterizedReturnType;
     this.isReturnTypeServiceMessage = isReturnTypeServiceMessage;
     this.communicationMode = communicationMode;
@@ -59,6 +62,7 @@ public MethodInfo(
     this.isRequestTypeServiceMessage = isRequestTypeServiceMessage;
     this.isSecured = isSecured;
     this.scheduler = scheduler;
+    this.restMethod = restMethod;
   }
 
   public String serviceName() {
@@ -113,6 +117,10 @@ public Scheduler scheduler() {
     return scheduler;
   }
 
+  public String restMethod() {
+    return restMethod;
+  }
+
   @Override
   public String toString() {
     return new StringJoiner(", ", MethodInfo.class.getSimpleName() + "[", "]")
@@ -128,6 +136,7 @@ public String toString() {
         .add("isRequestTypeServiceMessage=" + isRequestTypeServiceMessage)
         .add("isSecured=" + isSecured)
         .add("scheduler=" + scheduler)
+        .add("restMethod=" + restMethod)
         .toString();
   }
 }