Gradle: Added buildSrc (1/3)

Added library conventions and language based configurations.

- Added `doclets` to `buildSrc` for the `javadocs`
- Added `conventions` to centralize configuration of gradle plugins
- Added `projects` to handle project level conventions

JAVA-5758
JAVA-5757

Author: rozza

buildSrc/build.gradle.kts

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.
+ */
+import dev.panuszewski.gradle.pluginMarker
+
+plugins {
+    id("java-library")
+    `kotlin-dsl`
+    alias(libs.plugins.spotless)
+    alias(libs.plugins.detekt) apply false
+}
+
+repositories {
+    gradlePluginPortal()
+    mavenCentral()
+    google()
+}
+
+// Dependencies needed for the configuration of the plugins
+// Uses `pluginMarker` from the `typesafe-conventions` plugin, see `settings.gradle.kts`
+dependencies {
+    implementation(pluginMarker(libs.plugins.bnd))
+    implementation(pluginMarker(libs.plugins.detekt))
+    implementation(pluginMarker(libs.plugins.dokka))
+    implementation(pluginMarker(libs.plugins.kotlin.gradle))
+    implementation(pluginMarker(libs.plugins.spotbugs))
+    implementation(pluginMarker(libs.plugins.spotless))
+    implementation(pluginMarker(libs.plugins.test.logger))
+}
+
+// Spotless configuration for `buildSrc` code.
+spotless {
+    kotlinGradle {
+        target("**/*.gradle.kts")
+        ktfmt("0.39").dropboxStyle().configure { it.setMaxWidth(120) }
+        trimTrailingWhitespace()
+        indentWithSpaces()
+        endWithNewline()
+        licenseHeaderFile(
+            "../config/mongodb.license", "(package|group|plugins|import|buildscript|rootProject|@Suppress)")
+    }
+
+    kotlin {
+        target("**/*.kt")
+        ktfmt().dropboxStyle().configure { it.setMaxWidth(120) }
+        trimTrailingWhitespace()
+        indentWithSpaces()
+        endWithNewline()
+        licenseHeaderFile(rootProject.file("../config/mongodb.license"))
+    }
+
+    java {
+        palantirJavaFormat()
+        target("src/*/java/**/*.java")
+        removeUnusedImports()
+        trimTrailingWhitespace()
+        indentWithSpaces()
+        endWithNewline()
+        licenseHeaderFile(rootProject.file("../config/mongodb.license"))
+    }
+}
+
+java { toolchain { languageVersion.set(JavaLanguageVersion.of("17")) } }
+
+tasks.findByName("check")?.dependsOn("spotlessCheck")

buildSrc/settings.gradle.kts

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.
+ */
+plugins {
+    // Add support for `libs.versions.toml` within `buildSrc`
+    // https://github.com/radoslaw-panuszewski/typesafe-conventions-gradle-plugin
+    // https://github.com/gradle/gradle/issues/15383
+    id("dev.panuszewski.typesafe-conventions") version "0.4.1"
+}

buildSrc/src/main/java/com/mongodb/doclet/AtlasManualTaglet.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.mongodb.doclet;
+
+public final class AtlasManualTaglet extends DocTaglet {
+    @Override
+    public String getName() {
+        return "mongodb.atlas.manual";
+    }
+
+    @Override
+    protected String getHeader() {
+        return "MongoDB Atlas documentation";
+    }
+
+    @Override
+    protected String getBaseDocURI() {
+        return "https://www.mongodb.com/docs/atlas/";
+    }
+}

