Merge pull request #7 from sashirestela/developer

Release 0.6.0

Author: sashirestela

README.md

@@ -23,15 +23,16 @@ public class Post {
 }
 
 // Interface
+@Resource("/posts")
 public interface PostService {
 
-  @GET("/posts")
+  @GET
   List<Post> readPosts(@Query("_page") Integer page, @Query("_limit") Integer limit);
 
-  @GET("/posts/{postId}")
+  @GET("/{postId}")
   Post readPost(@Path("postId") Integer postId);
 
-  @POST("/posts")
+  @POST
   Post createPost(@Body Post post);
 
 }
@@ -104,8 +105,8 @@ Example:
 
 ```
 final var URL_BASE = "https://api.example.com";
-final var AUTHORIZATION_HEADER = "Authorization";
-final var BEARER_AUTHORIZATION = "Bearer qwertyasdfghzxcvb";
+final var HEADER_NAME = "Authorization";
+final var HEADER_VALUE = "Bearer qwertyasdfghzxcvb";
 final var END_OF_STREAM = "[DONE]";
 
 var httpClient = HttpClient.newBuilder()
@@ -118,24 +119,78 @@ var httpClient = HttpClient.newBuilder()
 
 var cleverClient = CleverClient.builder()
     .urlBase(URL_BASE)
-    .headers(Arrays.asList(AUTHORIZATION_HEADER, BEARER_AUTHORIZATION))
+    .headers(Arrays.asList(HEADER_NAME, HEADER_VALUE))
     .httpClient(httpClient)
     .endOfStream(END_OF_STREAM)
     .build();
 ```
 
 ### Interface Annotations
 
