From 18c1d3ade7238a55b1a29833d8a76336edca453b Mon Sep 17 00:00:00 2001 From: amckenzie Date: Tue, 12 Sep 2017 12:24:05 +0100 Subject: [PATCH] add javadoc to classes --- .../plugin/DefaultPluginProvider.java | 6 +-- .../AddFieldsAndMethodsToClassPlugin.java | 9 ++++ .../classgenerator/ClassModifyingPlugin.java | 17 +++++++ .../GenerateBuilderForClassPlugin.java | 40 ++++++++++++++++- .../MakeClassSerializablePlugin.java | 27 ++++++++++++ .../typename/SupportJavaOptionalsPlugin.java | 22 ++++++++++ .../plugin/typename/SupportUuidsPlugin.java | 44 +++++++++++++++++++ .../typename/SupportZonedDateTimePlugin.java | 44 +++++++++++++++++++ .../plugin/typename/TypeModifyingPlugin.java | 20 +++++++++ .../generation/pojo/TestPluginProvider.java | 2 +- .../plugin/DefaultPluginProviderTest.java | 6 +-- .../generators/plugin/PluginTestProvider.java | 2 +- .../plugin/PluginTestProviderTest.java | 2 +- 13 files changed, 230 insertions(+), 11 deletions(-) diff --git a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/DefaultPluginProvider.java b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/DefaultPluginProvider.java index d59bdc9..434ec51 100644 --- a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/DefaultPluginProvider.java +++ b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/DefaultPluginProvider.java @@ -2,15 +2,15 @@ import static java.util.Arrays.asList; -import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddFieldsAndMethodsToClassPlugin; +import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin; +import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.GenerateBuilderForClassPlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.MakeClassSerializablePlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.builder.BuilderGeneratorFactory; -import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.GenerateBuilderForClassPlugin; import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportJavaOptionalsPlugin; -import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin; import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportUuidsPlugin; import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportZonedDateTimePlugin; +import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin; import java.util.List; diff --git a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/AddFieldsAndMethodsToClassPlugin.java b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/AddFieldsAndMethodsToClassPlugin.java index 394812b..7638bc8 100644 --- a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/AddFieldsAndMethodsToClassPlugin.java +++ b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/AddFieldsAndMethodsToClassPlugin.java @@ -19,6 +19,15 @@ import com.squareup.javapoet.ParameterSpec; import com.squareup.javapoet.TypeSpec; +/** + * Plugin that adds fields, a constructor and getter methods to a class's + * Type Specification. + * + * Without this plugin each class will be generated with + * no fields nor getter methods and with an empty constructor. For this reason + * this class is added by default; although it is possible to override it should + * you need to change it's behaviour. + */ public class AddFieldsAndMethodsToClassPlugin implements ClassModifyingPlugin { private final AdditionalPropertiesGenerator additionalPropertiesGenerator = new AdditionalPropertiesGenerator(); diff --git a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/ClassModifyingPlugin.java b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/ClassModifyingPlugin.java index 5cf218c..3847f83 100644 --- a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/ClassModifyingPlugin.java +++ b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/ClassModifyingPlugin.java @@ -4,8 +4,25 @@ import com.squareup.javapoet.TypeSpec; +/** + * Interface for all plugins that modify the generated classes. These can be plugins for + * example, adding fields and methods to the class, making the class {@link java.io.Serializable}, + * or adding specific annotations to the class or it's methods. + * + * {@link MakeClassSerializablePlugin} + * {@link AddFieldsAndMethodsToClassPlugin} + */ public interface ClassModifyingPlugin { + /** + * Modifies the generation of a class. + * + * @param typeSpecBuilder A builder for generating the class + * @param classDefinition The definition of the class from the json schema document + * @param pluginContext Access to any data the plugin might need + * + * @return The modified class's {@link TypeSpec} builder + */ TypeSpec.Builder generateWith(final TypeSpec.Builder typeSpecBuilder, final ClassDefinition classDefinition, final PluginContext pluginContext); diff --git a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/GenerateBuilderForClassPlugin.java b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/GenerateBuilderForClassPlugin.java index a77da44..bdff1e2 100644 --- a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/GenerateBuilderForClassPlugin.java +++ b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/GenerateBuilderForClassPlugin.java @@ -1,14 +1,50 @@ package uk.gov.justice.generation.pojo.generators.plugin.classgenerator; import uk.gov.justice.generation.pojo.dom.ClassDefinition; -import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin; -import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.PluginContext; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.builder.BuilderGenerator; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.builder.BuilderGeneratorFactory; import com.squareup.javapoet.MethodSpec; import com.squareup.javapoet.TypeSpec; +/** + * Adds a builder for the class as an static inner class and a static + * method for accessing the builder. For example, a class MyClass specified + * with one property myProperty would be generated thusly: + * + * 
+ *     {@code public class MyClass {
+ *
+ *          private final String myProperty;
+ *
+ *          public MyClass(final String myProperty) {
+ *              this.myProperty = myProperty;
+ *          }
+ *
+ *          public String getMyProperty() {
+ *              return myProperty;
+ *          }
+ *
+ *          public static Builder myClass() {
+ *              return new MyClass.Builder();
+ *          }
+ *
+ *          public static class Builder {
+ *
+ *              private String myProperty;
+ *
+ *              public Builder withMyProperty(final String myProperty) {
+ *                  this.myProperty = myProperty;
+ *                  return this;
+ *              }
+ *
+ *              public MyClass build() {
+ *                  return new MyClass(myProperty);
+ *              }
+ *          }
+ *      }
+ * }
+ */ public class GenerateBuilderForClassPlugin implements ClassModifyingPlugin { private final BuilderGeneratorFactory builderGeneratorFactory; diff --git a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/MakeClassSerializablePlugin.java b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/MakeClassSerializablePlugin.java index 2c0365e..8347886 100644 --- a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/MakeClassSerializablePlugin.java +++ b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/classgenerator/MakeClassSerializablePlugin.java @@ -12,6 +12,33 @@ import com.squareup.javapoet.FieldSpec; import com.squareup.javapoet.TypeSpec; +/** + * A class plugin that adds {@see Serializable} interface and + * {@Code serialVersionUID} to the generated class. + * + * Note: the serialVersionUID is always set to 1. + * + * For example: + * + * 
+ *     {@code public class MyClass implements Serializable {
+ *
+ *          private static final long serialVersionUID = 1L;
+ *
+ *          private final String myProperty;
+ *
+ *          public MyClass(final String myProperty) {
+ *              this.myProperty = myProperty;
+ *          }
+ *
+ *          public String getMyProperty() {
+ *              return myProperty;
+ *          }
+ *      }
+ *     }
+ *
+ *
+ */ public class MakeClassSerializablePlugin implements ClassModifyingPlugin { private static final String SERIAL_VERSION_FIELD_NAME = "serialVersionUID"; diff --git a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportJavaOptionalsPlugin.java b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportJavaOptionalsPlugin.java index 453b659..9726218 100644 --- a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportJavaOptionalsPlugin.java +++ b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportJavaOptionalsPlugin.java @@ -10,6 +10,28 @@ import com.squareup.javapoet.ParameterizedTypeName; import com.squareup.javapoet.TypeName; +/** + * A type modifying plugin for setting all properties which are not marked as required + * in the json schema document to be wrapped in a java {@see Optional}. + * + * For example: + * + * 
+ *     {@code public class MyClass {
+ *
+ *          private final Optional myProperty;
+ *
+ *          public MyClass(final Optional myProperty) {
+ *              this.myProperty = myProperty;
+ *          }
+ *
+ *          public Optional getMyProperty() {
+ *              return myProperty;
+ *          }
+ *      }
+ *
+ * }
+ */ public class SupportJavaOptionalsPlugin implements TypeModifyingPlugin { @Override diff --git a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportUuidsPlugin.java b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportUuidsPlugin.java index a84b7a8..563aa3e 100644 --- a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportUuidsPlugin.java +++ b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportUuidsPlugin.java @@ -10,6 +10,50 @@ import com.squareup.javapoet.TypeName; +/** + * Adds support for using {@see UUID} as return types and constructor parameters in the generated + * class. + * + * To Use: + *

+ * The uuid should be specified as a reference in your json schema file: + * 

+ *         {@code "myProperty": {
+ *                  "$ref": "#/definitions/UUID"
+ *              },
+ *              "definitions": {
+ *                  "UUID": {
+ *                      "type": "string",
+ *                      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$",
+ *                  }
+ *              }
+ *
+ *     }
+ *

+ * + * The name {@code UUID} in the definition is important as this is how we specify that + * the types should be of type {@link UUID}. + * + *

+ * This will generate the following code: + * 

+ *          {@code
+ *  public class MyClass {
+ *
+ *                  private final UUID myProperty;
+ *
+ *                  public MyClass(final UUID myProperty) {
+ *                      this.myProperty = myProperty;
+ *                  }
+ *
+ *                  public UUID getMyProperty() {
+ *                      return myProperty;
+ *                  }
+ *              }
+ * }
+ *

+ * + */ public class SupportUuidsPlugin implements TypeModifyingPlugin { @Override diff --git a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportZonedDateTimePlugin.java b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportZonedDateTimePlugin.java index f2439db..af1ce35 100644 --- a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportZonedDateTimePlugin.java +++ b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportZonedDateTimePlugin.java @@ -10,6 +10,50 @@ import com.squareup.javapoet.TypeName; +/** + * Adds support for using {@see ZonedDateTime} as return types and constructor parameters in the generated + * class. + * + * To Use: + *

+ * The ZonedDateTime should be specified as a reference in your json schema file: + * 

+ *         {@code "myProperty": {
+ *                  "$ref": "#/definitions/ZonedDateTime"
+ *              },
+ *              "definitions": {
+ *                  "ZonedDateTime": {
+ *                      "type": "string",
+ *                      "pattern": "^[1|2][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]$"
+ *                  }
+ *              }
+ *
+ *     }
+ *

+ * + * The name {@code ZonedDateTime} in the definition is important as this is how we specify that + * the types should be of type {@link ZonedDateTime}. + * + *

+ * This will generate the following code: + * 

+ *          {@code public class MyClass {
+ *
+ *                  private final ZonedDateTime myProperty;
+ *
+ *                  public MyClass(final ZonedDateTime myProperty) {
+ *                      this.myProperty = myProperty;
+ *                  }
+ *
+ *                  public ZonedDateTime getMyProperty() {
+ *                      return myProperty;
+ *                  }
+ *              }
+ * }
+ *

+ * + */ + public class SupportZonedDateTimePlugin implements TypeModifyingPlugin { @Override diff --git a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/TypeModifyingPlugin.java b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/TypeModifyingPlugin.java index f289c5e..6372444 100644 --- a/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/TypeModifyingPlugin.java +++ b/pojo-generator-core/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/typename/TypeModifyingPlugin.java @@ -4,7 +4,27 @@ import com.squareup.javapoet.TypeName; +/** + * Interface for all plugins that modify return types and parameters of generated classes. For + * example these plugins can change the types of nullable properties in a class to + * {@link java.util.Optional}, support for {@link java.util.UUID} as return types and constructor + * parameters, or support for {@link java.time.ZonedDateTime} as return types and constructor + * parameters + * + * {@link SupportJavaOptionalsPlugin} + * {@link SupportUuidsPlugin} + * {@link SupportZonedDateTimePlugin} + */ public interface TypeModifyingPlugin { + /** + * Modifies the TypeName (used as constructor parameters and getter return types) of + * generated classes in some way. + * + * @param typeName The type name to be modified + * @param definition The FieldDefinition of the type to be modified + * + * @return The modified type name + */ TypeName modifyTypeName(final TypeName typeName, final Definition definition); } diff --git a/pojo-generator-core/src/test/java/uk/gov/justice/generation/pojo/TestPluginProvider.java b/pojo-generator-core/src/test/java/uk/gov/justice/generation/pojo/TestPluginProvider.java index 37f0832..b340839 100644 --- a/pojo-generator-core/src/test/java/uk/gov/justice/generation/pojo/TestPluginProvider.java +++ b/pojo-generator-core/src/test/java/uk/gov/justice/generation/pojo/TestPluginProvider.java @@ -4,8 +4,8 @@ import static java.util.Collections.singletonList; import uk.gov.justice.generation.pojo.generators.plugin.PluginProvider; -import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddFieldsAndMethodsToClassPlugin; +import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.MakeClassSerializablePlugin; import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportJavaOptionalsPlugin; import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin; diff --git a/pojo-generator-core/src/test/java/uk/gov/justice/generation/pojo/generators/plugin/DefaultPluginProviderTest.java b/pojo-generator-core/src/test/java/uk/gov/justice/generation/pojo/generators/plugin/DefaultPluginProviderTest.java index 639bc59..91e5292 100644 --- a/pojo-generator-core/src/test/java/uk/gov/justice/generation/pojo/generators/plugin/DefaultPluginProviderTest.java +++ b/pojo-generator-core/src/test/java/uk/gov/justice/generation/pojo/generators/plugin/DefaultPluginProviderTest.java @@ -5,14 +5,14 @@ import static org.hamcrest.CoreMatchers.is; import static org.junit.Assert.assertThat; -import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddFieldsAndMethodsToClassPlugin; -import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.MakeClassSerializablePlugin; +import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.GenerateBuilderForClassPlugin; +import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.MakeClassSerializablePlugin; import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportJavaOptionalsPlugin; -import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin; import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportUuidsPlugin; import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportZonedDateTimePlugin; +import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin; import java.util.List; diff --git a/pojo-plugin-test-provider/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/PluginTestProvider.java b/pojo-plugin-test-provider/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/PluginTestProvider.java index c7f9f03..6c7ea5e 100644 --- a/pojo-plugin-test-provider/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/PluginTestProvider.java +++ b/pojo-plugin-test-provider/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/PluginTestProvider.java @@ -3,9 +3,9 @@ import static java.util.Arrays.asList; import static java.util.Collections.emptyList; -import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddEventAnnotationToClassPlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddFieldsAndMethodsToClassPlugin; +import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.MakeClassSerializablePlugin; import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin; diff --git a/pojo-plugin-test-provider/src/test/java/uk/gov/justice/generation/pojo/generators/plugin/PluginTestProviderTest.java b/pojo-plugin-test-provider/src/test/java/uk/gov/justice/generation/pojo/generators/plugin/PluginTestProviderTest.java index f34adce..442e56f 100644 --- a/pojo-plugin-test-provider/src/test/java/uk/gov/justice/generation/pojo/generators/plugin/PluginTestProviderTest.java +++ b/pojo-plugin-test-provider/src/test/java/uk/gov/justice/generation/pojo/generators/plugin/PluginTestProviderTest.java @@ -5,9 +5,9 @@ import static org.hamcrest.CoreMatchers.is; import static org.junit.Assert.assertThat; -import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddEventAnnotationToClassPlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddFieldsAndMethodsToClassPlugin; +import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin; import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.MakeClassSerializablePlugin; import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin;