Merge pull request #63 from jenetics/issues/FACILEJDBC-58-code_snippets

#58: Code snippets

Author: jenetics

facilejdbc/src/main/java/io/jenetics/facilejdbc/Batch.java

@@ -32,12 +32,11 @@
  * essentially an {@link Iterable} of records or row-creation functions. The
  * available factory functions make it easy to create a batch from a given
  * list of records or parameters.
- *
- * <pre>{@code
- * final List<Person> persons = ...;
- * final Dctor<Person> dctor = ...;
+ * {@snippet lang="java":
+ * final List<Person> persons = null; // @replace substring='null' replacement="..."
+ * final Dctor<Person> dctor = null; // @replace substring='null' replacement="..."
  * final Batch batch = Batch.of(persons, dctor);
- * }</pre>
+ * }
  *
  * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
  * @version 1.0

facilejdbc/src/main/java/io/jenetics/facilejdbc/Dctor.java

@@ -38,19 +38,19 @@
  * This interface is responsible for <em>deconstructing</em> a given record, of
  * type {@code T}, to a DB-<em>row</em> ({@link ParamValues}).
  *
- * <pre>{@code
+ * {@snippet lang="java":
  * final Dctor<Book> dctor = Dctor.of(
  *     Dctor.field("title", Book::title),
  *     Dctor.field("isbn", Book::isbn),
  *     Dctor.field("published_at", Book::publishedAt),
  *     Dctor.field("pages", Book::pages)
  * );
- * }</pre>
+ * }
  *
  * If the {@code Book} class is a record, you can just write
- * <pre>{@code
+ * {@snippet lang="java":
  * final Dctor<Book> dctor = Dctor.of(Book.class);
- * }</pre>
+ * }
  *
  * @apiNote
  * A {@code Dctor} (deconstructor) is responsible for splitting a given record
