added tutorial

arangodb · rashtao · Oct 17, 2024 · Oct 17, 2024 · Oct 17, 2024 · Oct 17, 2024
commit 3416f871ec56cebc673c19ccfa3a30fa73f55658
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -167,6 +167,27 @@ jobs:
           working_directory: integration-tests
       - report
       - store_cache
+
+  tutorial:
+    parameters:
+      docker-img:
+        type: 'string'
+        default: 'docker.io/arangodb/arangodb:latest'
+    executor: 'j21'
+    steps:
+      - timeout
+      - checkout
+      - setup_remote_docker
+      - start-db:
+          docker-img: <<parameters.docker-img>>
+      - load_cache
+      - mvn-install
+      - run:
+          name: Run tutorial
+          command: mvn spring-boot:run
+          working_directory: tutorial
+      - store_cache
+
   deploy:
     executor: 'j17'
     steps:
@@ -177,6 +198,7 @@ jobs:
       - config_gpg
       - deploy
       - store_cache
+
   release:
     executor: 'j17'
     steps:
@@ -243,6 +265,9 @@ workflows:
               spring-boot-version:
                 - '3.2.6'
                 - '3.3.0'
+  tutorial:
+    jobs:
+      - tutorial
   deploy:
     jobs:
       - deploy:

diff --git a/tutorial/README.md b/tutorial/README.md
@@ -0,0 +1,183 @@
+![ArangoDB-Logo](https://www.arangodb.com/wp-content/uploads/2016/05/ArangoDB_logo_@2.png)
+
+# Spring Data ArangoDB - Tutorial
+
+This is a tutorial on how to configure [Spring Data ArangoDB](https://github.com/arangodb/spring-data), without using 
+Spring Boot Starter ArangoDB.
+A more extensive demo about the features of Spring Data ArangoDB can be found in the 
+[Spring Boot Starter ArangoDB Demo](https://github.com/arangodb/spring-boot-starter/tree/main/demo).
+
+# Getting Started
+
+## Build a project with Maven
+
+First, we have to set up a project and add every needed dependency.
+We use `Maven` and `Spring Boot` for this demo.
+
+We have to create a Maven `pom.xml`:
+
+```xml
+<?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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <relativePath/>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.3.4</version>
+    </parent>
+
+    <groupId>com.arangodb</groupId>
+    <artifactId>spring-data-arangodb-tutorial</artifactId>
+    <version>1.0.0</version>
+
+    <name>spring-data-arangodb-tutorial</name>
+    <description>ArangoDB Spring Data Tutorial</description>
+
+    <properties>
+        <java.version>21</java.version>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.arangodb</groupId>
+            <artifactId>arangodb-spring-data</artifactId>
+            <version>4.4.0</version>
+        </dependency>
+    </dependencies>
+
+</project>
+```
+
+## Entity classes
+
+For this tutorial we will model our entity with a Java record class:
+
+```java
+@Document("characters")
+public record Character(
+        @Id
+        String id,
+        String name,
+        String surname
+) {
+}
+```
+
+## Create a repository
+
+Now that we have our data model, we want to store data. For this, we create a repository interface which
+extends `ArangoRepository`. This gives us access to CRUD operations, paging, and query by example mechanics.
+
+```java
+public interface CharacterRepository extends ArangoRepository<Character, String> {
+}
+```
+
+## Create a Configuration class
+
+We need a configuration class to set up everything to connect to our ArangoDB instance and to declare that all
+needed Spring Beans are processed by the Spring container.
+
+- `@EnableArangoRepositories`: Defines where Spring can find your repositories
+- `arango()`: Method to configure the connection to the ArangoDB instance
+- `database()`: Method to define the database name
+- `returnOriginalEntities()`: Method to configures the behaviour of repository save methods to either return the  
+  original entities (updated where possible) or new ones. Set to `false` to use java records.
+
+```java
+@Configuration
+@EnableArangoRepositories(basePackages = {"com.arangodb.spring.demo"})
+public class AdbConfig implements ArangoConfiguration {
+
+    @Override
+    public ArangoDB.Builder arango() {
+        return new ArangoDB.Builder()
+                .host("localhost", 8529)
+                .user("root")
+                .password("test");
+    }
+
+    @Override
+    public String database() {
+        return "spring-demo";
+    }
+
+    @Override
+    public boolean returnOriginalEntities() {
+        return false;
+    }
+}
+```
+
+## Create a CommandLineRunner
+
+To run our demo as command line application, we have to create a class implementing `CommandLineRunner`:
+
+```java
+@ComponentScan("com.arangodb.spring.demo")
+public class CrudRunner implements CommandLineRunner {
+
+    @Autowired
+    private ArangoOperations operations;
+
+    @Autowired
+    private CharacterRepository repository;
+
+    @Override
+    public void run(String... args) {
+        // first drop the database so that we can run this multiple times with the same dataset
+        operations.dropDatabase();
+
+        System.out.println("# CRUD operations");
+
        // save a single entity in the database
+        // there is no need of creating the collection first. This happen automatically
+        Character nedStark = new Character(null, "Ned", "Stark");
+        Character saved = repository.save(nedStark);
+        System.out.println("Ned Stark saved in the database: " + saved);
+    }
+}
+```
+
+## Run the applucation
+
+Finally, we create a main class:
+
+```java
+@SpringBootApplication
+public class DemoApplication {
+  public static void main(final String... args) {
+    System.exit(SpringApplication.exit(
+            SpringApplication.run(CrudRunner.class, args)
+    ));
+  }
+}
+```
+
+And run it with:
+
+```shell
+mvn spring-boot:run
+```
+
+This should produce a console output similar to:
+
+```
+Ned Stark saved in the database: Character[id=2029, name=Ned, surname=Stark]
+```
+
+# Learn more
+
+* [ArangoDB](https://www.arangodb.com)
+* [Spring Data ArangoDB](https://github.com/arangodb/spring-data)
+* [ArangoDB Java Driver](https://github.com/arangodb/arangodb-java-driver)
+* [Spring Boot Starter ArangoDB Demo](https://github.com/arangodb/spring-boot-starter/tree/main/demo)
diff --git a/tutorial/pom.xml b/tutorial/pom.xml
@@ -0,0 +1,41 @@
+<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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <relativePath/>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.3.4</version>
+    </parent>
+
+    <groupId>com.arangodb</groupId>
+    <artifactId>spring-data-arangodb-tutorial</artifactId>
+    <version>1.0.0</version>
+
+    <name>spring-data-arangodb-tutorial</name>
+    <description>ArangoDB Spring Data Tutorial</description>
+
+    <properties>
+        <java.version>21</java.version>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.arangodb</groupId>
+            <artifactId>arangodb-spring-data</artifactId>
+            <version>4.4.0</version>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+        </dependency>
+    </dependencies>
+
+</project>
diff --git a/tutorial/src/main/java/com/arangodb/spring/demo/AdbConfig.java b/tutorial/src/main/java/com/arangodb/spring/demo/AdbConfig.java
@@ -0,0 +1,29 @@
+package com.arangodb.spring.demo;
+
+import com.arangodb.ArangoDB;
+import com.arangodb.springframework.annotation.EnableArangoRepositories;
+import com.arangodb.springframework.config.ArangoConfiguration;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+@EnableArangoRepositories(basePackages = {"com.arangodb.spring.demo"})
+public class AdbConfig implements ArangoConfiguration {
+
+    @Override
+    public ArangoDB.Builder arango() {
+        return new ArangoDB.Builder()
+                .host("localhost", 8529)
+                .user("root")
+                .password("test");
+    }
+
+    @Override
+    public String database() {
+        return "spring-demo";
+    }
+
+    @Override
+    public boolean returnOriginalEntities() {
+        return false;
+    }
+}
diff --git a/tutorial/src/main/java/com/arangodb/spring/demo/DemoApplication.java b/tutorial/src/main/java/com/arangodb/spring/demo/DemoApplication.java
@@ -0,0 +1,35 @@
+/*
+ * DISCLAIMER
+ *
+ * Copyright 2017 ArangoDB GmbH, Cologne, Germany
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * Copyright holder is ArangoDB GmbH, Cologne, Germany
+ */
+
+package com.arangodb.spring.demo;
+
+import com.arangodb.spring.demo.runner.CrudRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+
+@SpringBootApplication
+public class DemoApplication {
+    public static void main(final String... args) {
+        System.exit(SpringApplication.exit(
+                SpringApplication.run(CrudRunner.class, args)
+        ));
+    }
+}
diff --git a/tutorial/src/main/java/com/arangodb/spring/demo/entity/Character.java b/tutorial/src/main/java/com/arangodb/spring/demo/entity/Character.java
@@ -0,0 +1,33 @@
+/*
+ * DISCLAIMER
+ *
+ * Copyright 2017 ArangoDB GmbH, Cologne, Germany
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * Copyright holder is ArangoDB GmbH, Cologne, Germany
+ */
+
+package com.arangodb.spring.demo.entity;
+
+import com.arangodb.springframework.annotation.Document;
+import org.springframework.data.annotation.Id;
+
+@Document("characters")
+public record Character(
+        @Id
+        String id,
+        String name,
+        String surname
+) {
+}
diff --git a/tutorial/src/main/java/com/arangodb/spring/demo/repository/CharacterRepository.java b/tutorial/src/main/java/com/arangodb/spring/demo/repository/CharacterRepository.java
@@ -0,0 +1,27 @@
+/*
+ * DISCLAIMER
+ *
+ * Copyright 2017 ArangoDB GmbH, Cologne, Germany
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * Copyright holder is ArangoDB GmbH, Cologne, Germany
+ */
+
+package com.arangodb.spring.demo.repository;
+
+import com.arangodb.spring.demo.entity.Character;
+import com.arangodb.springframework.repository.ArangoRepository;
+
+public interface CharacterRepository extends ArangoRepository<Character, String> {
+}