[4.x] Helidon Data examples

etc/checkstyle-suppressions.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!--
 
-    Copyright (c) 2016, 2023 Oracle and/or its affiliates.
+    Copyright (c) 2016, 2025 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -43,4 +43,10 @@
               files="examples/openapi-tools/"/>
     <suppress checks="HideUtilityClassConstructor"
               files="examples/openapi-tools/"/>
+    <suppress checks="MethodName"
+              files="examples/data/"/>
+    <suppress checks="MethodName"
+              files="examples/declarative/data/"/>
+    <suppress checks="MethodName"
+              files="examples/microprofile/data/"/>
 </suppressions>

examples/data/mysql/README.md

@@ -0,0 +1,79 @@
+Helidon Data SE Imperative Example
+----
+
+This example demonstrates a Java SE imperative application that utilizes Helidon Data, WebServer,
+and a MySQL database.
+
+There are 2 repository interfaces in the example:
+
+- `PokemonRepository`
+- `TypeRepository`
+
+> **NOTE:** Database table `POKEMON` is initialized with ID auto increment to supply primary key values
+>           by the database. MySQL database default String comparisons are case-insensitive.
+
+## Start the Database
+
+To run the application, a MySQL database is required. You can start the database with the necessary
+configuration using the following Docker command:
+
+```shell
+docker run --name mysql \
+       -p 3306:3306 \
+       -e MYSQL_DATABASE='pokemons' \
+       -e MYSQL_RANDOM_ROOT_PASSWORD='yes' \
+       -e MYSQL_USER='user' \
+       -e MYSQL_PASSWORD='changeit' \
+       -d mysql
+```
+
+### Database Schema and Content
+
+The application's Jakarta Persistence API implementation automatically creates the database schema
+using the `resources/init.sql` script. The schema consists of two main entities: `Pokemon` and `Type`.
+The initialization script populates the database with a basic set of records.
+
+## Build and Run
+
+1. Build the application using Maven:
+
+```shell
+mvn package
+```
+
+2. Run the application:
+
+```shell
+java -jar target/helidon-examples-data-mysql.jar
+```
+
+> **NOTE:** The default username and password from this example should never be used in a production environment!
+
+## Test Example
+
+The application provides `http://localhost:8080/pokemon` endpoint.
+
+**List all pokémons:**
+```shell
+curl http://localhost:8080/pokemon/all
+```
+
+**List all normal type pokémons:**
+```shell
+curl http://localhost:8080/pokemon/type/Normal
+```
+
+**Retrieve a pokémon by name (`Meowth`):**
+```shell
+curl http://localhost:8080/pokemon/get/Meowth
+```
+
+**Insert new pokémon:**
+```shell
+curl -i -X POST -H 'Content-type: application/json' -d '{"name":"Charmander","type":"Fire"}' http://localhost:8080/pokemon
+```
+
+**Delete existing pokémon by ID (`20`):**
+```shell
+curl -i -X DELETE http://localhost:8080/pokemon/20
+```

examples/data/mysql/pom.xml

@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 2025 Oracle and/or its affiliates.
+
+    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.
+
+-->
+
+<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>io.helidon.applications</groupId>
+        <artifactId>helidon-se</artifactId>
+        <version>4.3.0-SNAPSHOT</version>
+        <relativePath/>
+    </parent>
+
+    <groupId>io.helidon.examples.data</groupId>
+    <artifactId>helidon-examples-data-mysql</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <name>Helidon Examples Data MySQ</name>
+
+    <description>
+        The example shows how to use Helidon Data with MySQL.
+    </description>
+
+    <properties>
+        <mainClass>io.helidon.examples.data.mysql.Main</mainClass>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.helidon.config</groupId>
+            <artifactId>helidon-config-yaml</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.data</groupId>
+            <artifactId>helidon-data</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.data.jakarta.persistence</groupId>
+            <artifactId>helidon-data-jakarta-persistence</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.webserver</groupId>
+            <artifactId>helidon-webserver</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.http.media</groupId>
+            <artifactId>helidon-http-media-jsonp</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.logging</groupId>
+            <artifactId>helidon-logging-jul</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>jakarta.persistence</groupId>
+            <artifactId>jakarta.persistence-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.eclipse.persistence</groupId>
+            <artifactId>org.eclipse.persistence.jpa</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.eclipse.persistence</groupId>
+            <artifactId>org.eclipse.persistence.core</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.mysql</groupId>
+            <artifactId>mysql-connector-j</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>io.helidon.bundles</groupId>
+                            <artifactId>helidon-bundles-apt</artifactId>
+                            <version>${helidon.version}</version>
+                        </path>
+                        <path>
+                            <groupId>io.helidon.data.jakarta.persistence</groupId>
+                            <artifactId>helidon-data-jakarta-persistence-codegen</artifactId>
+                            <version>${helidon.version}</version>
+                        </path>
+                    </annotationProcessorPaths>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-dependency-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>copy-libs</id>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

