Add xAPI client with support for state document resources

README.md

@@ -2,9 +2,112 @@
 
 xAPI Java helps you to create applications that send or receive xAPI [Statements](https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#statements) or [Documents](https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#10-documents).
 
+There are two projects in this [Monorepo](https://en.wikipedia.org/wiki/Monorepo), xAPI Client and xAPI Model.
+
+Both the xAPI client and xAPI Model use a [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface). Objects are [immutable](https://en.wikipedia.org/wiki/Immutable_object).
+
+## xAPI Java Client
+
+The xAPI Java Client can be used by learning record providers (LRP) to communicate with learning record stores (LRS) or a system which follows the LRS requirements of one or more of the xAPI resources.
+
+### Getting started
+
+To use the xAPI Client include the appropriate XML in the `dependencies` section of your `pom.xml`, as shown in the following example:
+
+```xml
+<project>
+    <modelVersion>4.0.0</modelVersion>
+    <artifactId>getting-started</artifactId>
+    <!-- ... -->
+    <dependencies>
+        <!-- ... -->
+        <dependency>
+            <groupId>dev.learning.xapi</groupId>
+            <artifactId>xapi-client</artifactId>
+            <version>1.0.3</version>
+        </dependency>
+    </dependencies>
+</project>
+```
+
+### State Resource
+
+The xAPI Client allows applications to store, change, fetch, or delete [state documents](https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#23-state-resource).
+
+#### Getting a state
+
+Example:
+
+```java
+final var request = client.getState(r -> r.activityId("https://example.com/activity/1")
+
+    .agent(a -> a.name("A N Other").mbox("another@example.com"))
+
+    .registration("67828e3a-d116-4e18-8af3-2d2c59e27be6")
+
+    .stateId("bookmark"), String.class)
+
+    .block();
+
+final String state = request.getBody();
+```
+
+#### Posting a state
+
+Example:
+
+```java
+client.postState(r -> r.activityId("https://example.com/activity/1")
+
+    .agent(a -> a.name("A N Other").mbox("another@example.com"))
+
+    .registration("67828e3a-d116-4e18-8af3-2d2c59e27be6")
+
+    .stateId("bookmark")
+
+    .state("Hello World!"))
+
+    .block();
+```
+
+#### Putting a state
+
+Example:
+
+```java
+client.putState(r -> r.activityId("https://example.com/activity/1")
+
+    .agent(a -> a.name("A N Other").mbox("another@example.com"))
+
+    .registration("67828e3a-d116-4e18-8af3-2d2c59e27be6")
+
+    .stateId("bookmark")
+
+    .state("Hello World!"))
+
+    .block();
+```
+
+#### Deleting a state
+
+Example:
+
+```java
+client.deleteState(r -> r.activityId("https://example.com/activity/1")
+
+    .agent(a -> a.name("A N Other").mbox("another@example.com"))
+
+    .registration("67828e3a-d116-4e18-8af3-2d2c59e27be6")
+
+    .stateId("bookmark"))
+
+    .block();
+```
+
+
 ## xAPI Java Model
 
-The xAPI Model has a [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface). Objects are [immutable](https://en.wikipedia.org/wiki/Immutable_object).
+The xAPI model can be used by clients that send xAPI data or by servers that receive xAPI data.
 
 ### Getting started
 
@@ -20,7 +123,7 @@ To use the xAPI Model include the appropriate XML in the `dependencies` section
         <dependency>
             <groupId>dev.learning.xapi</groupId>
             <artifactId>xapi-model</artifactId>
-            <version>1.0.1</version>
+            <version>1.0.3</version>
         </dependency>
     </dependencies>
 </project>
@@ -95,7 +198,7 @@ final String json = objectMapper.writeValueAsString(statement);
 
 ```
 
-### Creating a new statment using an existing statement as template
+### Creating a new statement using an existing statement as template
 
 Example:
 

pom.xml

@@ -86,6 +86,7 @@
 
   <modules>
     <module>xapi-model</module>
+    <module>xapi-client</module>
   </modules>
 
   <build>

xapi-client/lombok.config

@@ -0,0 +1,3 @@
+# Suppress code coverage on Lombok annotations
+lombok.addLombokGeneratedAnnotation = true
+lombok.builder.className = Builder

xapi-client/pom.xml

@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>dev.learning.xapi</groupId>
+    <artifactId>xapi-build</artifactId>
+    <version>1.0.3-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>xapi-client</artifactId>
+
+  <name>xAPI Client</name>
+  <description>learning.dev xAPI Client</description>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-webflux</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>dev.learning.xapi</groupId>
+      <artifactId>xapi-model</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.projectlombok</groupId>
+      <artifactId>lombok</artifactId>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-test</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>com.squareup.okhttp3</groupId>
+      <artifactId>mockwebserver</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>com.squareup.okhttp3</groupId>
+      <artifactId>okhttp</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>io.netty</groupId>
+      <artifactId>netty-resolver-dns-native-macos</artifactId>
+      <classifier>osx-aarch_64</classifier>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.jacoco</groupId>
+        <artifactId>jacoco-maven-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </build>
+
+</project>

xapi-client/src/main/java/dev/learning/xapi/client/DeleteStateRequest.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2016-2023 Berry Cloud Ltd. All rights reserved.
+ */
+
+package dev.learning.xapi.client;
+
+import lombok.experimental.SuperBuilder;
+import org.springframework.http.HttpMethod;
+
+/**
+ * Request for deleting a single State document.
+ *
+ * @see <a href=
+ *      "https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#single-document-put--post--get--delete">Single
+ *      State Document DELETE</a>
+ *
+ * @author István Rátkai (Selindek)
+ */
+@SuperBuilder
+public class DeleteStateRequest extends StateRequest {
+
+  @Override
+  protected HttpMethod getMethod() {
+    return HttpMethod.DELETE;
+  }
+
+  /**
+   * Builder for DeleteStateRequest.
+   */
+  public abstract static class Builder<C extends DeleteStateRequest, B extends Builder<C, B>>
+      extends StateRequest.Builder<C, B> {
+
+    // This static class extends the lombok builder.
+
+  }
+
+}

xapi-client/src/main/java/dev/learning/xapi/client/DeleteStatesRequest.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2016-2023 Berry Cloud Ltd. All rights reserved.
+ */
+
+package dev.learning.xapi.client;
+
+import lombok.experimental.SuperBuilder;
+import org.springframework.http.HttpMethod;
+
+/**
+ * Request for deleting multiple State documents.
+ *
+ * @see <a href=
+ *      "https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#multiple-document-delete">Multiple
+ *      State Document DELETE</a>
+ *
+ * @author István Rátkai (Selindek)
+ */
+@SuperBuilder
+public class DeleteStatesRequest extends StatesRequest {
+
+  @Override
+  protected HttpMethod getMethod() {
+    return HttpMethod.DELETE;
+  }
+
+  /**
+   * Builder for DeleteStatesRequest.
+   */
+  public abstract static class Builder<C extends DeleteStatesRequest, B extends Builder<C, B>>
+      extends StatesRequest.Builder<C, B> {
+
+    // This static class extends the lombok builder.
+
+  }
+
+}

xapi-client/src/main/java/dev/learning/xapi/client/GetStateRequest.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2016-2023 Berry Cloud Ltd. All rights reserved.
+ */
+
+package dev.learning.xapi.client;
+
+import lombok.experimental.SuperBuilder;
+import org.springframework.http.HttpMethod;
+
+/**
+ * Request for getting a single State document.
+ *
+ * @see <a href=
+ *      "https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#single-document-put--post--get--delete">Single
+ *      State Document GET</a>
+ *
+ * @author István Rátkai (Selindek)
+ */
+@SuperBuilder
+public class GetStateRequest extends StateRequest {
+
+  @Override
+  protected HttpMethod getMethod() {
+    return HttpMethod.GET;
+  }
+
+  /**
+   * Builder for GetStateRequest.
+   */
+  public abstract static class Builder<C extends GetStateRequest, B extends Builder<C, B>>
+      extends StateRequest.Builder<C, B> {
+
+    // This static class extends the lombok builder.
+
+  }
+
+}

xapi-client/src/main/java/dev/learning/xapi/client/GetStatesRequest.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2016-2023 Berry Cloud Ltd. All rights reserved.
+ */
+
+package dev.learning.xapi.client;
+
+import java.time.Instant;
+import java.util.Map;
+import java.util.Optional;
+import lombok.Getter;
+import lombok.experimental.SuperBuilder;
+import org.springframework.http.HttpMethod;
+import org.springframework.web.util.UriBuilder;
+
+/**
+ * Request for getting multiple State documents.
+ *
+ * @see <a href=
+ *      "https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#multiple-document-get">Multiple
+ *      State Document GET</a>
+ *
+ * @author István Rátkai (Selindek)
+ */
+@SuperBuilder
+@Getter
+public class GetStatesRequest extends StatesRequest {
+
+  /**
+   * Only ids of states stored since the specified instant (exclusive) are returned.
+   */
+  private final Instant since;
+
+  @Override
+  protected HttpMethod getMethod() {
+    return HttpMethod.GET;
+  }
+
+  @Override
+  protected UriBuilder url(UriBuilder uriBuilder, Map<String, Object> queryParams) {
+
+    return super.url(uriBuilder, queryParams).queryParamIfPresent("since",
+        Optional.ofNullable(since));
+
+  }
+
+  /**
+   * Builder for DeleteStateRequest.
+   */
+  public abstract static class Builder<C extends GetStatesRequest, B extends Builder<C, B>>
+      extends StatesRequest.Builder<C, B> {
+
+    // This static class extends the lombok builder.
+
+  }
+
+}