Integrate automatic code formatting with git hooks and documentation

.githooks/README.md

@@ -0,0 +1,40 @@
+# Git Hooks for xAPI Java
+
+This directory contains git hooks for automating development workflows.
+
+## Available Hooks
+
+### pre-commit
+
+Automatically formats Java code using the Spotify fmt-maven-plugin before committing changes.
+
+**What it does:**
+- Runs `./mvnw com.spotify.fmt:fmt-maven-plugin:format` to format all Java files
+- Adds reformatted files to the commit automatically
+- Ensures code follows the Google Java Style Guide
+
+## Installation
+
+To enable these hooks, run from the repository root:
+
+```bash
+./install-git-hooks.sh
+```
+
+This configures git to use hooks from this directory instead of the default `.git/hooks/`.
+
+## Disabling Hooks
+
+To disable the hooks:
+
+```bash
+git config --unset core.hooksPath
+```
+
+## Manual Formatting
+
+If you prefer not to use the git hook, you can manually format code at any time:
+
+```bash
+./mvnw com.spotify.fmt:fmt-maven-plugin:format
+```

.githooks/pre-commit

@@ -0,0 +1,26 @@
+#!/bin/bash
+# Pre-commit hook for xapi-java
+# Automatically formats Java code using the Spotify fmt-maven-plugin before committing
+
+# Check if we're in the repository root
+if [ ! -f "mvnw" ]; then
+    echo "Error: mvnw not found. This hook must be run from the repository root."
+    exit 1
+fi
+
+echo "Running code formatter..."
+
+# Run the formatter
+./mvnw com.spotify.fmt:fmt-maven-plugin:format -q
+
+# Check if the formatter ran successfully
+if [ $? -ne 0 ]; then
+    echo "Error: Code formatting failed. Please fix the issues and try again."
+    exit 1
+fi
+
+# Add any files that were reformatted to the commit
+git add -u
+
+echo "Code formatting complete."
+exit 0

.github/copilot-instructions.md

@@ -54,6 +54,18 @@ Always run the full build after making changes to ensure your changes don't brea
 
 - **Strictly follow the Google Java Style Guide**
 
+### Code Formatting
+
+**IMPORTANT**: All Java code must be formatted using the Spotify fmt-maven-plugin before committing:
+
+```bash
+./mvnw com.spotify.fmt:fmt-maven-plugin:format
+```
+
+- Run this command after making code changes and before committing
+- The formatter automatically applies Google Java Style formatting
+- A git pre-commit hook is available via `./install-git-hooks.sh` to automate this
+
 ### Validation
 
 - CheckStyle validation runs automatically during Maven build

CONTRIBUTING.md

@@ -117,6 +117,31 @@ To run tests:
 
 xAPI Java strictly follows the **[Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)**.
 
