You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by yc...@apache.org on 2025/02/02 05:36:31 UTC
(cassandra-sidecar) 02/06: Fixed JavaDocs and Removed TemporaryFile
This is an automated email from the ASF dual-hosted git repository.
ycai pushed a commit to branch r/apache/pr178
in repository https://gitbox.apache.org/repos/asf/cassandra-sidecar.git
commit 9f6428f222569de6a6007199ae2e3590b9cf5f77
Author: Yuriy Semchyshyn <yu...@semchyshyn.com>
AuthorDate: Fri Jan 31 14:22:17 2025 -0600
Fixed JavaDocs and Removed TemporaryFile
---
.../sidecar/datahub/IdentifiersProvider.java | 51 +++++++++---
.../cassandra/sidecar/datahub/JsonEmitter.java | 2 +
.../sidecar/datahub/KeyspaceToAspectConverter.java | 2 +-
.../sidecar/datahub/MetadataToAspectConverter.java | 2 +-
.../cassandra/sidecar/datahub/SchemaReporter.java | 35 +++++---
.../sidecar/datahub/SchemaReportingTask.java | 8 +-
.../sidecar/datahub/TableToAspectConverter.java | 2 +-
.../datahub/TableToSchemaMetadataConverter.java | 18 ++++-
.../cassandra/sidecar/datahub/TemporaryFile.java | 92 ----------------------
9 files changed, 88 insertions(+), 124 deletions(-)
diff --git a/server/src/main/java/org/apache/cassandra/sidecar/datahub/IdentifiersProvider.java b/server/src/main/java/org/apache/cassandra/sidecar/datahub/IdentifiersProvider.java
index d4da2c98..b219030e 100644
--- a/server/src/main/java/org/apache/cassandra/sidecar/datahub/IdentifiersProvider.java
+++ b/server/src/main/java/org/apache/cassandra/sidecar/datahub/IdentifiersProvider.java
@@ -44,7 +44,9 @@ public abstract class IdentifiersProvider
protected static final String PROD = "PROD"; // DataHub requires this to be {@code PROD} regardless
/**
- * A public getter method that returns the name of a Cassandra Organization
+ * A public getter method that returns the name of Cassandra Organization
+ *
+ * @return name of Cassandra organization
*/
@NotNull
public String organization()
@@ -53,7 +55,9 @@ public abstract class IdentifiersProvider
}
/**
- * A public getter method that returns the name of a Cassandra Platform
+ * A public getter method that returns the name of Cassandra Platform
+ *
+ * @return name of Cassandra platform
*/
@NotNull
public String platform()
@@ -62,7 +66,9 @@ public abstract class IdentifiersProvider
}
/**
- * A public getter method that returns the name of a Cassandra Environment
+ * A public getter method that returns the name of Cassandra Environment
+ *
+ * @return name of Cassandra environment
*/
@NotNull
public String environment()
@@ -71,7 +77,9 @@ public abstract class IdentifiersProvider
}
/**
- * A public getter method that returns the name of a Cassandra Application
+ * A public getter method that returns the name of Cassandra Application
+ *
+ * @return name of Cassandra application
*/
@NotNull
public String application()
@@ -80,13 +88,17 @@ public abstract class IdentifiersProvider
}
/**
- * A public getter method that returns the name of a Cassandra Cluster
+ * A public getter method that returns the name of Cassandra Cluster
+ *
+ * @return name of Cassandra cluster
*/
@NotNull
public abstract String cluster();
/**
- * A public getter method that returns the identifier of a Cassandra Cluster
+ * A public getter method that returns the identifier of Cassandra Cluster
+ *
+ * @return identifier of Cassandra cluster
*/
@NotNull
public UUID identifier()
@@ -97,7 +109,9 @@ public abstract class IdentifiersProvider
};
/**
- * A public helper method that prepares the URN of a Data Platform
+ * A public helper method that prepares the URN of Data Platform
+ *
+ * @return URN of data platform
*/
@NotNull
public String urnDataPlatform()
@@ -110,7 +124,9 @@ public abstract class IdentifiersProvider
}
/**
- * A public helper method that prepares the URN of a Data Platform Instance
+ * A public helper method that prepares the URN of Data Platform Instance
+ *
+ * @return URN of data platform instance
*/
@NotNull
public String urnDataPlatformInstance()
@@ -124,7 +140,10 @@ public abstract class IdentifiersProvider
}
/**
- * A public helper method that prepares the URN of a Container
+ * A public helper method that prepares the URN of Container
+ *
+ * @param keyspace metadata of keyspace
+ * @return URN of container
*/
@NotNull
public String urnContainer(@NotNull KeyspaceMetadata keyspace)
@@ -138,7 +157,10 @@ public abstract class IdentifiersProvider
}
/**
- * A public helper method that prepares the URN of a Dataset
+ * A public helper method that prepares the URN of Dataset
+ *
+ * @param table metadata of table
+ * @return URN of dataset
*/
@NotNull
public String urnDataset(@NotNull TableMetadata table)
@@ -156,6 +178,8 @@ public abstract class IdentifiersProvider
/**
* A public method that returns an {@link int} hash code of this object
+ *
+ * @return hash code of this object
*/
@Override
public int hashCode()
@@ -172,6 +196,9 @@ public abstract class IdentifiersProvider
/**
* A public method that compares this {@link IdentifiersProvider} object to another one
+ *
+ * @param other another object for comparison
+ * @return whether this object is equal to another object
*/
@Override
public boolean equals(@Nullable Object other)
@@ -196,7 +223,9 @@ public abstract class IdentifiersProvider
/**
* A public method that returns a {@link String} representation of this object
- */
+ *
+ * @return a {@link String} representation of this object
+ **/
@Override
@NotNull
public String toString()
diff --git a/server/src/main/java/org/apache/cassandra/sidecar/datahub/JsonEmitter.java b/server/src/main/java/org/apache/cassandra/sidecar/datahub/JsonEmitter.java
index 31288c03..e11ab56c 100644
--- a/server/src/main/java/org/apache/cassandra/sidecar/datahub/JsonEmitter.java
+++ b/server/src/main/java/org/apache/cassandra/sidecar/datahub/JsonEmitter.java
@@ -134,6 +134,8 @@ public class JsonEmitter implements Emitter, AutoCloseable
* <p>
* Should only be called after this {@link Emitter} has been closed,
* otherwise the result is not going to be a correctly formatted JSON.
+ *
+ * @return the current content of the buffer
*/
public synchronized String content()
{
diff --git a/server/src/main/java/org/apache/cassandra/sidecar/datahub/KeyspaceToAspectConverter.java b/server/src/main/java/org/apache/cassandra/sidecar/datahub/KeyspaceToAspectConverter.java
index 3dcb0ffd..14fe7cdf 100644
--- a/server/src/main/java/org/apache/cassandra/sidecar/datahub/KeyspaceToAspectConverter.java
+++ b/server/src/main/java/org/apache/cassandra/sidecar/datahub/KeyspaceToAspectConverter.java
@@ -34,7 +34,7 @@ public abstract class KeyspaceToAspectConverter<T extends RecordTemplate> extend
}
/**
- * A helper method used in order to create a new instance of {@link MetadataChangeProposalWrapper<>} for a keyspace;
+ * A helper method used in order to create a new instance of {@link MetadataChangeProposalWrapper} for a keyspace;
* the instance will have its {@code urn} and {@code aspect} fields initialized with the provided values
*
* @param urn the URN to initialize the wrapper with
diff --git a/server/src/main/java/org/apache/cassandra/sidecar/datahub/MetadataToAspectConverter.java b/server/src/main/java/org/apache/cassandra/sidecar/datahub/MetadataToAspectConverter.java
index 3ad3e225..5db190b5 100644
--- a/server/src/main/java/org/apache/cassandra/sidecar/datahub/MetadataToAspectConverter.java
+++ b/server/src/main/java/org/apache/cassandra/sidecar/datahub/MetadataToAspectConverter.java
@@ -40,7 +40,7 @@ abstract class MetadataToAspectConverter<T extends RecordTemplate>
}
/**
- * A helper method that implementing classes should use in order to create a new instance of {@link MetadataChangeProposalWrapper<>};
+ * A helper method that implementing classes should use in order to create a new instance of {@link MetadataChangeProposalWrapper};
* the instance will have its {@code type}, {@code urn}, and {@code aspect} fields initialized with the provided values
*
* @param type the type to initialize the wrapper with
diff --git a/server/src/main/java/org/apache/cassandra/sidecar/datahub/SchemaReporter.java b/server/src/main/java/org/apache/cassandra/sidecar/datahub/SchemaReporter.java
index 2983d1c6..1fc6be29 100644
--- a/server/src/main/java/org/apache/cassandra/sidecar/datahub/SchemaReporter.java
+++ b/server/src/main/java/org/apache/cassandra/sidecar/datahub/SchemaReporter.java
@@ -40,8 +40,8 @@ import java.util.stream.Stream;
* Utility class for converting and reporting the provided Cassandra metadata objects
* in a DataHub-compliant format describing the current schema of the cluster.
* <p>
- * Note that the extensive usage of {@link Stream<>} types here enables late creation
- * and early destruction of DataHub aspect objects while the schema is being converted
+ * Note that the extensive usage of {@link Stream} types here enables late creation and
+ * early destruction of DataHub aspect objects while the schema is being converted
* (since all of them can potentially take up to a gigabyte on largest clusters).
*/
@Singleton
@@ -92,9 +92,9 @@ public class SchemaReporter
* A protected constructor that can be used to instantiate {@link SchemaReporter} with custom configuration
*
* @param identifiersProvider an instance of {@link IdentifiersProvider} to use
- * @param clusterConverters a {@link List<>} of {@link ClusterToAspectConverter<>} instances to use
- * @param keyspaceConverters a {@link List<>} of {@link KeyspaceToAspectConverter<>} instances to use
- * @param tableConverters a {@link List<>} of {@link TableToAspectConverter<>} instances to use
+ * @param clusterConverters a {@link List} of {@link ClusterToAspectConverter} instances to use
+ * @param keyspaceConverters a {@link List} of {@link KeyspaceToAspectConverter} instances to use
+ * @param tableConverters a {@link List} of {@link TableToAspectConverter} instances to use
* @param emitterFactory an instance of {@link EmitterFactory} to use
*/
protected SchemaReporter(@NotNull IdentifiersProvider identifiersProvider,
@@ -129,7 +129,11 @@ public class SchemaReporter
}
/**
- * Protected method for preparing cluster schema using DataHub client
+ * Protected method that converts Cassandra cluster metadata
+ * into a non-empty {@link Stream} of DataHub aspects
+ *
+ * @param metadata Cassandra cluster metadata
+ * @return non-empty {@link Stream} of DataHub aspects
*/
@NotNull
@SuppressWarnings("UnstableApiUsage")
@@ -144,7 +148,11 @@ public class SchemaReporter
}
/**
- * Protected method for preparing keyspace schema using DataHub client
+ * Protected method that converts Cassandra keyspace metadata
+ * into a non-empty {@link Stream} of DataHub aspects
+ *
+ * @param keyspace Cassandra keyspace metadata
+ * @return non-empty {@link Stream} of DataHub aspects
*/
@NotNull
@SuppressWarnings("UnstableApiUsage")
@@ -158,7 +166,11 @@ public class SchemaReporter
}
/**
- * Protected method for preparing table schema using DataHub client
+ * Protected method that converts Cassandra table metadata
+ * into a non-empty {@link Stream} of DataHub aspects
+ *
+ * @param table Cassandra table metadata
+ * @return non-empty {@link Stream} of DataHub aspects
*/
@NotNull
protected Stream<MetadataChangeProposalWrapper<? extends RecordTemplate>> stream(@NotNull TableMetadata table)
@@ -168,7 +180,12 @@ public class SchemaReporter
}
/**
- * Protected method for filtering out virtual keyspaces, Cassandra system keyspaces, and Sidecar system keyspace
+ * Protected method for filtering out virtual keyspaces,
+ * Cassandra system keyspaces, and Sidecar internal keyspaces
+ *
+ * @param keyspace Cassandra keyspace metadata
+ * @return {@code true} if the keyspace is neither virtual nor system,
+ * {@code false} otherwise
*/
protected boolean neitherVirtualNorSystem(@NotNull KeyspaceMetadata keyspace)
{
diff --git a/server/src/main/java/org/apache/cassandra/sidecar/datahub/SchemaReportingTask.java b/server/src/main/java/org/apache/cassandra/sidecar/datahub/SchemaReportingTask.java
index b1a18e37..e8abbc5d 100644
--- a/server/src/main/java/org/apache/cassandra/sidecar/datahub/SchemaReportingTask.java
+++ b/server/src/main/java/org/apache/cassandra/sidecar/datahub/SchemaReportingTask.java
@@ -94,14 +94,8 @@ public class SchemaReportingTask implements PeriodicTask, ExecuteOnClusterLeaseh
}
catch (Throwable throwable)
{
- LOGGER.error("Failed to convert and report the current schema");
+ LOGGER.error("Failed to convert and report the current schema", throwable);
promise.fail(throwable);
}
}
-
- @Override
- public Void result()
- {
- return null; // No result can be returned from a {@link PeriodicTask}
- }
}
diff --git a/server/src/main/java/org/apache/cassandra/sidecar/datahub/TableToAspectConverter.java b/server/src/main/java/org/apache/cassandra/sidecar/datahub/TableToAspectConverter.java
index 44d633fb..16887091 100644
--- a/server/src/main/java/org/apache/cassandra/sidecar/datahub/TableToAspectConverter.java
+++ b/server/src/main/java/org/apache/cassandra/sidecar/datahub/TableToAspectConverter.java
@@ -34,7 +34,7 @@ public abstract class TableToAspectConverter<T extends RecordTemplate> extends M
}
/**
- * A helper method used in order to create a new instance of {@link MetadataChangeProposalWrapper<>} for a table;
+ * A helper method used in order to create a new instance of {@link MetadataChangeProposalWrapper} for a table;
* the instance will have its {@code urn} and {@code aspect} fields initialized with the provided values
*
* @param urn the URN to initialize the wrapper with
diff --git a/server/src/main/java/org/apache/cassandra/sidecar/datahub/TableToSchemaMetadataConverter.java b/server/src/main/java/org/apache/cassandra/sidecar/datahub/TableToSchemaMetadataConverter.java
index 2c6442f5..4be719e8 100644
--- a/server/src/main/java/org/apache/cassandra/sidecar/datahub/TableToSchemaMetadataConverter.java
+++ b/server/src/main/java/org/apache/cassandra/sidecar/datahub/TableToSchemaMetadataConverter.java
@@ -133,7 +133,11 @@ public class TableToSchemaMetadataConverter extends TableToAspectConverter<Schem
}
/**
- * Protected method for converting single Cassandra column metadata into a collection of at least one DataHub schema field definition
+ * Protected method for converting metadata of a single Cassandra column
+ * into a non-empty {@link Stream} of DataHub schema field definitions
+ *
+ * @param column metadata of a single Cassandra column
+ * @return non-empty {@link Stream} of DataHub schema field definitions
*/
@NotNull
protected Stream<SchemaField> convertColumn(@NotNull ColumnMetadata column)
@@ -147,7 +151,14 @@ public class TableToSchemaMetadataConverter extends TableToAspectConverter<Schem
}
/**
- * Protected method for converting Cassandra's single data type into a non-empty collection of DataHub's field definitions
+ * Protected method for converting a single Cassandra data type
+ * into a non-empty {@link Stream} of DataHub schema field definitions
+ *
+ * @param name name of the field
+ * @param type type of the field
+ * @param partition whether the field is a part of partition key
+ * @param key whether the field is a part of any key
+ * @return non-empty {@link Stream} of DataHub schema field definitions
*/
@NotNull
protected Stream<SchemaField> convertType(@NotNull String name,
@@ -184,6 +195,9 @@ public class TableToSchemaMetadataConverter extends TableToAspectConverter<Schem
/**
* Protected method for converting data types used by Cassandra into the ones recognized by DataHub,
* uses {@code NullType} to indicate an unknown or unsupported data type
+ *
+ * @param cassandraType Cassandra data type
+ * @return DataHub data type, or {@code NullType} if unknown/unsupported
*/
@NotNull
protected SchemaFieldDataType convertType(@NotNull DataType.Name cassandraType)
diff --git a/server/src/main/java/org/apache/cassandra/sidecar/datahub/TemporaryFile.java b/server/src/main/java/org/apache/cassandra/sidecar/datahub/TemporaryFile.java
deleted file mode 100644
index 9abd7197..00000000
--- a/server/src/main/java/org/apache/cassandra/sidecar/datahub/TemporaryFile.java
+++ /dev/null
@@ -1,92 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you 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 org.apache.cassandra.sidecar.datahub;
-
-import datahub.client.file.FileEmitter;
-import org.jetbrains.annotations.NotNull;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
-import java.io.IOException;
-import java.nio.file.Files;
-import java.nio.file.Path;
-
-/**
- * Temporary file for formatted Cassandra schema that can be used with DataHub's
- * {@link FileEmitter} to produce schema files in the local temporary directory
- */
-@SuppressWarnings("unused")
-final class TemporaryFile implements AutoCloseable
-{
- private static final Logger LOGGER = LoggerFactory.getLogger(TemporaryFile.class);
-
- private static final String PREFIX = "cassandra-schema-";
- private static final String EXTENSION = ".json";
-
- @NotNull
- public final Path path;
-
- /**
- * Creates a temporary file for formatted Cassandra schema
- */
- public TemporaryFile() throws IOException
- {
- try
- {
- path = Files.createTempFile(PREFIX, EXTENSION);
- }
- catch (Exception exception)
- {
- throw new IOException("Cannot create a temporary file for schema extraction", exception);
- }
- }
-
- /**
- * Reads formatted Cassandra schema from the temporary file
- */
- @NotNull
- public String content() throws IOException
- {
- try
- {
- return new String(Files.readAllBytes(path));
- }
- catch (Exception exception)
- {
- throw new IOException("Cannot read extracted schema from the temporary file", exception);
- }
- }
-
- /**
- * Deletes the temporary file with formatted Cassandra schema
- */
- @Override
- public void close()
- {
- try
- {
- Files.delete(path);
- }
- catch (Exception exception)
- {
- LOGGER.warn("Cannot delete the temporary file with extracted schema", exception);
- }
- }
-}
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cassandra.apache.org
For additional commands, e-mail: commits-help@cassandra.apache.org