AVRO-3788: escape 'code extracts' in Javadoc

apache · Jul 31, 2023 · 23a9cc0 · 23a9cc0
1 parent ab6e1b8
commit 23a9cc0
Show file tree

Hide file tree

Showing 4 changed files with 86 additions and 11 deletions.
diff --git a/lang/java/compiler/src/main/java/org/apache/avro/compiler/specific/SpecificCompiler.java b/lang/java/compiler/src/main/java/org/apache/avro/compiler/specific/SpecificCompiler.java
@@ -1061,7 +1061,7 @@ public static String javaEscape(String o) {
    * Utility for template use. Escapes comment end with HTML entities.
    */
   public static String escapeForJavadoc(String s) {
-    return s.replace("*/", "*&#47;");
+    return s.replace("*/", "*&#47;").replace("<", "&lt;").replace(">", "&gt;");
   }
 
   /**

diff --git a/...iler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/record.vm b/...iler/src/main/velocity/org/apache/avro/compiler/specific/templates/java/classic/record.vm
@@ -228,10 +228,10 @@ public class ${this.mangleTypeIdentifier($schema.getName())} extends ${this.getS
 #foreach ($field in $schema.getFields())
 #if (${this.gettersReturnOptional} && (!${this.optionalGettersForNullableFieldsOnly} || ${field.schema().isNullable()}))
   /**
-   * Gets the value of the '${this.mangle($field.name(), $schema.isError())}' field as an Optional&lt;${this.javaType($field.schema())}&gt;.
+   * Gets the value of the '${this.mangle($field.name(), $schema.isError())}' field as an Optional&lt;${this.escapeForJavadoc(${this.javaType($field.schema())})}&gt;.
 #if ($field.doc())   * $field.doc()
 #end
-   * @return The value wrapped in an Optional&lt;${this.javaType($field.schema())}&gt;.
+   * @return The value wrapped in an Optional&lt;${this.escapeForJavadoc(${this.javaType($field.schema())})}&gt;.
    */
   public Optional<${this.javaType($field.schema())}> ${this.generateGetMethod($schema, $field)}() {
     return Optional.<${this.javaType($field.schema())}>ofNullable(${this.mangle($field.name(), $schema.isError())});
@@ -250,10 +250,10 @@ public class ${this.mangleTypeIdentifier($schema.getName())} extends ${this.getS
 
 #if (${this.createOptionalGetters})
   /**
-   * Gets the value of the '${this.mangle($field.name(), $schema.isError())}' field as an Optional&lt;${this.javaType($field.schema())}&gt;.
+   * Gets the value of the '${this.mangle($field.name(), $schema.isError())}' field as an Optional&lt;${this.escapeForJavadoc(${this.javaType($field.schema())})}&gt;.
 #if ($field.doc())   * $field.doc()
 #end
-   * @return The value wrapped in an Optional&lt;${this.javaType($field.schema())}&gt;.
+   * @return The value wrapped in an Optional&lt;${this.escapeForJavadoc(${this.javaType($field.schema())})}&gt;.
    */
   public Optional<${this.javaType($field.schema())}> ${this.generateGetOptionalMethod($schema, $field)}() {
     return Optional.<${this.javaType($field.schema())}>ofNullable(${this.mangle($field.name(), $schema.isError())});
@@ -406,10 +406,10 @@ public class ${this.mangleTypeIdentifier($schema.getName())} extends ${this.getS
 
 #if (${this.createOptionalGetters})
     /**
-      * Gets the value of the '${this.mangle($field.name(), $schema.isError())}' field as an Optional&lt;${this.javaType($field.schema())}&gt;.
+      * Gets the value of the '${this.mangle($field.name(), $schema.isError())}' field as an Optional&lt;${this.escapeForJavadoc(${this.javaType($field.schema())})}&gt;.
 #if ($field.doc())      * $field.doc()
 #end
-      * @return The value wrapped in an Optional&lt;${this.javaType($field.schema())}&gt;.
+      * @return The value wrapped in an Optional&lt;${this.escapeForJavadoc(${this.javaType($field.schema())})}&gt;.
       */
     public Optional<${this.javaType($field.schema())}> ${this.generateGetOptionalMethod($schema, $field)}() {
       return Optional.<${this.javaType($field.schema())}>ofNullable(${this.mangle($field.name(), $schema.isError())});

diff --git a/lang/java/tools/src/test/compiler/input/optionalgettersnullablefieldstest.avsc b/lang/java/tools/src/test/compiler/input/optionalgettersnullablefieldstest.avsc
@@ -3,6 +3,7 @@
     {"name": "name", "type": "string"},
     {"name": "nullable_name",  "type": ["string", "null"]},
     {"name": "favorite_number",  "type": ["int"]},
-    {"name": "nullable_favorite_number", "type": ["int", "null"]}
+    {"name": "nullable_favorite_number", "type": ["int", "null"]},
+    {"name": "nullable_array", "type": [{ "type": "array",  "items": "string" }, "null"]}
   ]
 }
diff --git a/lang/java/tools/src/test/compiler/output/OptionalGettersNullableFieldsTest.java b/lang/java/tools/src/test/compiler/output/OptionalGettersNullableFieldsTest.java
@@ -15,8 +15,10 @@
 /** Test that optional getters are created only for nullable fields */
 @org.apache.avro.specific.AvroGenerated
 public class OptionalGettersNullableFieldsTest extends org.apache.avro.specific.SpecificRecordBase implements org.apache.avro.specific.SpecificRecord {
-  private static final long serialVersionUID = 7830366875847294825L;
-  public static final org.apache.avro.Schema SCHEMA$ = new org.apache.avro.Schema.Parser().parse("{\"type\":\"record\",\"name\":\"OptionalGettersNullableFieldsTest\",\"namespace\":\"avro.examples.baseball\",\"doc\":\"Test that optional getters are created only for nullable fields\",\"fields\":[{\"name\":\"name\",\"type\":\"string\"},{\"name\":\"nullable_name\",\"type\":[\"string\",\"null\"]},{\"name\":\"favorite_number\",\"type\":[\"int\"]},{\"name\":\"nullable_favorite_number\",\"type\":[\"int\",\"null\"]}]}");
+  private static final long serialVersionUID = -6919829133416680993L;
+
+
+  public static final org.apache.avro.Schema SCHEMA$ = new org.apache.avro.Schema.Parser().parse("{\"type\":\"record\",\"name\":\"OptionalGettersNullableFieldsTest\",\"namespace\":\"avro.examples.baseball\",\"doc\":\"Test that optional getters are created only for nullable fields\",\"fields\":[{\"name\":\"name\",\"type\":\"string\"},{\"name\":\"nullable_name\",\"type\":[\"string\",\"null\"]},{\"name\":\"favorite_number\",\"type\":[\"int\"]},{\"name\":\"nullable_favorite_number\",\"type\":[\"int\",\"null\"]},{\"name\":\"nullable_array\",\"type\":[{\"type\":\"array\",\"items\":\"string\"},\"null\"]}]}");
   public static org.apache.avro.Schema getClassSchema() { return SCHEMA$; }
 
   private static final SpecificData MODEL$ = new SpecificData();
@@ -76,6 +78,7 @@ public static OptionalGettersNullableFieldsTest fromByteBuffer(
   private java.lang.CharSequence nullable_name;
   private java.lang.Object favorite_number;
   private java.lang.Integer nullable_favorite_number;
+  private java.util.List<java.lang.CharSequence> nullable_array;
 
   /**
    * Default constructor.  Note that this does not initialize fields
@@ -90,12 +93,14 @@ public OptionalGettersNullableFieldsTest() {}
    * @param nullable_name The new value for nullable_name
    * @param favorite_number The new value for favorite_number
    * @param nullable_favorite_number The new value for nullable_favorite_number
+   * @param nullable_array The new value for nullable_array
    */
-  public OptionalGettersNullableFieldsTest(java.lang.CharSequence name, java.lang.CharSequence nullable_name, java.lang.Object favorite_number, java.lang.Integer nullable_favorite_number) {
+  public OptionalGettersNullableFieldsTest(java.lang.CharSequence name, java.lang.CharSequence nullable_name, java.lang.Object favorite_number, java.lang.Integer nullable_favorite_number, java.util.List<java.lang.CharSequence> nullable_array) {
     this.name = name;
     this.nullable_name = nullable_name;
     this.favorite_number = favorite_number;
     this.nullable_favorite_number = nullable_favorite_number;
+    this.nullable_array = nullable_array;
   }
 
   @Override
@@ -112,6 +117,7 @@ public java.lang.Object get(int field$) {
     case 1: return nullable_name;
     case 2: return favorite_number;
     case 3: return nullable_favorite_number;
+    case 4: return nullable_array;
     default: throw new IndexOutOfBoundsException("Invalid index: " + field$);
     }
   }
@@ -125,6 +131,7 @@ public void put(int field$, java.lang.Object value$) {
     case 1: nullable_name = (java.lang.CharSequence)value$; break;
     case 2: favorite_number = value$; break;
     case 3: nullable_favorite_number = (java.lang.Integer)value$; break;
+    case 4: nullable_array = (java.util.List<java.lang.CharSequence>)value$; break;
     default: throw new IndexOutOfBoundsException("Invalid index: " + field$);
     }
   }
@@ -197,6 +204,23 @@ public void setNullableFavoriteNumber(java.lang.Integer value) {
     this.nullable_favorite_number = value;
   }
 
+  /**
+   * Gets the value of the 'nullable_array' field as an Optional&lt;java.util.List&lt;java.lang.CharSequence&gt;&gt;.
+   * @return The value wrapped in an Optional&lt;java.util.List&lt;java.lang.CharSequence&gt;&gt;.
+   */
+  public Optional<java.util.List<java.lang.CharSequence>> getNullableArray() {
+    return Optional.<java.util.List<java.lang.CharSequence>>ofNullable(nullable_array);
+  }
+
+
+  /**
+   * Sets the value of the 'nullable_array' field.
+   * @param value the value to set.
+   */
+  public void setNullableArray(java.util.List<java.lang.CharSequence> value) {
+    this.nullable_array = value;
+  }
+
   /**
    * Creates a new OptionalGettersNullableFieldsTest RecordBuilder.
    * @return A new OptionalGettersNullableFieldsTest RecordBuilder
@@ -242,6 +266,7 @@ public static class Builder extends org.apache.avro.specific.SpecificRecordBuild
     private java.lang.CharSequence nullable_name;
     private java.lang.Object favorite_number;
     private java.lang.Integer nullable_favorite_number;
+    private java.util.List<java.lang.CharSequence> nullable_array;
 
     /** Creates a new Builder */
     private Builder() {
@@ -270,6 +295,10 @@ private Builder(avro.examples.baseball.OptionalGettersNullableFieldsTest.Builder
         this.nullable_favorite_number = data().deepCopy(fields()[3].schema(), other.nullable_favorite_number);
         fieldSetFlags()[3] = other.fieldSetFlags()[3];
       }
+      if (isValidValue(fields()[4], other.nullable_array)) {
+        this.nullable_array = data().deepCopy(fields()[4].schema(), other.nullable_array);
+        fieldSetFlags()[4] = other.fieldSetFlags()[4];
+      }
     }
 
     /**
@@ -294,6 +323,10 @@ private Builder(avro.examples.baseball.OptionalGettersNullableFieldsTest other)
         this.nullable_favorite_number = data().deepCopy(fields()[3].schema(), other.nullable_favorite_number);
         fieldSetFlags()[3] = true;
       }
+      if (isValidValue(fields()[4], other.nullable_array)) {
+        this.nullable_array = data().deepCopy(fields()[4].schema(), other.nullable_array);
+        fieldSetFlags()[4] = true;
+      }
     }
 
     /**
@@ -456,6 +489,46 @@ public avro.examples.baseball.OptionalGettersNullableFieldsTest.Builder clearNul
       return this;
     }
 
+    /**
+      * Gets the value of the 'nullable_array' field.
+      * @return The value.
+      */
+    public java.util.List<java.lang.CharSequence> getNullableArray() {
+      return nullable_array;
+    }
+
+
+    /**
+      * Sets the value of the 'nullable_array' field.
+      * @param value The value of 'nullable_array'.
+      * @return This builder.
+      */
+    public avro.examples.baseball.OptionalGettersNullableFieldsTest.Builder setNullableArray(java.util.List<java.lang.CharSequence> value) {
+      validate(fields()[4], value);
+      this.nullable_array = value;
+      fieldSetFlags()[4] = true;
+      return this;
+    }
+
+    /**
+      * Checks whether the 'nullable_array' field has been set.
+      * @return True if the 'nullable_array' field has been set, false otherwise.
+      */
+    public boolean hasNullableArray() {
+      return fieldSetFlags()[4];
+    }
+
+
+    /**
+      * Clears the value of the 'nullable_array' field.
+      * @return This builder.
+      */
+    public avro.examples.baseball.OptionalGettersNullableFieldsTest.Builder clearNullableArray() {
+      nullable_array = null;
+      fieldSetFlags()[4] = false;
+      return this;
+    }
+
     @Override
     @SuppressWarnings("unchecked")
     public OptionalGettersNullableFieldsTest build() {
@@ -465,6 +538,7 @@ public OptionalGettersNullableFieldsTest build() {
         record.nullable_name = fieldSetFlags()[1] ? this.nullable_name : (java.lang.CharSequence) defaultValue(fields()[1]);
         record.favorite_number = fieldSetFlags()[2] ? this.favorite_number :  defaultValue(fields()[2]);
         record.nullable_favorite_number = fieldSetFlags()[3] ? this.nullable_favorite_number : (java.lang.Integer) defaultValue(fields()[3]);
+        record.nullable_array = fieldSetFlags()[4] ? this.nullable_array : (java.util.List<java.lang.CharSequence>) defaultValue(fields()[4]);
         return record;
       } catch (org.apache.avro.AvroMissingFieldException e) {
         throw e;