Reduce visibility of SQL-related classes and improve docs a bit

This builds upon @baptistemesta's great work on introducing a
DBeaver-based SQL formatter step in spotless-lib, by:
1. Reducing the visibility of those classes that I consider to be
   implementation details, and annotating those classes which I cannot
   hide away as `@Internal`.
2. Adding warnings to those classes that are more difficult
   to change that they may disappear in future versions.
3. Changing the docs to make it clearer that we are including DBeaver
   sources in Spotless and that, as far as we know, we can legally
   include them in Spotless since both projects are licensed under the
   Apache 2.0 license.
4. And doing minor cleanups here and there, like removing redundant
   comments, renaming a class for clarity, and fixing up a claim that
   the DBeaver formatter step comes from Hibernate.

Author: jbduncan

lib/src/main/java/com/diffplug/spotless/annotations/Internal.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2016 DiffPlug
+ *
+ * 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 com.diffplug.spotless.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;
+
+/**
+ * Signifies that a `public` API is actually an implementation detail, and should be treated as if it
+ * were `private`.
+ *
+ * The user of the API should be warned that it may unexpectedly disappear in future versions of
+ * Spotless. Usually the best place to put this warning is in the API's class JavaDoc.
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({
+		ElementType.ANNOTATION_TYPE,
+		ElementType.CONSTRUCTOR,
+		ElementType.FIELD,
+		ElementType.METHOD,
+		ElementType.TYPE
+})
+@Documented
+public @interface Internal {
+
+}

lib/src/main/java/com/diffplug/spotless/sql/DBeaverSQLFormatter.java

@@ -17,7 +17,7 @@
 
 import java.util.Properties;
 
-import com.diffplug.spotless.sql.dbeaver.SQLFormatterConfiguration;
+import com.diffplug.spotless.sql.dbeaver.DBeaverSQLFormatterConfiguration;
 import com.diffplug.spotless.sql.dbeaver.SQLTokenizedFormatter;
 
 /**
@@ -28,7 +28,7 @@ public class DBeaverSQLFormatter {
 	private final SQLTokenizedFormatter sqlTokenizedFormatter;
 
 	DBeaverSQLFormatter(Properties properties) {
-		SQLFormatterConfiguration configuration = new SQLFormatterConfiguration(properties);
+		DBeaverSQLFormatterConfiguration configuration = new DBeaverSQLFormatterConfiguration(properties);
 		sqlTokenizedFormatter = new SQLTokenizedFormatter(configuration);
 	}
 

lib/src/main/java/com/diffplug/spotless/sql/DBeaverSQLFormatterStep.java

@@ -23,10 +23,10 @@
 import com.diffplug.spotless.FormatterProperties;
 import com.diffplug.spotless.FormatterStep;
 
-/** Wraps up [BasicFormatterImpl](https://docs.jboss.org/hibernate/orm/4.1/javadocs/org/hibernate/engine/jdbc/internal/BasicFormatterImpl.html) as a FormatterStep. */
+/** SQL formatter step which wraps up DBeaver's SqlTokenizedFormatter implementation. */
 public class DBeaverSQLFormatterStep {
 
-	static final String NAME = "dbeaverSql";
+	private static final String NAME = "dbeaverSql";
 
 	// prevent direct instantiation
 	private DBeaverSQLFormatterStep() {}
@@ -40,17 +40,16 @@ public static FormatterStep create(Iterable<File> files) {
 	static final class State implements Serializable {
 		private static final long serialVersionUID = 1L;
 
-		/** The signature of the settings file. */
-		final FileSignature settings;
+		final FileSignature settingsSignature;
 
 		State(final Iterable<File> settingsFiles) throws Exception {
-			this.settings = FileSignature.signAsList(settingsFiles);
+			this.settingsSignature = FileSignature.signAsList(settingsFiles);
 		}
 
 		FormatterFunc createFormat() throws Exception {
-			FormatterProperties preferences = FormatterProperties.from(settings.files());
-			DBeaverSQLFormatter DBeaverSqlFormatter = new DBeaverSQLFormatter(preferences.getProperties());
-			return DBeaverSqlFormatter::format;
+			FormatterProperties preferences = FormatterProperties.from(settingsSignature.files());
+			DBeaverSQLFormatter dbeaverSqlFormatter = new DBeaverSQLFormatter(preferences.getProperties());
+			return dbeaverSqlFormatter::format;
 		}
 	}
 }

lib/src/main/java/com/diffplug/spotless/sql/dbeaver/DBPKeywordType.java

@@ -20,8 +20,9 @@
  * DBeaver - Universal Database Manager
  * Copyright (C) 2010-2017 Serge Rider ([email protected])
  *
-* Database keyword type
-*/
-public enum DBPKeywordType {
+ * Based on DBPKeywordType from https://github.com/serge-rider/dbeaver,
+ * which itself is licensed under the Apache 2.0 license.
+ */
+enum DBPKeywordType {
 	KEYWORD, FUNCTION, TYPE, OTHER
 }

lib/src/main/java/com/diffplug/spotless/sql/dbeaver/SQLFormatterConfiguration.java renamed to lib/src/main/java/com/diffplug/spotless/sql/dbeaver/DBeaverSQLFormatterConfiguration.java

@@ -17,34 +17,45 @@
 
 import java.util.Properties;
 
+import com.diffplug.spotless.annotations.Internal;
+
 /**
- * SQLFormatterConfiguration
+ * **Warning:** Use this class at your own risk. It is an implementation detail and is not
+ * guaranteed to exist in future versions.
+ *
+ * Forked from
+ * DBeaver - Universal Database Manager
+ * Copyright (C) 2010-2017 Serge Rider ([email protected])
+ *
+ * Based on SQLFormatterConfiguration from https://github.com/serge-rider/dbeaver,
+ * which itself is licensed under the Apache 2.0 license.
  */
-public class SQLFormatterConfiguration {
+@Internal
+public class DBeaverSQLFormatterConfiguration {
 
 	/**
 	 * UPPER, LOWER or ORIGINAL
 	 */
-	public static final String SQL_FORMATTER_KEYWORD_CASE = "sql.formatter.keyword.case";
+	private static final String SQL_FORMATTER_KEYWORD_CASE = "sql.formatter.keyword.case";
 
 	/**
 	 * ';' by default
 	 */
-	public static final String SQL_FORMATTER_STATEMENT_DELIMITER = "sql.formatter.statement.delimiter";
+	private static final String SQL_FORMATTER_STATEMENT_DELIMITER = "sql.formatter.statement.delimiter";
 	/**
 	 * space or tag
 	 */
-	public static final String SQL_FORMATTER_INDENT_TYPE = "sql.formatter.indent.type";
+	private static final String SQL_FORMATTER_INDENT_TYPE = "sql.formatter.indent.type";
 	/**
 	 * 4 by default
 	 */
-	public static final String SQL_FORMATTER_INDENT_SIZE = "sql.formatter.indent.size";
+	private static final String SQL_FORMATTER_INDENT_SIZE = "sql.formatter.indent.size";
 
 	private String statementDelimiters;
 	private KeywordCase keywordCase;
 	private String indentString;
 
-	public SQLFormatterConfiguration(Properties properties) {
+	public DBeaverSQLFormatterConfiguration(Properties properties) {
 		this.keywordCase = KeywordCase.valueOf(properties.getProperty(SQL_FORMATTER_KEYWORD_CASE, "UPPER"));
 		this.statementDelimiters = properties.getProperty(SQL_FORMATTER_STATEMENT_DELIMITER, SQLDialect.INSTANCE
 				.getScriptDelimiter());

lib/src/main/java/com/diffplug/spotless/sql/dbeaver/FormatterToken.java

@@ -15,19 +15,27 @@
  */
 package com.diffplug.spotless.sql.dbeaver;
 
+/*
+ * Forked from
+ * DBeaver - Universal Database Manager
+ * Copyright (C) 2010-2017 Serge Rider ([email protected])
+ *
+ * Based on FormatterToken from https://github.com/serge-rider/dbeaver,
+ * which itself is licensed under the Apache 2.0 license.
+ */
 class FormatterToken {
 
 	private TokenType fType;
 	private String fString;
 	private int fPos = -1;
 
-	public FormatterToken(final TokenType argType, final String argString, final int argPos) {
+	FormatterToken(final TokenType argType, final String argString, final int argPos) {
 		fType = argType;
 		fString = argString;
 		fPos = argPos;
 	}
 
-	public FormatterToken(final TokenType argType, final String argString) {
+	FormatterToken(final TokenType argType, final String argString) {
 		this(argType, argString, -1);
 	}
 

lib/src/main/java/com/diffplug/spotless/sql/dbeaver/KeywordCase.java

@@ -20,7 +20,7 @@
 /**
  * @author Baptiste Mesta.
  */
-public enum KeywordCase {
+enum KeywordCase {
 	UPPER {
 		public String transform(String value) {
 			return value.toUpperCase(Locale.ENGLISH);

lib/src/main/java/com/diffplug/spotless/sql/dbeaver/Pair.java

@@ -16,30 +16,35 @@
 package com.diffplug.spotless.sql.dbeaver;
 
 /**
- * Pair
+ * Forked from
+ * DBeaver - Universal Database Manager
+ * Copyright (C) 2010-2017 Serge Rider ([email protected])
+ *
+ * Based on Pair from https://github.com/serge-rider/dbeaver,
+ * which itself is licensed under the Apache 2.0 license.
  */
-public class Pair<T1, T2> {
+class Pair<T1, T2> {
 	private T1 first;
 	private T2 second;
 
-	public Pair(T1 first, T2 second) {
+	Pair(T1 first, T2 second) {
 		this.first = first;
 		this.second = second;
 	}
 
-	public T1 getFirst() {
+	T1 getFirst() {
 		return first;
 	}
 
-	public void setFirst(T1 first) {
+	void setFirst(T1 first) {
 		this.first = first;
 	}
 
-	public T2 getSecond() {
+	T2 getSecond() {
 		return second;
 	}
 
-	public void setSecond(T2 second) {
+	void setSecond(T2 second) {
 		this.second = second;
 	}
 

lib/src/main/java/com/diffplug/spotless/sql/dbeaver/SQLConstants.java

@@ -20,7 +20,8 @@
  * DBeaver - Universal Database Manager
  * Copyright (C) 2010-2017 Serge Rider ([email protected])
  *
- * SQL editor constants
+ * Based on SQLConstants from https://github.com/serge-rider/dbeaver,
+ * which itself is licensed under the Apache 2.0 license.
  */
 class SQLConstants {
 

lib/src/main/java/com/diffplug/spotless/sql/dbeaver/SQLDialect.java

@@ -15,10 +15,21 @@
  */
 package com.diffplug.spotless.sql.dbeaver;
 
-import java.util.*;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Locale;
+import java.util.Set;
+import java.util.TreeMap;
+import java.util.TreeSet;
 
 /**
- * Basic SQL Dialect
+ * Forked from
+ * DBeaver - Universal Database Manager
+ * Copyright (C) 2010-2017 Serge Rider ([email protected])
+ *
+ * Based on SQLDialect from https://github.com/serge-rider/dbeaver,
+ * which itself is licensed under the Apache 2.0 license.
  */
 class SQLDialect {