-| Annotation | Target    | Value                    |
-|------------|-----------|--------------------------|
-| Resource   | Interface | Resource's url           |
-| GET        | Method    | GET endpoint's url       |
-| POST       | Method    | POST endpoint's url      |
-| PUT        | Method    | PUT endpoint's url       |
-| DELETE     | Method    | DELETE endpoint's url    |
-| Multipart  | Method    | None. Mark for multipart |
-| Path       | Parameter | Path parameter name      |
-| Query      | Parameter | Query parameter name     |
+| Annotation | Target    | Value                       | Required Value |
+|------------|-----------|-----------------------------|----------------|
+| Resource   | Interface | Resource's url              | optional       |
+| GET        | Method    | GET endpoint's url          | optional       |
+| POST       | Method    | POST endpoint's url         | optional       |
+| PUT        | Method    | PUT endpoint's url          | optional       |
+| DELETE     | Method    | DELETE endpoint's url       | optional       |
+| Multipart  | Method    | (None)                      | none           |
+| Path       | Parameter | Path parameter name in url  | mandatory      |
+| Query      | Parameter | Query parameter name in url | mandatory      |
+| Body       | Parameter | (None)                      | none           |
+
+
+* ```Resource``` could be used to separate the repeated part of the endpoints' url in an interface.
+* ```GET, POST, PUT, DELETE``` are used to mark the typical http methods (endpoints).
+* ```Multipart``` is used to mark an endpoint with a multipart/form-data request. This is required when tou need to upload files.
+* ```Path``` is used to replace the path parameter name in url with the matched method parameter's value.
+* ```Query``` is used to add a query parameter to the url in the way: [?]queryName=methodParameterValue[&...].
+* ```Body``` is used to mark a custom object method parameter as the endpoint's payload request, so the request will be application/json at least the endpoint is annotated with Multipart.
+* Check the above [Description's example](#💡-description) and the [Test](https://github.com/sashirestela/cleverclient/tree/main/src/test/java/io/github/sashirestela/cleverclient) folder to see most of these interface annotations in action.
+
+### Interface Default Methods
+You can create interface default methods to execute special requirements such as pre/post processing before/after calling annotated regular methods. For example in the following interface definition, we have two regular methods with POST annotation which are called from anoother two default methods. In those defaults methods we are making some pre processing (in this case, modifying the request) before calling the annotated methods:
+
+```
+@Resource("/v1/completions")
+interface Completions {
+
+  default CompletableFuture<CompletionResponse> create(CompletionRequest completionRequest) {
+    completionRequest.setStream(false);
+    return notUseCreate(completionRequest);
+  }
+
+  @POST
+  CompletableFuture<CompletionResponse> notUseCreate(@Body CompletionRequest completionRequest);
+
+  default CompletableFuture<Stream<CompletionResponse>> createStream(CompletionRequest completionRequest) {
+    completionRequest.setStream(true);
+    return notUseCreateStream(completionRequest);
+  }
+
+  @POST
+  CompletableFuture<Stream<CompletionResponse>> notUseCreateStream(@Body CompletionRequest completionRequest);
+
+}
+```
+
+### Supported Response Type
+The reponse types are determined from the method responses. You don't need any annotation for that.
+
+We have five response types: Stream of objects, List of objects, Generic of object, Single object, and Plain Text, and all of them can be synchronous or asynchronous:
+
+| Method Response                     | Sync/Async | Response Type                           |
+|-------------------------------------|------------|-----------------------------------------|
+| CompletableFuture<Stream\<Object>>  | Async      | Server sent events as Stream of Objects |
+| Stream\<Object>                     | Sync       | Server sent events as Stream of Objects |
+| CompletableFuture<List\<Object>>    | Async      | Collection of Objects                   |
+| List\<Object>                       | Sync       | Collection of Objects                   |
+| CompletableFuture<Generic\<Object>> | Async      | Custom Generic Class of Object          |
+| Generic\<Object>                    | Sync       | Custom Generic Class of Object          |
+| CompletableFuture\<Object>          | Async      | Single Object                           |
+| Object                              | Sync       | Single Object                           |
+| CompletableFuture\<String>          | Async      | Plain Text                              |
+| String                              | Sync       | Plain Text                              |
 
 
 ## ✳ Examples

pom.xml

@@ -6,7 +6,7 @@
 
   <groupId>io.github.sashirestela</groupId>
   <artifactId>cleverclient</artifactId>
-  <version>0.5.0</version>
+  <version>0.6.0</version>
   <packaging>jar</packaging>
 
   <name>cleverclient</name>

src/example/java/io/github/sashirestela/cleverclient/example/jsonplaceholder/PostService.java

@@ -9,22 +9,24 @@
 import io.github.sashirestela.cleverclient.annotation.PUT;
 import io.github.sashirestela.cleverclient.annotation.Path;
 import io.github.sashirestela.cleverclient.annotation.Query;
+import io.github.sashirestela.cleverclient.annotation.Resource;
 
+@Resource("/posts")
 public interface PostService {
 
-  @GET("/posts")
+  @GET
   List<Post> readPosts(@Query("_page") Integer page, @Query("_limit") Integer limit);
 
-  @GET("/posts/{postId}")
+  @GET("/{postId}")
   Post readPost(@Path("postId") Integer postId);
 
-  @POST("/posts")
+  @POST
   Post createPost(@Body Post post);
 
-  @PUT("/posts/{postId}")
+  @PUT("/{postId}")
   Post updatePost(@Path("postId") Integer postId, @Body Post post);
 
-  @DELETE("/posts/{postId}")
+  @DELETE("/{postId}")
   Post deletePost(@Path("postId") Integer postId);
 
 }

src/main/java/io/github/sashirestela/cleverclient/CleverClient.java

@@ -11,10 +11,8 @@
 import io.github.sashirestela.cleverclient.support.CleverClientSSE;
 import lombok.Builder;
 import lombok.Getter;
-import lombok.NoArgsConstructor;
 import lombok.NonNull;
 
-@NoArgsConstructor
 @Getter
 public class CleverClient {
   private static Logger logger = LoggerFactory.getLogger(CleverClient.class);

src/test/java/io/github/sashirestela/cleverclient/CleverClientTest.java

@@ -20,6 +20,7 @@ void shouldSetPropertiesToDefaultValuesWhenBuilderIsCalledWithoutThoseProperties
         .build();
     assertEquals(List.of(), cleverClient.getHeaders());
     assertEquals(HttpClient.Version.HTTP_2, cleverClient.getHttpClient().version());
+    assertNotNull(cleverClient.getUrlBase());
     assertNotNull(cleverClient.getHttpProcessor());
   }
 

src/test/java/io/github/sashirestela/cleverclient/http/HttpProcessorTest.java

@@ -74,6 +74,15 @@ void shouldReturnAStringSyncWhenMethodReturnTypeIsAString() throws IOException,
     assertEquals(expectedDemo, actualDemo);
   }
 
