Issue #68: Generate documentation for SQL connectors

src/it/metricshub-connectors/src/main/connector/database/Database/Database.yaml

@@ -0,0 +1,26 @@
+metrics:
+  db.io:
+    description: The number of bytes sent or received to/from all clients.
+    type: Counter
+    unit: By
+  db.connections:
+    description: The number of connection attempts (successful or not) to the database.
+    type: Counter
+    unit: "{connection}"
+  db.client.connection.count:
+    description: The number of client connections to the database.
+    type: UpDownCounter
+    unit: "{connection}"
+  db.uptime:
+    description: The total number of seconds the server has been up.
+    type: Gauge
+    unit: s
+  db.queries:
+    description: The total number of statements executed by the server.
+    type: Counter
+    unit: "{statement}"
+  db.tables:
+    description: The total number of tables in the database.
+    type: Gauge
+    unit: "{table}"
+

src/it/metricshub-connectors/src/site/site.xml

@@ -12,7 +12,7 @@
 
 	<custom>
 		<noDefaultLinks>true</noDefaultLinks>
-		<keywords>metricshub, connector, hardware, system</keywords>
+		<keywords>metricshub, connector, hardware, system, database</keywords>
 		<bodyClass>custom-class</bodyClass>
 	</custom>
 
@@ -29,17 +29,9 @@
 
 		<menu name="User Documentation">
 			<item name="Getting Started" href="index.html" />
+			<item name="Connectors Directory" href="metricshub-connectors-directory.html"/>
 		</menu>
 
-		<menu name="MetricsHub Connectors">
-			<item name="Supported Platforms" href="platform-requirements.html " />
-		</menu>
-
-		<menu name="Reference">
-			<item name="Reference" href="metricshub-connector-reference.html"/>
-		</menu>
-
-		<menu ref="reports" />
 	</body>
 
 </project>

src/it/metricshub-connectors/verify.groovy

@@ -31,6 +31,7 @@ assert htmlText.indexOf("WBEMGenDiskNT") > -1 : "metricshub-connectors-directory
 assert htmlText.indexOf("WBEMGenHBA") > -1 : "metricshub-connectors-directory: WBEMGenHBA must be listed"
 assert htmlText.indexOf("WBEMGenLUN") > -1 : "metricshub-connectors-directory: WBEMGenLUN must be listed"
 assert htmlText.indexOf("WBEMGenNetwork") > -1 : "metricshub-connectors-directory: WBEMGenNetwork must be listed"
+assert htmlText.indexOf("MySQL") > -1 : "metricshub-connectors-directory: MySQL must be listed"
 
 // Check generated reference files
 String directoryPath = 'target/site/connectors'
