Add convenient methods for voiding statements and getting multiple st…

…atements (#144)

Resolves #131, #142

README.md

@@ -47,10 +47,24 @@ The xAPI Java Client has a Spring AutoConfiguration bean which picks up the foll
 | xapi.client.password          | Password for basic authorization header                            |
 | xapi.client.authorization     | Authorization header (has precedence over the username and password properties)    |
 
-Properties can be set using any [external configuration](https://docs.spring.io/spring-boot/docs/3.0.4/reference/htmlsingle/#features.external-config.files) method supported by Spring Boot.
+Properties can be set using any [external configuration](https://docs.spring.io/spring-boot/docs/3.0.6/reference/htmlsingle/#features.external-config.files) method supported by Spring Boot.
 
 If you need more specific customization (eg. your LRS needs specific headers, or you want to set the authorization header dynamically) you can create a custom configurer by implementing the `XapiClientConfigurer` interface.
 
+### Advanced Configuration
+
+The xAPI Java Client uses the Spring WebClient. Spring WebClient has default memory limit of 256KB for buffering data. If this limit is exceeded then a DataBufferLimitException will be thrown.
+
+The default memory limit of 256KB for buffering data could be exceeded if the LRS returns a large number of Statements or if the Statements contain attachments. 
+
+It is possible to set the memory limit for buffering data with the `spring.codec.max-in-memory-size` property.
+
+Example:
+
+```
+spring.codec.max-in-memory-size=1MB
+```
+
 ### Statement Resource
 
 The xAPI Java Client allows applications to store and fetch xAPI [Statements](https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#statements).
@@ -101,6 +115,20 @@ StatementResult moreStatementResult = moreResponse.getBody();
 Statement[] statements = moreStatementResult.getStatements();
 ```
 
+### Getting Statements as Iterator (and processing them as a Stream)
+
+`getStatementIterator()` is convenient method a which combines the functionality of `getStatments()` and `getMoreStatements()`. In most cases it is preferable to use getStatementIterator() instead of `getStatments()` and `getMoreStatements()`.
+
+Example:
+
+```java
+var statements = client.getStatementIterator().block();
+
+// process the first 100 Statements
+statements.toStream().limit(100).forEach(s -> {
+    // add logic here...
+  });
+```
 
 ### Posting a Statement
 

samples/get-statement-iterator/pom.xml

@@ -0,0 +1,22 @@
+<?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.samples</groupId>
+    <artifactId>xapi-samples-build</artifactId>
+    <version>1.1.5-SNAPSHOT</version>
+  </parent>
+  <artifactId>get-statement-iterator</artifactId>
+  <name>Get xAPI StatementIterator Sample</name>
+  <description>Get xAPI StatementIterator</description>
+  <dependencies>
+    <dependency>
+      <groupId>dev.learning.xapi</groupId>
+      <artifactId>xapi-client</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>dev.learning.xapi.samples</groupId>
+      <artifactId>core</artifactId>
+    </dependency>
+  </dependencies>
+</project>

samples/get-statement-iterator/src/main/java/dev/learning/xapi/samples/getstatements/GetStatementIteratorApplication.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2016-2023 Berry Cloud Ltd. All rights reserved.
+ */
+
+package dev.learning.xapi.samples.getstatements;
+
+import dev.learning.xapi.client.XapiClient;
+import dev.learning.xapi.model.Verb;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * Sample using xAPI client to get multiple statements as StatementIterator.
+ *
+ * @author Thomas Turrell-Croft
+ * @author István Rátkai (Selindek)
+ */
+@SpringBootApplication
+public class GetStatementIteratorApplication implements CommandLineRunner {
+
+  /**
+   * Default xAPI client. Properties are picked automatically from application.properties.
+   */
+  @Autowired
+  private XapiClient client;
+
+  public static void main(String[] args) {
+    SpringApplication.run(GetStatementIteratorApplication.class, args).close();
+  }
+
+  @Override
+  public void run(String... args) throws Exception {
+
+    // Get Statements as StatementIterator
+    var statements = client.getStatementIterator().block();
+
+    // Print the returned statements to the console
+    statements.toStream().forEach(s -> System.out.println(s));
+
+    // Get Statements with Verb filter as StatementIterator
+    var filteredStatements =
+        client.getStatementIterator(r -> r.verb(Verb.ATTEMPTED)).block();
+
+    // Print the returned statements to the console
+    filteredStatements.toStream().forEach(s -> System.out.println(s));
+
+  }
+
+}

samples/get-statement-iterator/src/main/resources/application.properties

@@ -0,0 +1,5 @@
+xapi.client.username = admin
+xapi.client.password = password
+xapi.client.baseUrl = https://example.com/xapi/
+
+spring.codec.max-in-memory-size=1MB

samples/get-statement-with-attachment/src/main/resources/application.properties

@@ -1,3 +1,5 @@
 xapi.client.username = admin
 xapi.client.password = password
 xapi.client.baseUrl = https://example.com/xapi/
+
+spring.codec.max-in-memory-size=1MB

samples/get-statements/src/main/java/dev/learning/xapi/samples/getstatements/GetStatementsApplication.java

@@ -7,7 +7,6 @@
 import dev.learning.xapi.client.XapiClient;
 import dev.learning.xapi.model.StatementResult;
 import dev.learning.xapi.model.Verb;
-import java.util.Arrays;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.CommandLineRunner;
 import org.springframework.boot.SpringApplication;
@@ -39,7 +38,7 @@ public void run(String... args) throws Exception {
     ResponseEntity<StatementResult> response = client.getStatements().block();
 
     // Print the returned statements to the console
-    Arrays.asList(response.getBody().getStatements()).forEach(s -> System.out.println(s));
+    response.getBody().getStatements().forEach(s -> System.out.println(s));
 
 
 
@@ -48,7 +47,7 @@ public void run(String... args) throws Exception {
         client.getStatements(r -> r.verb(Verb.ATTEMPTED.getId())).block();
 
     // Print the returned statements to the console
-    Arrays.asList(filteredResponse.getBody().getStatements()).forEach(s -> System.out.println(s));
+    filteredResponse.getBody().getStatements().forEach(s -> System.out.println(s));
 
   }
 

samples/get-statements/src/main/resources/application.properties

@@ -1,3 +1,5 @@
 xapi.client.username = admin
 xapi.client.password = password
 xapi.client.baseUrl = https://example.com/xapi/
+
+spring.codec.max-in-memory-size=1MB

samples/pom.xml

@@ -35,6 +35,7 @@
     <module>core</module>
     <!-- Statements Resource -->
     <module>get-statement</module>
+    <module>get-statement-iterator</module>
     <module>get-statement-with-attachment</module>
     <module>post-statement</module>
     <module>post-signed-statement</module>

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

@@ -7,6 +7,7 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import dev.learning.xapi.model.Agent;
 import dev.learning.xapi.model.StatementFormat;
+import dev.learning.xapi.model.Verb;
 import java.net.URI;
 import java.time.Instant;
 import java.util.Map;
@@ -179,6 +180,20 @@ public Builder verb(String verb) {
       return this;
     }
 
+    /**
+     * Sets the verb.
+     *
+     * @param verb The verb of the GetStatementRequest.
+     *
+     * @return This builder
+     *
+     * @see GetStatementsRequest#verb
+     */
+    public Builder verb(Verb verb) {
+      this.verb = verb.getId();
+      return this;
+    }
+
     /**
      * Sets the activity.
      *