+  @Test
+  void shouldThrownExceptionWhenMethodReturnTypeIsAString() throws IOException, InterruptedException {
+    when(httpClient.send(any(HttpRequest.class), any(HttpResponse.BodyHandlers.ofString().getClass())))
+        .thenThrow(new InterruptedException("The operation was interrupted"));
+
+    var service = httpProcessor.createProxy(ITest.SyncService.class);
+    assertThrows(CleverClientException.class, () -> service.getDemoPlain(100));
+  }
+
   @Test
   void shouldReturnAnObjectSyncWhenMethodReturnTypeIsAnObject() throws IOException, InterruptedException {
     when(httpClient.send(any(HttpRequest.class), any(HttpResponse.BodyHandlers.ofString().getClass())))
@@ -88,6 +97,15 @@ void shouldReturnAnObjectSyncWhenMethodReturnTypeIsAnObject() throws IOException
     assertEquals(expectedDemo, actualDemo);
   }
 
+  @Test
+  void shouldThrownExceptionWhenMethodReturnTypeIsAnObject() throws IOException, InterruptedException {
+    when(httpClient.send(any(HttpRequest.class), any(HttpResponse.BodyHandlers.ofString().getClass())))
+        .thenThrow(new InterruptedException("The operation was interrupted"));
+    
+    var service = httpProcessor.createProxy(ITest.SyncService.class);
+    assertThrows(CleverClientException.class, () -> service.getDemo(100));
+  }
+
   @Test
   void shouldReturnAGenericSyncWhenMethodReturnTypeIsAnObject() throws IOException, InterruptedException {
     when(httpClient.send(any(HttpRequest.class), any(HttpResponse.BodyHandlers.ofString().getClass())))
@@ -103,6 +121,15 @@ void shouldReturnAGenericSyncWhenMethodReturnTypeIsAnObject() throws IOException
     assertEquals(expectedDemo, actualDemo);
   }
 
+  @Test
+  void shouldThrownExceptionWhenMethodReturnTypeIsAGenericObject() throws IOException, InterruptedException {
+    when(httpClient.send(any(HttpRequest.class), any(HttpResponse.BodyHandlers.ofString().getClass())))
+        .thenThrow(new InterruptedException("The operation was interrupted"));
+    
+    var service = httpProcessor.createProxy(ITest.SyncService.class);
+    assertThrows(CleverClientException.class, () -> service.getGenericDemo(1));
+  }
+
   @Test
   void shouldReturnAListSyncWhenMethodReturnTypeIsAList() throws IOException, InterruptedException {
     when(httpClient.send(any(HttpRequest.class), any(HttpResponse.BodyHandlers.ofString().getClass())))
@@ -118,6 +145,15 @@ void shouldReturnAListSyncWhenMethodReturnTypeIsAList() throws IOException, Inte
     assertEquals(expectedDemo, actualDemo);
   }
 
