Merge pull request #6 from sashirestela/developer

Release 0.5.0

Author: sashirestela

README.md

@@ -1,3 +1,172 @@
-# CleverClient
+[![codecov](https://codecov.io/gh/sashirestela/cleverclient/graph/badge.svg?token=PEYAFW3EWD)](https://codecov.io/gh/sashirestela/cleverclient)
+![Maven Central](https://img.shields.io/maven-central/v/io.github.sashirestela/cleverclient)
+![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/sashirestela/cleverclient/maven.yml)
 
+# 💎 CleverClient
 Java library that makes it easier to use the Java's HttpClient to perform http operations, using interfaces.
+
+
+## 💡 Description
+CleverClient is a Java 11+ library that makes it easy to use the standard [HttpClient](https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpClient.html) component to call http services by using annotated interfaces.
+
+For example, if we want to call the API [JsonPlaceHolder](https://jsonplaceholder.typicode.com/) with the endpoint ```/posts```, we just have to create an entity ```Post```, an interface ```PostService``` with special annotatons, and call the API through ```CleverClient```:
+
+```
+// Entity
+public class Post {
+  private Integer id;
+  private String title;
+  private String body;
+  private Integer userId;
+
+  // Constructors , getters, setters, etc.
+}
+
+// Interface
+public interface PostService {
+
+  @GET("/posts")
+  List<Post> readPosts(@Query("_page") Integer page, @Query("_limit") Integer limit);
+
+  @GET("/posts/{postId}")
+  Post readPost(@Path("postId") Integer postId);
+
+  @POST("/posts")
+  Post createPost(@Body Post post);
+
+}
+
+// Use CleverClient to call the API
+var cleverClient = CleverClient.builder()
+    .urlBase("https://jsonplaceholder.typicode.com/")
+    .build();
+
+var postService = cleverClient.create(PostService.class);
+
+var page = 1;
+var limit = 5;
+var postId = 17;
+var userId = 3;
+
+// Example Read Posts
+var postsList = postService.readPosts(page, limit);
+postsList.forEach(System.out::println);
+
+// Example Read Post
+var onePost = postService.readPost(postId);
+System.out.println(onePost);
+
+// Example Create Post
+var newPost = postService.createPost(new Post(
+    null,
+    "Hello",
+    "Hello word, you are very welcome!",
+    userId));
+System.out.println(newPost);
+```
+
+
+## 🛠️ Installation
+You can install CleverClient by adding the following dependency to your Maven project:
+
+```xml
+<dependency>
+    <groupId>io.github.sashirestela</groupId>
+    <artifactId>cleverclient</artifactId>
+    <version>[latest version]</version>
+</dependency>
+```
+
+Or alternatively using Gradle:
+
+```groovy
+dependencies {
+    implementation 'io.github.sashirestela:cleverclient:[latest version]'
+}
+```
+
+Take in account that you need to use **Java 11 or above**.
+
+
+## 📕 Features
+
+### CleverClient Builder
+We have the following attributes to create a CleverClient object:
+
+| Attribute   | Description                        | Required  |
+| ----------- |------------------------------------|-----------|
+| urlBase     | Api's url                          | mandatory |
+| headers     | Pairs of headers name/value        | optional  |
+| httpClient  | Java HttpClient object             | optional  |
+| endOfStream | Text used to mark final of streams | optional  |
+
+Example:
+
+```
+final var URL_BASE = "https://api.example.com";
+final var AUTHORIZATION_HEADER = "Authorization";
+final var BEARER_AUTHORIZATION = "Bearer qwertyasdfghzxcvb";
+final var END_OF_STREAM = "[DONE]";
+
+var httpClient = HttpClient.newBuilder()
+    .version(Version.HTTP_1_1)
+    .followRedirects(Redirect.NORMAL)
+    .connectTimeout(Duration.ofSeconds(20))
+    .executor(Executors.newFixedThreadPool(3))
+    .proxy(ProxySelector.of(new InetSocketAddress("proxy.example.com", 80)))
+    .build();
+
+var cleverClient = CleverClient.builder()
+    .urlBase(URL_BASE)
+    .headers(Arrays.asList(AUTHORIZATION_HEADER, BEARER_AUTHORIZATION))
+    .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     |
+
+
+## ✳ Examples
+Some examples have been created in the folder [example](https://github.com/sashirestela/cleverclient/tree/main/src/example/java/io/github/sashirestela/cleverclient/example) and you can follow the next steps to execute them:
+* Clone this respository:
+  ```
+  git clone https://github.com/sashirestela/cleverclient.git
+  cd cleverclient
+  ```
+* Build the project:
+  ```
+  mvn clean install
+  ```
+* Run example:
+  ```
+  mvn exec:java -Dexec.mainClass=io.github.sashirestela.cleverclient.example.<className> [logOptions]
+  ```
+  Where:
+
+  * ```<className>``` is mandatory and must be one of the values:
+    * BasicExample
+    * StreamExample (This requires you have an OpenAI account and set the env variable OPENAI_API_TOKEN)
+  
+  * ```[logOptions]``` are optional and you can you use them to set:
+    * Logger lever: ```-Dorg.slf4j.simpleLogger.defaultLogLevel=<logLevel>```
+    * Logger file: ```-Dorg.slf4j.simpleLogger.logFile=<logFile>```
+  * For example, to run the BasicExample with all the log options:
+    * ```mvn exec:java -Dexec.mainClass=io.github.sashirestela.cleverclient.example.BasicExample -Dorg.slf4j.simpleLogger.defaultLogLevel=debug -Dorg.slf4j.simpleLogger.logFile=example.log```
+
+
+## 📄 License
+CleverClient is licensed under the MIT License. See the
+[LICENSE](https://github.com/sashirestela/cleverclient/blob/main/LICENSE) file
+for more information.

pom.xml

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

src/example/java/io/github/sashirestela/cleverclient/example/BasicExample.java

@@ -0,0 +1,57 @@
+package io.github.sashirestela.cleverclient.example;
+
+import io.github.sashirestela.cleverclient.CleverClient;
+import io.github.sashirestela.cleverclient.example.jsonplaceholder.Post;
+import io.github.sashirestela.cleverclient.example.jsonplaceholder.PostService;
+
+public class BasicExample {
+
+  public static void main(String[] args) {
+    final var URL_BASE = "https://jsonplaceholder.typicode.com";
+
+    var cleverClient = CleverClient.builder()
+        .urlBase(URL_BASE)
+        .build();
+    var postService = cleverClient.create(PostService.class);
+
+    var page = 1;
+    var limit = 5;
+    var postId = 17;
+    var userId = 3;
+
+    showTitle("Example Read Posts");
+    var postsList = postService.readPosts(page, limit);
+    postsList.forEach(System.out::println);
+
+    showTitle("Example Read Post");
+    var onePost = postService.readPost(postId);
+    System.out.println(onePost);
+
+    showTitle("Example Create Post");
+    var newPost = postService.createPost(Post.builder()
+        .title("Hello")
+        .body("Hello word, you are very welcome!")
+        .userId(userId)
+        .build());
+    System.out.println(newPost);
+
+    showTitle("Example Update Post");
+    var editPost = postService.updatePost(postId, Post.builder()
+        .title("Hello")
+        .body("Hello word, you are very welcome!")
+        .userId(userId)
+        .build());
+    System.out.println(editPost);
+
+    showTitle("Example Delete Post");
+    postService.deletePost(postId);
+    System.out.println("Post was deleted");
+  }
+
+  private static void showTitle(String title) {
+    final var times = 50;
+    System.out.println("=".repeat(times));
+    System.out.println(title);
+    System.out.println("-".repeat(times));
+  }
+}

src/example/java/io/github/sashirestela/cleverclient/example/StreamExample.java

@@ -0,0 +1,63 @@
+package io.github.sashirestela.cleverclient.example;
+
+import java.util.Arrays;
+
+import io.github.sashirestela.cleverclient.CleverClient;
+import io.github.sashirestela.cleverclient.example.openai.ChatRequest;
+import io.github.sashirestela.cleverclient.example.openai.ChatResponse;
+import io.github.sashirestela.cleverclient.example.openai.ChatService;
+import io.github.sashirestela.cleverclient.example.openai.Message;
+
+/**
+ * Before running this example you must have an OpenAI account and keep your Api
+ * Key in an environment variable called OPENAI_API_KEY.
+ * 
+ * @see https://platform.openai.com/docs/api-reference/authentication
+ */
+public class StreamExample {
+
+  public static void main(String[] args) {
+    final var URL_BASE = "https://api.openai.com";
+    final var AUTHORIZATION_HEADER = "Authorization";
+    final var BEARER_AUTHORIZATION = "Bearer " + System.getenv("OPENAI_API_KEY");
+    final var END_OF_STREAM = "[DONE]";
+
+    var cleverClient = CleverClient.builder()
+        .urlBase(URL_BASE)
+        .headers(Arrays.asList(AUTHORIZATION_HEADER, BEARER_AUTHORIZATION))
+        .endOfStream(END_OF_STREAM)
+        .build();
+    var chatService = cleverClient.create(ChatService.class);
+
+    var chatRequest = ChatRequest.builder()
+        .model("gpt-3.5-turbo")
+        .messages(Arrays.asList(
+            new Message("user", "Write an article about AI, no more than 100 words.")))
+        .temperature(0.7)
+        .stream(true)
+        .build();
+
+    showTitle("Example Create Synchronous Stream");
+    var chatResponseSync = chatService.createSyncStream(chatRequest);
+    chatResponseSync
+        .filter(chatResp -> chatResp.firstContent() != null)
+        .map(ChatResponse::firstContent)
+        .forEach(System.out::print);
+    System.out.println();
+
+    showTitle("Example Create Asynchronous Stream");
+    var chatResponseAsync = chatService.createAsyncStream(chatRequest).join();
+    chatResponseAsync
+        .filter(chatResp -> chatResp.firstContent() != null)
+        .map(ChatResponse::firstContent)
+        .forEach(System.out::print);
+    System.out.println();
+  }
+
+  private static void showTitle(String title) {
+    final var times = 50;
+    System.out.println("=".repeat(times));
+    System.out.println(title);
+    System.out.println("-".repeat(times));
+  }
+}

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

@@ -0,0 +1,17 @@
+package io.github.sashirestela.cleverclient.example.jsonplaceholder;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+@Data
+public class Post {
+  private Integer id;
+  private String title;
+  private String body;
+  private Integer userId;
+}

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

@@ -0,0 +1,30 @@
+package io.github.sashirestela.cleverclient.example.jsonplaceholder;
+
+import java.util.List;
+
+import io.github.sashirestela.cleverclient.annotation.Body;
+import io.github.sashirestela.cleverclient.annotation.DELETE;
+import io.github.sashirestela.cleverclient.annotation.GET;
+import io.github.sashirestela.cleverclient.annotation.POST;
+import io.github.sashirestela.cleverclient.annotation.PUT;
+import io.github.sashirestela.cleverclient.annotation.Path;
+import io.github.sashirestela.cleverclient.annotation.Query;
+
+public interface PostService {
+
+  @GET("/posts")
+  List<Post> readPosts(@Query("_page") Integer page, @Query("_limit") Integer limit);
+
+  @GET("/posts/{postId}")
+  Post readPost(@Path("postId") Integer postId);
+
+  @POST("/posts")
+  Post createPost(@Body Post post);
+
+  @PUT("/posts/{postId}")
+  Post updatePost(@Path("postId") Integer postId, @Body Post post);
+
+  @DELETE("/posts/{postId}")
+  Post deletePost(@Path("postId") Integer postId);
+
+}

src/example/java/io/github/sashirestela/cleverclient/example/openai/ChatRequest.java

@@ -0,0 +1,17 @@
+package io.github.sashirestela.cleverclient.example.openai;
+
+import java.util.List;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+
+@AllArgsConstructor
+@Getter
+@Builder
+public class ChatRequest {
+  private String model;
+  private List<Message> messages;
+  private Double temperature;
+  private Boolean stream;
+}