[FSTORE-617] Fix java docstrings to build javadocs (#921)

logicalclocks · Feb 8, 2023 · 37bd63b · 37bd63b
1 parent f304f92
commit 37bd63b
Show file tree

Hide file tree

Showing 17 changed files with 428 additions and 301 deletions.
diff --git a/.gitignore b/.gitignore
@@ -130,3 +130,6 @@ docs/generated
 
 # Test artifacts
 keyFile.json
+
+# delombok dir
+delombok
diff --git a/java/pom.xml b/java/pom.xml
@@ -31,6 +31,9 @@
         <junit.version>5.9.1</junit.version>
         <surefire-plugin.version>2.22.0</surefire-plugin.version>
         <mockito.version>4.3.1</mockito.version>
+
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <delombok.output>${project.basedir}/delombok</delombok.output>
     </properties>
 
     <dependencies>
@@ -368,14 +371,52 @@
                     <systemPropertiesFile>src/test/resources/system.properties</systemPropertiesFile>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.projectlombok</groupId>
+                <artifactId>lombok-maven-plugin</artifactId>
+                <version>${lombok.version}.0</version>
+                <configuration>
+                    <sourceDirectory>${project.basedir}/src/main/java</sourceDirectory>
+                    <outputDirectory>${delombok.output}</outputDirectory>
+                    <addOutputDirectory>false</addOutputDirectory>
+                </configuration>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>delombok</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>3.1.1</version>
+                <configuration>
+                    <source>1.8</source>
+                    <target>1.8</target>
+                    <sourcepath>${delombok.output}</sourcepath>
+                </configuration>
+
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+
         </plugins>
         <testResources>
             <testResource>
                 <directory>src/test/resources</directory>
             </testResource>
         </testResources>
     </build>
-
     <repositories>
         <repository>
             <id>Hops</id>

diff --git a/java/src/main/java/com/logicalclocks/hsfs/Feature.java b/java/src/main/java/com/logicalclocks/hsfs/Feature.java
@@ -193,7 +193,8 @@ public Filter ge(Feature value) {
 
   /**
    * check if a value exists in a group of values.
-   * 
+   * @param collection collection of values to filter on SqlFilterCondition.IN
+   * @return Filter object
    * @deprecated
    * `in` method is deprecated. Use `isin` instead.
    */

diff --git a/java/src/main/java/com/logicalclocks/hsfs/FeatureGroup.java b/java/src/main/java/com/logicalclocks/hsfs/FeatureGroup.java
@@ -136,11 +136,11 @@ public Dataset<Row> read(boolean online, Map<String, String> readOptions) throws
   /**
    * Reads Feature group data at a specific point in time.
    *
-   * @param wallclockTime
-   * @return DataFrame.
-   * @throws FeatureStoreException
-   * @throws IOException
-   * @throws ParseException
+   * @param wallclockTime point in time
+   * @return Spark DataFrame containing feature data.
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws IOException IOException
+   * @throws ParseException ParseException
    */
   public Dataset<Row> read(String wallclockTime) throws FeatureStoreException, IOException, ParseException {
     return (Dataset<Row>) selectAll().asOf(wallclockTime).read(false, null);
@@ -149,12 +149,12 @@ public Dataset<Row> read(String wallclockTime) throws FeatureStoreException, IOE
   /**
    * Reads Feature group data at a specific point in time.
    *
-   * @param wallclockTime
-   * @param readOptions
-   * @return DataFrame.
-   * @throws FeatureStoreException
-   * @throws IOException
-   * @throws ParseException
+   * @param wallclockTime point in time
+   * @param readOptions Additional read options as key-value pairs, defaults to empty Map.
+   * @return Spark DataFrame containing feature data.
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws IOException IOException
+   * @throws ParseException ParseException
    */
   public Dataset<Row> read(String wallclockTime, Map<String, String> readOptions)
       throws FeatureStoreException, IOException, ParseException {
@@ -166,10 +166,10 @@ public Dataset<Row> read(String wallclockTime, Map<String, String> readOptions)
    *
    * @param wallclockStartTime start date.
    * @param wallclockEndTime   end date.
-   * @return DataFrame.
-   * @throws FeatureStoreException
-   * @throws IOException
-   * @throws ParseException
+   * @return Spark DataFrame containing feature data.
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws IOException IOException
+   * @throws ParseException ParseException
    *
    * @deprecated
    */
@@ -182,11 +182,12 @@ public Dataset<Row> readChanges(String wallclockStartTime, String wallclockEndTi
    * `readChanges` method is deprecated. Use `asOf(wallclockEndTime, wallclockStartTime).read(readOptions)` instead.
    *
    * @param wallclockStartTime start date.
-   * @param wallclockEndTime   end date.
-   * @return DataFrame.
-   * @throws FeatureStoreException
-   * @throws IOException
-   * @throws ParseException
+   * @param wallclockEndTime end date.
+   * @param readOptions Additional write options as key-value pairs, defaults to empty Map.
+   * @return Spark DataFrame containing feature data.
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws IOException IOException
+   * @throws ParseException ParseException
    *
    * @deprecated
    */
@@ -204,8 +205,8 @@ public Dataset<Row> readChanges(String wallclockStartTime, String wallclockEndTi
    * @param wallclockTime Datetime string. The String should be formatted in one of the
    *     following formats `%Y%m%d`, `%Y%m%d%H`, `%Y%m%d%H%M`, or `%Y%m%d%H%M%S`.
    * @return Query. The query object with the applied time travel condition
-   * @throws FeatureStoreException
-   * @throws ParseException
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws ParseException ParseException
    */
   public Query asOf(String wallclockTime) throws FeatureStoreException, ParseException {
     return selectAll().asOf(wallclockTime);
@@ -222,8 +223,8 @@ public Query asOf(String wallclockTime) throws FeatureStoreException, ParseExcep
    * @param excludeUntil Datetime string. The String should be formatted in one of the
     *     following formats `%Y%m%d`, `%Y%m%d%H`, `%Y%m%d%H%M`, or `%Y%m%d%H%M%S`.
    * @return Query. The query object with the applied time travel condition
-   * @throws FeatureStoreException
-   * @throws ParseException
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws ParseException ParseException
    */
   public Query asOf(String wallclockTime, String excludeUntil) throws FeatureStoreException, ParseException {
     return selectAll().asOf(wallclockTime, excludeUntil);
@@ -295,8 +296,9 @@ public void insert(Dataset<Row> featureData, boolean overwrite, Map<String, Stri
    *
    * @param featureData dataframe to be committed.
    * @param operation   commit operation type, INSERT or UPSERT.
-   * @throws FeatureStoreException
-   * @throws IOException
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws IOException IOException
+   * @throws ParseException ParseException
    */
   public void insert(Dataset<Row> featureData, HudiOperationType operation)
       throws FeatureStoreException, IOException, ParseException {
@@ -330,6 +332,13 @@ public void insert(Dataset<Row> featureData, Storage storage, boolean overwrite,
   /**
    * insert streaming dataframe in the Feature group.
    *
+   * @param featureData Spark dataframe containing feature data
+   * @return StreamingQuery
+   * @throws StreamingQueryException StreamingQueryException
+   * @throws IOException IOException
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws TimeoutException TimeoutException
+   * @throws ParseException ParseException
    * @deprecated
    * insertStream method is deprecated FeatureGroups. Full capability insertStream is available for StreamFeatureGroups.
    */
@@ -342,6 +351,14 @@ public StreamingQuery insertStream(Dataset<Row> featureData)
   /**
    * insert streaming dataframe in the Feature group.
    *
+   * @param featureData Spark dataframe containing feature data
+   * @param queryName name of spark StreamingQuery
+   * @return StreamingQuery
+   * @throws StreamingQueryException StreamingQueryException
+   * @throws IOException IOException
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws TimeoutException TimeoutException
+   * @throws ParseException ParseException
    * @deprecated
    * insertStream method is deprecated FeatureGroups. Full capability insertStream is available for StreamFeatureGroups.
    */
@@ -354,6 +371,15 @@ public StreamingQuery insertStream(Dataset<Row> featureData, String queryName)
   /**
    * insert streaming dataframe in the Feature group.
    *
+   * @param featureData Spark dataframe containing feature data
+   * @param queryName name of spark StreamingQuery
+   * @param outputMode outputMode
+   * @return StreamingQuery
+   * @throws StreamingQueryException StreamingQueryException
+   * @throws IOException IOException
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws TimeoutException TimeoutException
+   * @throws ParseException ParseException
    * @deprecated
    * insertStream method is deprecated FeatureGroups. Full capability insertStream is available for StreamFeatureGroups.
    */
@@ -366,6 +392,17 @@ public StreamingQuery insertStream(Dataset<Row> featureData, String queryName, S
   /**
    * insert streaming dataframe in the Feature group.
    *
+   * @param featureData Spark dataframe containing feature data
+   * @param queryName name of spark StreamingQuery
+   * @param outputMode outputMode
+   * @param awaitTermination whether or not to wait for query Termination
+   * @param timeout timeout
+   * @return StreamingQuery
+   * @throws StreamingQueryException StreamingQueryException
+   * @throws IOException IOException
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws TimeoutException TimeoutException
+   * @throws ParseException ParseException
    * @deprecated
    * insertStream method is deprecated FeatureGroups. Full capability insertStream is available for StreamFeatureGroups.
    */
@@ -379,6 +416,17 @@ public StreamingQuery insertStream(Dataset<Row> featureData, String queryName, S
   /**
    * insert streaming dataframe in the Feature group.
    *
+   * @param featureData Spark dataframe containing feature data
+   * @param queryName name of spark StreamingQuery
+   * @param outputMode outputMode
+   * @param awaitTermination whether or not to wait for query Termination
+   * @param checkpointLocation path to checkpoint location directory
+   * @return StreamingQuery
+   * @throws StreamingQueryException StreamingQueryException
+   * @throws IOException IOException
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws TimeoutException TimeoutException
+   * @throws ParseException ParseException
    * @deprecated
    * insertStream method is deprecated FeatureGroups. Full capability insertStream is available for StreamFeatureGroups.
    */
@@ -392,6 +440,19 @@ public StreamingQuery insertStream(Dataset<Row> featureData, String queryName, S
   /**
    * insert streaming dataframe in the Feature group.
    *
+   * @param featureData Spark dataframe containing feature data
+   * @param queryName name of spark StreamingQuery
+   * @param outputMode outputMode
+   * @param awaitTermination whether or not to wait for query Termination
+   * @param timeout timeout
+   * @param checkpointLocation path to checkpoint location directory
+   * @param writeOptions Additional write options as key-value pairs, defaults to empty Map.
+   * @return StreamingQuery
+   * @throws StreamingQueryException StreamingQueryException
+   * @throws IOException IOException
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws TimeoutException TimeoutException
+   * @throws ParseException ParseException
    * @deprecated
    * insertStream method is deprecated FeatureGroups. Full capability insertStream is available for StreamFeatureGroups.
    */
@@ -424,8 +485,10 @@ public void commitDeleteRecord(Dataset<Row> featureData, Map<String, String> wri
   /**
    * Return commit details.
    *
-   * @throws FeatureStoreException
-   * @throws IOException
+   * @return commit details.
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws IOException IOException
+   * @throws ParseException ParseException
    */
   public Map<Long, Map<String, String>> commitDetails() throws IOException, FeatureStoreException, ParseException {
     return utils.commitDetails(this, null);
@@ -435,8 +498,10 @@ public Map<Long, Map<String, String>> commitDetails() throws IOException, Featur
    * Return commit details.
    *
    * @param limit number of commits to return.
-   * @throws FeatureStoreException
-   * @throws IOException
+   * @return commit details.
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws IOException IOException
+   * @throws ParseException ParseException
    */
   public Map<Long, Map<String, String>> commitDetails(Integer limit)
       throws IOException, FeatureStoreException, ParseException {
@@ -447,8 +512,10 @@ public Map<Long, Map<String, String>> commitDetails(Integer limit)
    * Return commit details.
    *
    * @param wallclockTime point in time.
-   * @throws FeatureStoreException
-   * @throws IOException
+   * @return commit details.
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws IOException IOException
+   * @throws ParseException ParseException
    */
   public Map<Long, Map<String, String>> commitDetails(String wallclockTime)
       throws IOException, FeatureStoreException, ParseException {
@@ -460,8 +527,10 @@ public Map<Long, Map<String, String>> commitDetails(String wallclockTime)
    *
    * @param wallclockTime point in time.
    * @param limit number of commits to return.
-   * @throws FeatureStoreException
-   * @throws IOException
+   * @return commit details.
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws IOException IOException
+   * @throws ParseException ParseException
    */
   public Map<Long, Map<String, String>> commitDetails(String wallclockTime, Integer limit)
       throws IOException, FeatureStoreException, ParseException {
@@ -498,8 +567,9 @@ public Schema getDeserializedAvroSchema() throws FeatureStoreException, IOExcept
    *
    * @param wallclockTime number of commits to return.
    * @return statistics object of computed statistics
-   * @throws FeatureStoreException
-   * @throws IOException
+   * @throws FeatureStoreException FeatureStoreException
+   * @throws IOException IOException
+   * @throws ParseException ParseException
    */
   public Statistics computeStatistics(String wallclockTime) throws FeatureStoreException, IOException, ParseException {
     if (statisticsConfig.getEnabled()) {