+  @Test
+  void shouldThrownExceptionWhenMethodReturnTypeIsAList() throws IOException, InterruptedException {
+    when(httpClient.send(any(HttpRequest.class), any(HttpResponse.BodyHandlers.ofString().getClass())))
+        .thenThrow(new InterruptedException("The operation was interrupted"));
+    
+    var service = httpProcessor.createProxy(ITest.SyncService.class);
+    assertThrows(CleverClientException.class, () -> service.getDemos());
+  }
+
   @Test
   void shouldReturnAStreamSyncWhenMethodReturnTypeIsAStream() throws IOException, InterruptedException {
     when(httpClient.send(any(HttpRequest.class), any(HttpResponse.BodyHandlers.ofLines().getClass())))
@@ -133,6 +169,16 @@ void shouldReturnAStreamSyncWhenMethodReturnTypeIsAStream() throws IOException,
     assertEquals(expectedDemo, actualDemo);
   }
 
+  @Test
+  void shouldThrownExceptionWhenMethodReturnTypeIsAStream() throws IOException, InterruptedException {
+    when(httpClient.send(any(HttpRequest.class), any(HttpResponse.BodyHandlers.ofLines().getClass())))
+        .thenThrow(new InterruptedException("The operation was interrupted"));
+    
+    var service = httpProcessor.createProxy(ITest.SyncService.class);
+    var requestDemo = new ITest.RequestDemo("Descr", null);
+    assertThrows(CleverClientException.class, () -> service.getDemoStream(requestDemo));
+  }
+
   @Test
   void shouldReturnAStringAsyncWhenMethodReturnTypeIsAString() {
     when(httpClient.sendAsync(any(HttpRequest.class), any(HttpResponse.BodyHandlers.ofString().getClass())))

src/test/java/io/github/sashirestela/cleverclient/http/ITest.java

@@ -10,6 +10,7 @@
 import io.github.sashirestela.cleverclient.annotation.Multipart;
 import io.github.sashirestela.cleverclient.annotation.POST;
 import io.github.sashirestela.cleverclient.annotation.Path;
+import io.github.sashirestela.cleverclient.annotation.Resource;
 import lombok.AllArgsConstructor;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
@@ -37,50 +38,52 @@ interface BadPathParamService {
 
   }
 
+  @Resource("/demos")
   interface AsyncService {
 
-    @GET("/demos")
+    @GET
     Set<Demo> unsupportedMethod();
 
-    @GET("/demos/{demoId}")
+    @GET("/{demoId}")
     CompletableFuture<String> getDemoPlain(@Path("demoId") Integer demoId);
 
-    @GET("/demos/{demoId}")
+    @GET("/{demoId}")
     CompletableFuture<Demo> getDemo(@Path("demoId") Integer demoId);
 
-    @GET("/demos/{genericDemoId}")
+    @GET("/{genericDemoId}")
     CompletableFuture<Generic<Demo>> getGenericDemo(@Path("genericDemoId") Integer genericDemoId);
 
-    @GET("/demos")
+    @GET
     CompletableFuture<List<Demo>> getDemos();
 
-    @POST("/demos")
+    @POST
     CompletableFuture<Stream<Demo>> getDemoStream(@Body RequestDemo request);
 
     @Multipart
-    @POST("/demos")
+    @POST
     CompletableFuture<Demo> getFile(@Body RequestDemo request);
 
     default String defaultMethod(String name) {
       return "Hello " + name;
     }
   }
 
+  @Resource("/demos")
   interface SyncService {
 
-    @GET("/demos/{demoId}")
+    @GET("/{demoId}")
     String getDemoPlain(@Path("demoId") Integer demoId);
 
-    @GET("/demos/{demoId}")
+    @GET("/{demoId}")
     Demo getDemo(@Path("demoId") Integer demoId);
 
-    @GET("/demos/{genericDemoId}")
+    @GET("/{genericDemoId}")
     Generic<Demo> getGenericDemo(@Path("genericDemoId") Integer genericDemoId);
 
-    @GET("/demos")
+    @GET
     List<Demo> getDemos();
 
-    @POST("/demos")
+    @POST
     Stream<Demo> getDemoStream(@Body RequestDemo request);
   }