@@ -199,8 +199,7 @@ static <T> Dctor<T> of(final Field<? super T>... fields) {
 
 	/**
 	 * Create a new deconstructor for the given record type.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * // Matching column names, with book columns:
 	 * // [title, author, isbn, pages, published_at]
 	 * final Dctor<Book> dctor = Dctor.of(Book.class);
@@ -219,7 +218,7 @@ static <T> Dctor<T> of(final Field<? super T>... fields) {
 	 *     field("pages", book -> book.pages()*3),
 	 *     field("title_hash", book -> book.title().hashCode())
 	 * );
-	 * }</pre>
+	 * }
 	 *
 	 * @see Records#dctor(Class, Field[])
 	 *

facilejdbc/src/main/java/io/jenetics/facilejdbc/Lifecycle.java

@@ -232,8 +232,7 @@ default void silentClose(final Throwable previousError) {
 	 * interface but needs some cleanup work to do after usage. In the following
 	 * example the created {@code file} is automatically deleted when leaving the
 	 * {@code try} block.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * // Create the closeable file.
 	 * final Value<Path, IOException> file = Value.of(
 	 *     Files.createFile(Path.of("some_file")),
@@ -246,7 +245,7 @@ default void silentClose(final Throwable previousError) {
 	 *     final var writtenText = Files.readString(file.get());
 	 *     assert "foo".equals(writtenText);
 	 * }
-	 * }</pre>
+	 * }
 	 *
 	 * @see #of(Object, ThrowingConsumer)
 	 * @see #build(ThrowingFunction)
@@ -290,8 +289,7 @@ public String toString() {
 		 * released, by calling the defined <em>release</em> method. The typical
 		 * use case for this method is when additional initialization of the
 		 * value is needed.
-		 *
-		 * <pre>{@code
+		 * {@snippet lang="java":
 		 * final var file = CloseableValue.of(
 		 *     Files.createFile(Path.of("some_file")),
 		 *     Files::deleteIfExists
@@ -303,7 +301,7 @@ public String toString() {
 		 * try (file) {
 		 *     // Do something with temp file.
 		 * }
-		 * }</pre>
+		 * }
 		 *
 		 * @param <E> the exception type
 		 * @param block the codec block which is applied to the value
@@ -352,8 +350,7 @@ public static <T, E extends Exception> Value<T, E> of(
 		 * in the case of an error. If the <em>value</em> could be created, the
 		 * caller is responsible for closing the opened <em>resources</em> by
 		 * calling the {@link Value#close()} method.
-		 *
-		 * <pre>{@code
+		 * {@snippet lang="java":
 		 * final Value<Stream<Object>, IOException> result = Value.build(resources -> {
 		 *     final var fin = resources.add(new FileInputStream(file.toFile()), Closeable::close);
 		 *     final var bin = resources.add(new BufferedInputStream(fin), Closeable::close);
@@ -366,7 +363,7 @@ public static <T, E extends Exception> Value<T, E> of(
 		 * try (result) {
 		 *     result.get().forEach(System.out::println);
 		 * }
-		 * }</pre>
+		 * }
 		 *
 		 * @see Resources
 		 *
@@ -414,8 +411,7 @@ public static <T, E extends Exception> Value<T, E> of(
 	 * Using the {@code Resources} class can simplify the creation of
 	 * dependent input streams, where it might be otherwise necessary to create
 	 * nested {@code try-with-resources} blocks.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * try (var resources = new Resources<IOException>()) {
 	 *     final var fin = resources.add(new FileInputStream(file), Closeable::close);
 	 *     if (fin.read() != -1) {
@@ -424,7 +420,7 @@ public static <T, E extends Exception> Value<T, E> of(
 	 *     final var oin = resources.add(new ObjectInputStream(fin), Closeable::close);
 	 *     // ...
 	 * }
-	 * }</pre>
+	 * }
 	 *
 	 * @see Value#build(ThrowingFunction)
 	 *
@@ -509,15 +505,14 @@ private Lifecycle() {
 	 * of the method invocations throws an exception. The first exception thrown
 	 * is rethrown after invoking the method on the remaining objects, all other
 	 * exceptions are swallowed.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * final var streams = new ArrayList<InputStream>();
 	 * streams.add(new FileInputStream(file1));
 	 * streams.add(new FileInputStream(file2));
 	 * streams.add(new FileInputStream(file3));
 	 * // ...
 	 * invokeAll(Closeable::close, streams);
-	 * }</pre>
+	 * }
 	 *
 	 * @param <A> the closeable object type
 	 * @param <E> the exception type

facilejdbc/src/main/java/io/jenetics/facilejdbc/MultiParam.java

@@ -28,10 +28,9 @@
  * Represents a query parameter with <em>name</em> and one or more <em>values</em>.
  * The parameter values are evaluated lazily. But it is also possible to create
  * {@code MultiParam} objects with eagerly evaluated values.
- *
- * <pre>{@code
+ * {@snippet lang="java":
  * SELECT_QUERY.on(Param.values("ids", 1, 2, 3, 4))
- * }</pre>
+ * }
  *
  * @see SingleParam
  * @see SingleParam#values(String, Iterable)

facilejdbc/src/main/java/io/jenetics/facilejdbc/Param.java

@@ -34,18 +34,18 @@
  * class.
  * <p>
  * Creating single-valued parameters:
- * <pre>{@code
+ * {@snippet lang="java":
  * INSERT_QUERY.on(
  *     Param.value("forename", "Werner"),
  *     Param.value("birthday", LocalDate.now()),
  *     Param.value("email", "some.email@gmail.com"))
- * }</pre>
+ * }
  *
  * Creating multivalued parameters:
- * <pre>{@code
+ * {@snippet lang="java":
  * Query.of("SELECT * FROM table WHERE id = IN(:ids);")
  *     .on(Param.values("ids", 1, 2, 3, 4))
- * }</pre>
+ * }
  *
  * @see SingleParam
  * @see MultiParam
@@ -70,12 +70,11 @@ public sealed interface Param permits SingleParam, MultiParam {
 	/**
 	 * Create a new query parameter object for the given {@code name} and
 	 * {@code value}.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * final var result = Query.of("SELECT * FROM table WHERE id = :id;")
 	 *     .on(Param.value("id", 43245)
 	 *     .as(PARSER.singleOpt(), conn);
-	 * }</pre>
+	 * }
 	 *
 	 * @param name the parameter name
 	 * @param value the parameter values, which may be {@code null}
@@ -93,12 +92,11 @@ static SingleParam value(final String name, final Object value) {
 	/**
 	 * Create a new (multi) query parameter object for the given {@code name}
 	 * and the given {@code values}.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * final var result = Query.of("SELECT * FROM table WHERE id = IN(:ids);")
 	 *     .on(Param.values("ids", List.of(43245, 434, 23, 987, 1239))
 	 *     .as(PARSER.list(), conn);
-	 * }</pre>
+	 * }
 	 *
 	 * @since 1.3
 	 *
@@ -130,12 +128,11 @@ private static <T> Stream<T> stream(final Iterable<? extends T> values) {
 	/**
 	 * Create a new (multi) query parameter object for the given {@code name}
 	 * and the given {@code values}.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * final var result = Query.of("SELECT * FROM table WHERE id = IN(:ids);")
 	 *     .on(Param.values("ids", 43245, 434, 23, 987, 1239)
 	 *     .as(PARSER.list(), conn);
-	 * }</pre>
+	 * }
 	 *
 	 * @since 1.3
 	 *
@@ -155,12 +152,11 @@ static MultiParam values(final String name, final Object... values) {
 	/**
 	 * Create a new query parameter object from the given {@code name} and
 	 * lazily evaluated {@code value}.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * final var result = Query.of("SELECT * FROM table WHERE date < :date;")
 	 *     .on(Param.lazyValue("date", LocalDate::now)
 	 *     .as(PARSER.singleOpt(), conn);
-	 * }</pre>
+	 * }
 	 *
 	 * @param name the parameter name
 	 * @param value the lazily evaluated parameter value
@@ -178,14 +174,13 @@ static SingleParam lazyValue(final String name, final SqlSupplier<?> value) {
 	/**
 	 * Create a new query parameter object for the given {@code name} and
 	 * lazily evaluated {@code values}.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * final SqlSupplier<Integer> id1 = ...;
 	 * final SqlSupplier<Integer> id2 = ...;
 	 * final var result = Query.of("SELECT * FROM table WHERE id = IN(:ids);")
 	 *     .on(Param.lazyValues("id", List.of(id1, id2))
 	 *     .as(PARSER.list(), conn);
-	 * }</pre>
+	 * }
 	 *
 	 * @param name the parameter name
 	 * @param values the parameter values
@@ -209,12 +204,11 @@ static MultiParam lazyValues(
 	/**
 	 * Create a new query parameter object for the given {@code name} and
 	 * lazily evaluated {@code values}.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * final var result = Query.of("SELECT * FROM table WHERE id = IN(:ids);")
 	 *     .on(Param.lazyValues("id", () -> 324, () -> 9967))
 	 *     .as(PARSER.list(), conn);
-	 * }</pre>
+	 * }
 	 *
 	 * @param name the parameter name
 	 * @param values the parameter values

facilejdbc/src/main/java/io/jenetics/facilejdbc/Query.java

@@ -52,8 +52,7 @@
 
 /**
  * A {@code Query} represents an executable piece of SQL text.
- *
- * <pre>{@code
+ * {@snippet lang="java":
  * private static final Query SELECT = Query.of("""
  *     SELECT * FROM person
  *     WHERE forename like :forename
@@ -66,7 +65,7 @@
  *     VALUES(:forename, :surname, :birthday, :email);
  *     """
  * );
- * }</pre>
+ * }
  *
  * @apiNote
  * This class is immutable and thread-safe.
@@ -111,11 +110,11 @@ public String sql() {
 	/**
 	 * Return the original SQL string, this object is created with. So the
 	 * following assertion holds for every possible SQL string;
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * final String sql = "SELECT * FROM table WHERE id = :id;";
 	 * final Query query = Query.of(sql);
 	 * assert sql.equals(query.rawSql());
-	 * }</pre>
+	 * }
 	 *
 	 * @since 1.1
 	 *
@@ -209,12 +208,11 @@ public Query withTimeout(final Duration timeout) {
 
 	/**
 	 * Return a new query object with the given query parameter values.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * final var result = Query.of("SELECT * FROM table WHERE id = :id;")
-	 *     .on(List.of(Param.value("id", 43245))
+	 *     .on(List.of(Param.value("id", 43245)))
 	 *     .as(PARSER.singleOpt(), conn);
-	 * }</pre>
+	 * }
 	 *
 	 * @see #on(Param...)
 	 * @see #on(Map)
@@ -279,12 +277,11 @@ private static Stream<SingleParam> toParams(final MultiParam param) {
 
 	/**
 	 * Return a new query object with the given query parameter values.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * final var result = Query.of("SELECT * FROM table WHERE id = :id;")
-	 *     .on(Param.value("id", 43245)
+	 *     .on(Param.value("id", 43245))
 	 *     .as(PARSER.singleOpt(), conn);
-	 * }</pre>
+	 * }
 	 *
 	 * @param params the query parameters
 	 * @return a new query object with the set parameters
@@ -298,12 +295,11 @@ public Query on(final Param... params) {
 
 	/**
 	 * Return a new query object with the given query parameter values.
-	 *
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * final var result = Query.of("SELECT * FROM table WHERE id = :id;")
 	 *     .on(Map.of("id", 43245))
 	 *     .as(PARSER.singleOpt(), conn);
-	 * }</pre>
+	 * }
 	 *
 	 * @param params the query parameters
 	 * @return a new query object with the set parameters
@@ -624,7 +620,7 @@ public String toString() {
 
 	/**
 	 * Create a new query object from the given SQL string.
-	 * <pre>{@code
+	 * {@snippet lang="java":
 	 * private static final Query SELECT = Query.of("""
 	 *     SELECT * FROM person
 	 *     WHERE forename like :forename
@@ -637,7 +633,7 @@ public String toString() {
 	 *     VALUES(:forename, :surname, :birthday, :email);
 	 *     """
 	 * );
-	 * }</pre>
+	 * }
 	 *
 	 * @param sql the SQL string of the created query
 	 * @return a new query object from the given SQL string