+#### Automated Formatting
+
+The project uses the **[Spotify fmt-maven-plugin](https://github.com/spotify/fmt-maven-plugin)** to automatically format Java code according to the Google Java Style Guide.
+
+**Recommended: Install Git Hooks**
+
+To automatically format your code before each commit, install the pre-commit hook:
+
+```bash
+./install-git-hooks.sh
+```
+
+This ensures your code is always formatted correctly before committing. The hook runs `./mvnw com.spotify.fmt:fmt-maven-plugin:format` automatically.
+
+**Manual Formatting**
+
+If you prefer not to use the git hook, you can manually format your code at any time:
+
+```bash
+# Format all Java files in the project
+./mvnw com.spotify.fmt:fmt-maven-plugin:format
+```
+
+**Important**: Run the formatter before committing your changes to avoid formatting issues in pull requests.
+
 #### Automated Enforcement
 
 - **[CheckStyle](https://checkstyle.sourceforge.io)** is configured to enforce the Google Java Style Guide automatically during the build
@@ -294,6 +319,7 @@ public Mono<ResponseEntity<Statement>> getStatement(GetStatementRequest request)
 
 Before submitting your pull request, verify:
 
+- [ ] Code has been formatted using `./mvnw com.spotify.fmt:fmt-maven-plugin:format` (or use the git hook)
 - [ ] Public methods are documented with JavaDoc
 - [ ] Public methods are tested with unit tests
 - [ ] New and existing tests pass when run locally (`./mvnw clean verify`)

install-git-hooks.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Install script for git hooks
+# This script sets up git hooks for automatic code formatting
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "Installing git hooks for xapi-java..."
+
+# Check if we're in the repository root
+if [ ! -f "$SCRIPT_DIR/mvnw" ]; then
+    echo "Error: This script must be run from the repository root."
+    exit 1
+fi
+
+# Configure git to use the .githooks directory
+git config core.hooksPath .githooks
+
+echo "✓ Git hooks installed successfully!"
+echo ""
+echo "The following hooks are now active:"
+echo "  - pre-commit: Automatically formats Java code using fmt-maven-plugin"
+echo ""
+echo "To disable the hooks, run: git config --unset core.hooksPath"

samples/core/src/main/java/dev/learning/xapi/samples/core/ExampleState.java

@@ -16,9 +16,7 @@ public class ExampleState {
   private String message;
   private Instant timestamp;
 
-  /**
-   * Constructor for ExampleState.
-   */
+  /** Constructor for ExampleState. */
   public ExampleState(String message, Instant timestamp) {
     super();
     this.message = message;
@@ -45,5 +43,4 @@ public void setTimestamp(Instant timestamp) {
   public String toString() {
     return "ExampleState [message=" + message + ", timestamp=" + timestamp + "]";
   }
-
 }

samples/delete-activity-profile/src/main/java/dev/learning/xapi/samples/deleteactivityprofile/DeleteActivityProfileApplication.java

@@ -20,11 +20,8 @@
 @SpringBootApplication
 public class DeleteActivityProfileApplication implements CommandLineRunner {
 
-  /**
-   * Default xAPI client. Properties are picked automatically from application.properties.
-   */
-  @Autowired
-  private XapiClient client;
+  /** Default xAPI client. Properties are picked automatically from application.properties. */
+  @Autowired private XapiClient client;
 
   public static void main(String[] args) {
     SpringApplication.run(DeleteActivityProfileApplication.class, args).close();
@@ -37,25 +34,21 @@ public void run(String... args) {
     postActivityProfile();
 
     // Delete activity profile
-    client.deleteActivityProfile(r -> r.activityId("https://example.com/activity/1")
-
-        .profileId("bookmark"))
-
+    client
+        .deleteActivityProfile(
+            r -> r.activityId("https://example.com/activity/1").profileId("bookmark"))
         .block();
-
   }
 
   private void postActivityProfile() {
 
     // Post activity profile
-    client.postActivityProfile(r -> r.activityId("https://example.com/activity/1")
-
-        .profileId("bookmark")
-
-        .activityProfile(new ExampleState("Hello World!", Instant.now())))
-
+    client
+        .postActivityProfile(
+            r ->
+                r.activityId("https://example.com/activity/1")
+                    .profileId("bookmark")
+                    .activityProfile(new ExampleState("Hello World!", Instant.now())))
         .block();
-
   }
-
 }

samples/delete-agent-profile/src/main/java/dev/learning/xapi/samples/deleteagentprofile/DeleteAgentProfileApplication.java

@@ -20,11 +20,8 @@
 @SpringBootApplication
 public class DeleteAgentProfileApplication implements CommandLineRunner {
 
-  /**
-   * Default xAPI client. Properties are picked automatically from application.properties.
-   */
-  @Autowired
-  private XapiClient client;
+  /** Default xAPI client. Properties are picked automatically from application.properties. */
+  @Autowired private XapiClient client;
 
   public static void main(String[] args) {
     SpringApplication.run(DeleteAgentProfileApplication.class, args).close();
@@ -39,25 +36,21 @@ public void run(String... args) {
     // Delete Agent Profile
     client
         .deleteAgentProfile(
-            r -> r.agent(a -> a.name("A N Other").mbox("mailto:another@example.com"))
-
-                .profileId("bookmark"))
-
+            r ->
+                r.agent(a -> a.name("A N Other").mbox("mailto:another@example.com"))
+                    .profileId("bookmark"))
         .block();
   }
 
   private void postAgentProfile() {
 
     // Post Profile
     client
-        .postAgentProfile(r -> r.agent(a -> a.name("A N Other").mbox("mailto:another@example.com"))
-
-            .profileId("bookmark")
-
-            .profile(new ExampleState("Hello World!", Instant.now())))
-
+        .postAgentProfile(
+            r ->
+                r.agent(a -> a.name("A N Other").mbox("mailto:another@example.com"))
+                    .profileId("bookmark")
+                    .profile(new ExampleState("Hello World!", Instant.now())))
         .block();
-
   }
-
 }

samples/delete-state/src/main/java/dev/learning/xapi/samples/deletestate/DeleteStateApplication.java

@@ -20,11 +20,8 @@
 @SpringBootApplication
 public class DeleteStateApplication implements CommandLineRunner {
 
-  /**
-   * Default xAPI client. Properties are picked automatically from application.properties.
-   */
-  @Autowired
-  private XapiClient client;
+  /** Default xAPI client. Properties are picked automatically from application.properties. */
+  @Autowired private XapiClient client;
 
   public static void main(String[] args) {
     SpringApplication.run(DeleteStateApplication.class, args).close();
@@ -37,33 +34,27 @@ public void run(String... args) {
     postState();
 
     // Delete State
-    client.deleteState(r -> r.activityId("https://example.com/activity/1")
-
-        .agent(a -> a.name("A N Other").mbox("mailto:another@example.com"))
-
-        .registration("67828e3a-d116-4e18-8af3-2d2c59e27be6")
-
-        .stateId("bookmark"))
-
+    client
+        .deleteState(
+            r ->
+                r.activityId("https://example.com/activity/1")
+                    .agent(a -> a.name("A N Other").mbox("mailto:another@example.com"))
+                    .registration("67828e3a-d116-4e18-8af3-2d2c59e27be6")
+                    .stateId("bookmark"))
         .block();
-
   }
 
   private void postState() {
 
     // Post State
-    client.postState(r -> r.activityId("https://example.com/activity/1")
-
-        .agent(a -> a.name("A N Other").mbox("mailto:another@example.com"))
-
-        .registration("67828e3a-d116-4e18-8af3-2d2c59e27be6")
-
-        .stateId("bookmark")
-
-        .state(new ExampleState("Hello World!", Instant.now())))
-
+    client
+        .postState(
+            r ->
+                r.activityId("https://example.com/activity/1")
+                    .agent(a -> a.name("A N Other").mbox("mailto:another@example.com"))
+                    .registration("67828e3a-d116-4e18-8af3-2d2c59e27be6")
+                    .stateId("bookmark")
+                    .state(new ExampleState("Hello World!", Instant.now())))
         .block();
-
   }
-
 }

samples/delete-states/src/main/java/dev/learning/xapi/samples/deletestates/DeleteStatesApplication.java

@@ -20,11 +20,8 @@
 @SpringBootApplication
 public class DeleteStatesApplication implements CommandLineRunner {
 
-  /**
-   * Default xAPI client. Properties are picked automatically from application.properties.
-   */
-  @Autowired
-  private XapiClient client;
+  /** Default xAPI client. Properties are picked automatically from application.properties. */
+  @Autowired private XapiClient client;
 
   public static void main(String[] args) {
     SpringApplication.run(DeleteStatesApplication.class, args).close();
@@ -37,31 +34,26 @@ public void run(String... args) {
     postState();
 
     // Delete states
-    client.deleteStates(r -> r.activityId("https://example.com/activity/1")
-
-        .agent(a -> a.name("A N Other").mbox("mailto:another@example.com"))
-
-        .registration("67828e3a-d116-4e18-8af3-2d2c59e27be6"))
-
+    client
+        .deleteStates(
+            r ->
+                r.activityId("https://example.com/activity/1")
+                    .agent(a -> a.name("A N Other").mbox("mailto:another@example.com"))
+                    .registration("67828e3a-d116-4e18-8af3-2d2c59e27be6"))
         .block();
-
   }
 
   private void postState() {
 
     // Post State
-    client.postState(r -> r.activityId("https://example.com/activity/1")
-
-        .agent(a -> a.name("A N Other").mbox("mailto:another@example.com"))
-
-        .registration("67828e3a-d116-4e18-8af3-2d2c59e27be6")
-
-        .stateId("bookmark")
-
-        .state(new ExampleState("Hello World!", Instant.now())))
-
+    client
+        .postState(
+            r ->
+                r.activityId("https://example.com/activity/1")
+                    .agent(a -> a.name("A N Other").mbox("mailto:another@example.com"))
+                    .registration("67828e3a-d116-4e18-8af3-2d2c59e27be6")
+                    .stateId("bookmark")
+                    .state(new ExampleState("Hello World!", Instant.now())))
         .block();
-
   }
-
 }