Add annotations for API visibility/stability

core/src/main/java/org/htsjdk/core/api/annotations/Advanced.java

@@ -0,0 +1,42 @@
+package org.htsjdk.core.api.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotates a public API as Advanced.
+ *
+ * <p>Advanced signifies that public API is for advance-usage only, and typical usages are covered
+ * by other API.
+ *
+ * <p>Examples:
+ *
+ * <ul>
+ *     <li>
+ *         Setters that might left the record in an inconsistent stage. Setters with validation
+ *         and/or extra-steps might be used instead, unless necessary.
+ *     </li>
+ *     <li>
+ *         Specialized classes that might be used in delegates or wrappers, but where the major
+ *         functionality could be used through the interface.
+ *     </li>
+ *     <li>
+ *         Methods containing unsafe operations, where a different method could do the same operation
+ *         in a safer way in most of the cases.
+ *     </li>
+ * </ul>
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({
+        ElementType.ANNOTATION_TYPE,
+        ElementType.CONSTRUCTOR,
+        ElementType.FIELD,
+        ElementType.METHOD,
+        ElementType.TYPE
+})
+@Documented
+public @interface Advanced {
+}

core/src/main/java/org/htsjdk/core/api/annotations/Beta.java

@@ -0,0 +1,28 @@
+package org.htsjdk.core.api.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotates a public API as Beta.
+ *
+ * <p>Beta signifies that public API could be change without notice in future releases, but
+ * <em>not removed</em>. Removal of {@link Beta} annotation signifies that the public API is
+ * stable and changes suppose a major version bump.
+ *
+ * @see Experimental
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({
+        ElementType.ANNOTATION_TYPE,
+        ElementType.CONSTRUCTOR,
+        ElementType.FIELD,
+        ElementType.METHOD,
+        ElementType.TYPE
+})
+@Documented
+public @interface Beta {
+}

core/src/main/java/org/htsjdk/core/api/annotations/Experimental.java

@@ -0,0 +1,28 @@
+package org.htsjdk.core.api.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotates a public API as Experimental.
+ *
+ * <p>Experimental signifies that public API could be change or <em>removed</em> without notice
+ * in future releases. A {@link Experimental} API could be upgraded to {@link Beta} if not removal
+ * is predicted but API is unstable.
+ *
+ * @see Beta
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({
+        ElementType.ANNOTATION_TYPE,
+        ElementType.CONSTRUCTOR,
+        ElementType.FIELD,
+        ElementType.METHOD,
+        ElementType.TYPE
+})
+@Documented
+public @interface Experimental {
+}

core/src/main/java/org/htsjdk/core/api/annotations/Private.java

@@ -0,0 +1,37 @@
+package org.htsjdk.core.api.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotates a public API as Private.
+ *
+ * <p>Private signifies that public API should be considered as private code and not used by
+ * client-code. This API will be changed without notice as its usage only supported when it is
+ * internal.
+ *
+ * <p>Examples:
+ *
+ * <ul>
+ *     <li>Internal packages ("*.internal").</li>
+ *     <li>Public API only for sharing internaly but that should be located in non-internal packages.</li>
+ *     <li>Public API only for testing (e.g., {@link VisibleForTesting}.</li>
+ * </ul>
+ *
+ * @see VisibleForTesting
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({
+        ElementType.PACKAGE,
+        ElementType.ANNOTATION_TYPE,
+        ElementType.CONSTRUCTOR,
+        ElementType.FIELD,
+        ElementType.METHOD,
+        ElementType.TYPE
+})
+@Documented
+public @interface Private {
+}

core/src/main/java/org/htsjdk/core/api/annotations/VisibleForTesting.java

@@ -0,0 +1,21 @@
+package org.htsjdk.core.api.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * Annotates a public API as visible for testing.
+ *
+ * <p>Visible for testing signifies that public API is visible only for testing purposes; thus,
+ * they are not supposed to be used by client-code.
+ *
+ * <p>{@link VisibleForTesting} indicates the reason for make public a private API, which should
+ * be also marked as {@link Private}.
+ *
+ * @see Private
+ */
+@Retention(RetentionPolicy.CLASS)
+@Documented
+public @interface VisibleForTesting {
+}

core/src/main/java/org/htsjdk/core/utils/ParamUtils.java → core/src/main/java/org/htsjdk/core/utils/internal/ParamUtils.java

@@ -1,4 +1,6 @@
-package org.htsjdk.core.utils;
+package org.htsjdk.core.utils.internal;
+
+import org.htsjdk.core.api.annotations.Private;
 
 import java.util.Collection;
 import java.util.function.Supplier;
@@ -9,6 +11,7 @@
  * <p>All the methods in this class throw {@link IllegalArgumentException} if conditions are not
  * met.
  */
+@Private
 public final class ParamUtils {
 
     // cannot be instantiated

core/src/main/java/org/htsjdk/core/utils/internal/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Internal utils.
+ */
+@Private
+package org.htsjdk.core.utils.internal;
+
+import org.htsjdk.core.api.annotations.Private;

core/src/test/java/org/htsjdk/core/utils/ParamUtilsTest.java → core/src/test/java/org/htsjdk/core/utils/internal/ParamUtilsTest.java

@@ -1,4 +1,4 @@
-package org.htsjdk.core.utils;
+package org.htsjdk.core.utils.internal;
 
 import org.htsjdk.test.HtsjdkBaseTest;
 import org.testng.Assert;