examples/data/mysql/src/main/java/io/helidon/examples/data/mysql/Main.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025 Oracle and/or its affiliates.
+ *
+ * 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.
+ */
+package io.helidon.examples.data.mysql;
+
+import io.helidon.logging.common.LogConfig;
+import io.helidon.webserver.WebServer;
+
+/**
+ * The Main class serves as the entry point for the application.
+ * It demonstrates the usage of Helidon Data in an SE imperative application.
+ */
+public class Main {
+
+    private Main() {
+        throw new UnsupportedOperationException("Instances of Main class are not allowed");
+    }
+
+    /**
+     * Entry point for the SE application.
+     *
+     * @param args command-line arguments passed to the application
+     */
+    public static void main(String... args) {
+        LogConfig.configureRuntime();
+        WebServer webServer = WebServer.builder()
+                .port(8080)
+                .routing(routing -> routing.register("/pokemon", new PokemonService()))
+                .build();
+        webServer.start();
+        System.out.println("Server started on: http://localhost:" + webServer.port());
+    }
+
+}

examples/data/mysql/src/main/java/io/helidon/examples/data/mysql/Pokemon.java

@@ -0,0 +1,118 @@
+/*
+ * Copyright (c) 2025 Oracle and/or its affiliates.
+ *
+ * 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.
+ */
+package io.helidon.examples.data.mysql;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+
+/**
+ * Represents a pokémon entity with its associated properties.
+ * This class is annotated with JPA annotations to map its properties to a database table.
+ */
+@Entity
+@Table(name = "POKEMON")
+public class Pokemon {
+
+    @Id
+    @Column(name = "ID")
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Integer id;
+    @Column(name = "NAME", unique = true, nullable = false)
+    private String name;
+    @ManyToOne
+    @JoinColumn(name = "TYPE_ID", nullable = false)
+    private Type type;
+
+    /**
+     * Constructs a new {@link Pokemon} instance with the specified values.
+     *
+     * @param name the name of the pokémon
+     * @param type the type of the pokémon
+     */
+    public Pokemon(String name, Type type) {
+        this.id = null;
+        this.name = name;
+        this.type = type;
+    }
+
+    /**
+     * Constructs a new default {@link Pokemon} instance with default values.
+     */
+    public Pokemon() {
+        this(null, null);
+    }
+
+    /**
+     * Returns the unique identifier of the pokémon.
+     *
+     * @return the id of the pokémon
+     */
+    public Integer getId() {
+        return id;
+    }
+
+    /**
+     * Sets the unique identifier of the pokémon.
+     *
+     * @param id the new id of the pokémon
+     */
+    public void setId(Integer id) {
+        this.id = id;
+    }
+
+    /**
+     * Returns the name of the pokémon.
+     *
+     * @return the name of the pokémon
+     */
+    public String getName() {
+        return name;
+    }
+
+    /**
+     * Sets the name of the pokémon.
+     *
+     * @param name the new name of the pokémon
+     */
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    /**
+     * Returns the type of the pokémon.
+     *
+     * @return the type of the pokémon
+     */
+    public Type getType() {
+        return type;
+    }
+
+    /**
+     * Sets the type of the pokémon.
+     *
+     * @param type the new type of the pokémon
+     */
+    public void setType(Type type) {
+        this.type = type;
+    }
+
+}