[jOOQ/jOOQ#2026] Add new @Internal annotation

This new annotation signifies that a given public type, method, or field
is in fact internal API and should not be used in client code.

jOOQ/src/main/java/org/jooq/Internal.java

@@ -0,0 +1,59 @@
+/*
+ * 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.
+ *
+ * Other licenses:
+ * -----------------------------------------------------------------------------
+ * Commercial licenses for this work are available. These replace the above
+ * ASL 2.0 and offer limited warranties, support, maintenance, and commercial
+ * database integrations.
+ *
+ * For more information, please visit: http://www.jooq.org/licenses
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ */
+package org.jooq;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Signifies that a API (public class, method or field) is internal and subject to incompatible
+ * changes, or even removal, in a future release. An API bearing this annotation is exempt from any
+ * compatibility guarantees made by its containing library.
+ *
+ * @author Knut Wannheden
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target(value={FIELD, METHOD, TYPE})
+public @interface Internal {}

jOOQ/src/main/java/org/jooq/util/jaxb/tools/MiniJAXB.java

@@ -64,6 +64,7 @@ import javax.xml.parsers.DocumentBuilder;
 import javax.xml.parsers.DocumentBuilderFactory;
 import javax.xml.parsers.ParserConfigurationException;
 
+import org.jooq.Internal;
 import org.jooq.exception.ConfigurationException;
 import org.jooq.tools.Convert;
 import org.jooq.tools.reflect.Reflect;
@@ -86,6 +87,7 @@ import org.xml.sax.InputSource;
  *
  * @author Lukas Eder
  */
+@Internal
 public class MiniJAXB {
 
     public static String marshal(XMLAppendable object) {

jOOQ/src/main/java/org/jooq/util/jaxb/tools/XMLAppendable.java

@@ -37,6 +37,19 @@
  */
 package org.jooq.util.jaxb.tools;
 
+import org.jooq.Internal;
+
+/**
+ * Interface to be implemented by JAXB annotated Java classes which are
+ * serialized to XML using {@link XMLBuilder}.
+ * <p>
+ * The implementing classes are expected to call the various {@code append()}
+ * methods on the {@link XMLBuilder} instance.
+ *
+ * @author Knut Wannheden
+ */
+@Internal
 public interface XMLAppendable {
+
     void appendTo(XMLBuilder builder);
 }

jOOQ/src/main/java/org/jooq/util/jaxb/tools/XMLBuilder.java

@@ -41,9 +41,20 @@ import java.io.IOException;
 import java.util.List;
 import java.util.regex.Pattern;
 
+import org.jooq.Internal;
+
 /**
+ * Wrapper around a {@link StringBuilder} which can be used to serialize
+ * a JAXB-annotated Java object graph to XML. The JAXB objects must however
+ * also implement the {@link XMLAppendable} interface for this to work.
+ * <p>
+ * Use {@link #formatting()} to create an instance producing formatted XML
+ * output and {@link #nonFormatting()} to produce XML without any formatting
+ * whitespace (i.e. everything on one line).
+ *
  * @author Knut Wannheden
  */
+@Internal
 public class XMLBuilder {
 
     private final StringBuilder builder = new StringBuilder();