@@ -56,7 +57,8 @@ String [] fileNamesToCheck = [
 	'wbemgenhba.html',
 	'wbemgenlun.html',
 	'wbemgennetwork.html',
-	'winstoragespaces.html'
+	'winstoragespaces.html',
+	'mysql.html'
 ]
 
 fileNamesToCheck.each { fileName ->
@@ -74,6 +76,7 @@ String [] tagsFileNamesToCheck = [
 	'vm.html',
 	'hyper-v.html',
 	'hardware.html',
+	'database.html',
 ]
 
 String [] hardwareConnectors = [
@@ -257,3 +260,15 @@ assert htmlText.indexOf("Windows Storage Spaces") > -1 : "WinStoreSpaces: Unexpe
 assert htmlText.indexOf("WMI/WinRM") > -1 : "WinStoreSpaces: Unexpected Technology and protocols"
 assert htmlText.indexOf("<code>root\\Microsoft\\Windows\\Storage</code>") > -1 : "WinStoreSpaces: Unexpected namespaces"
 assert htmlText.indexOf("metricshub HOSTNAME -t storage -c +WinStorageSpaces --wmi -u USER") > -1 : "WinStoreSpaces: Page must indicate the expected CLI example."
+
+// MySQL
+htmlText = new File(basedir, "target/site/connectors/mysql.html").text
+assert htmlText.indexOf("Any platform running MySQL") > -1 : "MySQL: Unexpected Typical platform"
+assert htmlText.indexOf("Microsoft Windows, Linux") > -1 : "MySQL: Unexpected Operating Systems"
+assert htmlText.indexOf("MySQL Database") > -1 : "MySQL: Unexpected Leverages"
+assert htmlText.indexOf("SQL/JDBC") > -1 : "MySQL: Unexpected Technology and protocols"
+assert htmlText.indexOf("metricshub HOSTNAME -t win -c +MySQL --jdbc -u USER --jdbc-url URL") > -1 : "MySQL: Page must indicate the expected CLI example."
+assert htmlText.indexOf("<code>SELECT @@version_comment REGEXP 'mysql' AS is_mysql;</code>") > -1 : "MySQL: Page must indicate the activation criterion."
+assert htmlText.indexOf("Expected Result:") > -1 : "MySQL: Page must indicate the Expected Result message."
+assert htmlText.indexOf("<code>1</code>") > -1 : "MySQL: Page must indicate the expected result value."
+assert htmlText.indexOf('<h3 id="metrics">Metrics</h3>') > - 1 : "MySQL: Page must indicate 'Metrics' as HTML H3 element"

src/main/java/org/sentrysoftware/maven/metricshub/connector/producer/AbstractPageProducer.java

@@ -148,7 +148,7 @@ protected void buildConnectorsTable(
 				sink.tableCell();
 				final Set<TechnologyType> technologies = connectorJsonNodeReader.getTechnologies();
 				for (final TechnologyType technology : technologies) {
-					sink.text(technology.toString());
+					sink.text(technology.getDisplayName());
 					sink.lineBreak();
 				}
 

src/main/java/org/sentrysoftware/maven/metricshub/connector/producer/ConnectorPageProducer.java

@@ -533,6 +533,16 @@ private void produceMetricsHubExamplesContent(
 			appendYamlUsernameAndPassword(yamlBuilder);
 		}
 
+		if (technologies.contains(TechnologyType.SQL)) {
+			cli.append(" --jdbc -u USER --jdbc-url URL");
+			yamlBuilder.append("          jdbc:\n");
+			yamlBuilder.append("            port: <PORT>\n");
+			yamlBuilder.append("            database: <DB_NAME>\n");
+			yamlBuilder.append("            type: <type>\n");
+			yamlBuilder.append("            url: <URL>\n");
+			appendYamlUsernameAndPassword(yamlBuilder);
+		}
+
 		// Connector variable
 		if (connectorVariables != null && !connectorVariables.isEmpty()) {
 			yamlBuilder.append("        additionalConnectors:\n");

src/main/java/org/sentrysoftware/maven/metricshub/connector/producer/MainPageProducer.java

@@ -58,6 +58,7 @@ public MainPageProducer(Log logger, String connectorSubdirectoryName, String tag
 	 * @param mainSink               The main sink used for generating content.
 	 * @param connectors             The map of connector identifiers to their corresponding JsonNodes.
 	 * @param enterpriseConnectorIds The enterprise connector identifiers.
+	 * @param connectorTags          The set of connector tags.
 	 */
 	public void produce(
 		final Sink mainSink,

src/main/java/org/sentrysoftware/maven/metricshub/connector/producer/SinkHelper.java

@@ -125,6 +125,7 @@ public static String glyphIcon(final String iconName) {
 	 * Create a bootstrap badge with the following content.
 	 *
 	 * @param content text of the badge.
+	 * @param customClassname custom class name to apply to the badge.
 	 * @return the HTML code for this badge.
 	 */
 	public static String bootstrapLabel(@NonNull final String content, String customClassname) {
@@ -172,13 +173,21 @@ public static String replaceWithHtmlCode(final String value) {
 
 	/**
 	 * Creates an HTML hyperlink reference with the given content.
+	 *
+	 * @param link the URL to which the hyperlink points.
+	 * @param content the text to display as the clickable hyperlink.
+	 * @return a string containing the HTML code for the hyperlink
 	 */
 	public static String hyperlinkRef(final String link, final String content) {
 		return String.format("<a href=\"%s\">%s</a>", link, content);
 	}
 
 	/**
-	 * Creates an HTMP hyperlink reference with the given content and the specified classes.
+	 * Creates an HTML hyperlink reference with the given content.
+	 *
+	 * @param link the path in the `connector` directory.
+	 * @param content the text to display as the hyperlink.
+	 * @return string containing the HTML code for the hyperlink.
 	 */
 	public static String gitHubHyperlinkRef(final String link, final String content) {
 		return String.format(

src/main/java/org/sentrysoftware/maven/metricshub/connector/producer/model/common/ConnectorDefaultVariable.java

@@ -25,6 +25,9 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/**
+ * Represents a default variable for a connector.
+ */
 @NoArgsConstructor
 @AllArgsConstructor
 @Data

src/main/java/org/sentrysoftware/maven/metricshub/connector/producer/model/common/TechnologyType.java

@@ -58,7 +58,12 @@ public enum TechnologyType {
 	/**
 	 * Windows Management Instrumentation (WMI) / Windows Remote Management (WinRM)
 	 */
-	WMI("WMI/WinRM");
+	WMI("WMI/WinRM"),
+
+	/**
+	 * SQL through JDBC
+	 */
+	SQL("SQL/JDBC");
 
 	@Getter
 	private String displayName;
@@ -80,7 +85,8 @@ public enum TechnologyType {
 		"snmptable", SNMP,
 		"snmpget", SNMP,
 		"wbem", WBEM,
-		"wmi", WMI
+		"wmi", WMI,
+		"sql", SQL
 	);
 
 	// @formatter:on

src/main/java/org/sentrysoftware/maven/metricshub/connector/producer/model/criteria/CriterionFactory.java

@@ -64,6 +64,7 @@ public class CriterionFactory {
 		map.put("snmpgetnext", CriterionFactory::newSnmpGetNextCriterion);
 		map.put("wbem", CriterionFactory::newWbemCriterion);
 		map.put("wmi", CriterionFactory::newWmiCriterion);
+		map.put("sql", CriterionFactory::newSqlCriterion);
 
 		CRITERION_FACTORY_MAP = Collections.unmodifiableMap(map);
 	}
@@ -178,6 +179,16 @@ private static WmiCriterion newWmiCriterion(final JsonNode node) {
 		return new WmiCriterion(node);
 	}
 
+	/**
+	 * Creates a new {@link SqlCriterion} instance based on the provided {@link JsonNode}.
+	 *
+	 * @param node The {@link JsonNode} containing criterion configuration.
+	 * @return A new {@link SqlCriterion} instance.
+	 */
+	private static SqlCriterion newSqlCriterion(final JsonNode node) {
+		return new SqlCriterion(node);
+	}
+
 	/**
 	 * Creates an {@link Optional} instance containing an {@link AbstractCriterion} based on the provided {@link JsonNode} criterion type.
 	 *

src/main/java/org/sentrysoftware/maven/metricshub/connector/producer/model/criteria/CriterionSinkProduceVisitor.java

@@ -37,7 +37,7 @@
  *
  * @see ICriterionVisitor
  */
 @AllArgsConstructor
 public class CriterionSinkProduceVisitor implements ICriterionVisitor {
 
 	private static final String CODE_FORMAT = "<code>%s</code>";
@@ -320,4 +320,31 @@
 	public void visit(WmiCriterion wmiCriterion) {
 		buildWqlSink(wmiCriterion);
 	}
+
+	@Override
+	public void visit(final SqlCriterion sqlCriterion) {
+		// SQL
+		sink.listItem();
+		sink.text("The ");
+		sink.bold();
+		sink.text("SQL query");
+		sink.bold_();
+		sink.text(" below succeeds on the monitored database:");
+		sink.list();
+		sink.list();
+		sink.listItem();
+		sink.rawText(String.format("SQL Query: <code>%s</code>", SinkHelper.replaceWithHtmlCode(sqlCriterion.getQuery())));
+		sink.listItem_();
+
+		final String expectedResult = sqlCriterion.getExpectedResult();
+		if (expectedResult != null) {
+			sink.listItem();
+			sink.rawText(String.format("Expected Result: <code>%s</code>", SinkHelper.replaceWithHtmlCode(expectedResult)));
+			sink.listItem_();
+		}
+
+		// End the SQL criteria list
+		sink.list_();
+		sink.listItem_();
+	}
 }

src/main/java/org/sentrysoftware/maven/metricshub/connector/producer/model/criteria/ICriterionVisitor.java

@@ -104,4 +104,11 @@ public interface ICriterionVisitor {
 	 * @param wmiCriterion The WMI criterion to visit.
 	 */
 	void visit(WmiCriterion wmiCriterion);
+
+	/**
+	 * Visits the specified SQL criterion.
+	 *
+	 * @param sqlCriterion The SQL criterion to visit.
+	 */
+	void visit(SqlCriterion sqlCriterion);
 }

src/main/java/org/sentrysoftware/maven/metricshub/connector/producer/model/criteria/SqlCriterion.java

@@ -0,0 +1,58 @@
+package org.sentrysoftware.maven.metricshub.connector.producer.model.criteria;
+
+/*-
+ * ╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲
+ * MetricsHub Connector Maven Plugin
+ * ჻჻჻჻჻჻
+ * Copyright (C) 2023 Sentry Software
+ * ჻჻჻჻჻჻
+ * 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 static org.sentrysoftware.maven.metricshub.connector.producer.JsonNodeHelper.nonNullTextOrDefault;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import lombok.Builder;
+
+/**
+ * Represents a criterion for filtering based on a SQL query.
+ *
+ * @see AbstractCriterion
+ */
+public class SqlCriterion extends AbstractCriterion {
+
+	/**
+	 * Constructs SqlCriterion with the specified JSON criterion.
+	 *
+	 * @param criterion The JSON criterion for SQL check.
+	 */
+	@Builder
+	public SqlCriterion(final JsonNode criterion) {
+		super(criterion);
+	}
+
+	/**
+	 * Gets the query from the current SQL criterion, or {@code null} if not present.
+	 *
+	 * @return The query from the criterion, or {@code null} if not present.
+	 */
+	public String getQuery() {
+		return nonNullTextOrDefault(criterion.get("query"), null);
+	}
+
+	@Override
+	public void accept(ICriterionVisitor visitor) {
+		visitor.visit(this);
+	}
+}