buildSrc/src/main/java/com/mongodb/doclet/DocTaglet.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.mongodb.doclet;
+
+import static java.util.Arrays.asList;
+import static jdk.javadoc.doclet.Taglet.Location.CONSTRUCTOR;
+import static jdk.javadoc.doclet.Taglet.Location.FIELD;
+import static jdk.javadoc.doclet.Taglet.Location.METHOD;
+import static jdk.javadoc.doclet.Taglet.Location.OVERVIEW;
+import static jdk.javadoc.doclet.Taglet.Location.PACKAGE;
+import static jdk.javadoc.doclet.Taglet.Location.TYPE;
+
+import com.sun.source.doctree.DocTree;
+import com.sun.source.doctree.UnknownBlockTagTree;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import javax.lang.model.element.Element;
+import jdk.javadoc.doclet.Taglet;
+
+public abstract class DocTaglet implements Taglet {
+
+    @Override
+    public Set<Location> getAllowedLocations() {
+        return new HashSet<>(asList(CONSTRUCTOR, METHOD, FIELD, OVERVIEW, PACKAGE, TYPE));
+    }
+
+    @Override
+    public boolean isInlineTag() {
+        return false;
+    }
+
+    @Override
+    public String toString(List<? extends DocTree> tags, Element element) {
+        if (tags.size() == 0) {
+            return null;
+        }
+
+        StringBuilder buf =
+                new StringBuilder(String.format("<dl><dt><span class=\"strong\">%s</span></dt>", getHeader()));
+        for (DocTree tag : tags) {
+            String text = ((UnknownBlockTagTree) tag).getContent().get(0).toString();
+            buf.append("<dd>").append(genLink(text)).append("</dd>");
+        }
+        return buf.toString();
+    }
+
+    protected String genLink(final String text) {
+        String relativePath = text;
+        String display = text;
+
+        int firstSpace = text.indexOf(' ');
+        if (firstSpace != -1) {
+            relativePath = text.substring(0, firstSpace);
+            display = text.substring(firstSpace).trim();
+        }
+
+        return String.format("<a href='%s%s'>%s</a>", getBaseDocURI(), relativePath, display);
+    }
+
+    protected abstract String getHeader();
+
+    protected abstract String getBaseDocURI();
+}

buildSrc/src/main/java/com/mongodb/doclet/DochubTaglet.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.mongodb.doclet;
+
+public class DochubTaglet extends DocTaglet {
+
+    @Override
+    public String getName() {
+        return "mongodb.driver.dochub";
+    }
+
+    @Override
+    protected String getHeader() {
+        return "MongoDB documentation";
+    }
+
+    @Override
+    protected String getBaseDocURI() {
+        return "https://dochub.mongodb.org/";
+    }
+}

buildSrc/src/main/java/com/mongodb/doclet/ManualTaglet.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.mongodb.doclet;
+
+public class ManualTaglet extends DocTaglet {
+
+    @Override
+    public String getName() {
+        return "mongodb.driver.manual";
+    }
+
+    @Override
+    protected String getHeader() {
+        return "MongoDB documentation";
+    }
+
+    @Override
+    protected String getBaseDocURI() {
+        return "https://www.mongodb.com/docs/manual/";
+    }
+}

buildSrc/src/main/java/com/mongodb/doclet/ServerReleaseTaglet.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.mongodb.doclet;
+
+public class ServerReleaseTaglet extends DocTaglet {
+
+    @Override
+    public String getName() {
+        return "mongodb.server.release";
+    }
+
+    @Override
+    protected String getHeader() {
+        return "Since server release";
+    }
+
+    @Override
+    protected String getBaseDocURI() {
+        return "https://www.mongodb.com/docs/manual/release-notes/";
+    }
+}

buildSrc/src/main/kotlin/ProjectExtensions.kt

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.
+ */
+import org.gradle.api.Project
+import org.gradle.api.java.archives.Manifest
+import org.gradle.api.publish.maven.MavenPublication
+import org.gradle.api.tasks.bundling.Jar
+import org.gradle.kotlin.dsl.named
+import org.gradle.kotlin.dsl.withType
+
+object ProjectExtensions {
+
+    /**
+     * Extension function to get and validate the current scala version
+     *
+     * See: gradle.properties for `supportedScalaVersions` and `defaultScalaVersion`
+     */
+    fun Project.scalaVersion(): String {
+        val supportedScalaVersions = (project.property("supportedScalaVersions") as String).split(",")
+        val scalaVersion: String =
+            (project.findProperty("scalaVersion") ?: project.property("defaultScalaVersion")) as String
+
+        if (!supportedScalaVersions.contains(scalaVersion)) {
+            throw UnsupportedOperationException(
+                """Scala version: $scalaVersion is not a supported scala version.
+                |Supported versions: $supportedScalaVersions
+            """
+                    .trimMargin())
+        }
+
+        return scalaVersion
+    }
+
+    /** Extension function to configure the maven publication */
+    fun Project.configureMavenPublication(configure: MavenPublication.() -> Unit = {}) {
+        val publishing = extensions.getByName("publishing") as org.gradle.api.publish.PublishingExtension
+        publishing.publications.named<MavenPublication>("maven") { configure() }
+    }
+
+    /** Extension function to configure the jars manifest */
+    fun Project.configureJarManifest(configure: Manifest.() -> Unit = {}) {
+        tasks.withType<Jar> { manifest { configure() } }
+    }
+}