This is an automated email from the ASF dual-hosted git repository. lewismc pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/gora.git
The following commit(s) were added to refs/heads/master by this push: new 775171e GORA-213 Document every method in GoraCompiler new ff64c7e Merge pull request #224 from podorvanova/document-gora-compiler 775171e is described below commit 775171eca2ef9d64544a5dd95466055b85dcb18b Author: Maria Podorvanova <podorvanova.ma...@gmail.com> AuthorDate: Thu Oct 8 22:08:27 2020 +1100 GORA-213 Document every method in GoraCompiler --- .../org/apache/gora/compiler/GoraCompiler.java | 68 +++++++++++++++++++++- 1 file changed, 65 insertions(+), 3 deletions(-) diff --git a/gora-compiler/src/main/java/org/apache/gora/compiler/GoraCompiler.java b/gora-compiler/src/main/java/org/apache/gora/compiler/GoraCompiler.java index 003301e..9aeba68 100644 --- a/gora-compiler/src/main/java/org/apache/gora/compiler/GoraCompiler.java +++ b/gora-compiler/src/main/java/org/apache/gora/compiler/GoraCompiler.java @@ -63,7 +63,15 @@ public class GoraCompiler extends SpecificCompiler { static { GORA_HIDDEN_FIELD_NAMES.add(DIRTY_BYTES_FIELD_NAME); } - + + /** + * Compiles schemas into multiple files. + * + * @param srcFiles Source files which will be compiled. + * @param dest Path to the directory under which .java classes will be written. + * @param licenseHeader License header which will be added to compiled files. + * @throws IOException If there's an issue with compiling to the destination. + */ public static void compileSchema(File[] srcFiles, File dest, LicenseHeaders licenseHeader) throws IOException { Schema.Parser parser = new Schema.Parser(); @@ -112,7 +120,12 @@ public class GoraCompiler extends SpecificCompiler { LOG.info("Compiled avro into: {}", dest.getAbsolutePath()); return newSchema; } - + + /** + * @param schema Schema to be made immutable. + * @return String which can be appended to the given schema in order to + * make it immutable. + */ public static String generateAppropriateImmutabilityModifier(Schema schema){ switch (schema.getType()) { case BYTES: @@ -122,6 +135,11 @@ public class GoraCompiler extends SpecificCompiler { } } + /** + * + * @param schema Schema to be wrapped by dirty wrapper. + * @return Meta Java code which wraps "value" into dirty wrapper according to the given schema. + */ public static String generateAppropriateWrapperOrValue(Schema schema) { switch (schema.getType()) { case MAP: @@ -137,6 +155,12 @@ public class GoraCompiler extends SpecificCompiler { } } + /** + * + * @param schema Schema to be wrapped by dirty wrapper. + * @return Meta Java code which wraps "value" casted to the necessary type + * into dirty wrapper according to the given schema. + */ public static String generateAppropriateWrapperOrValueForPut(Schema schema) { switch (schema.getType()) { case MAP: @@ -150,6 +174,13 @@ public class GoraCompiler extends SpecificCompiler { } } + /** + * + * @param schema Schema to be wrapped by dirty wrapper. + * @param field The field within a record. + * @return Meta Java code which creates default value according to the field/schema type + * and wraps it into dirty wrapper if necessary. + */ public static String generateAppropriateWrapper(Schema schema, Field field) { if (DIRTY_BYTES_FIELD_NAME.equals(field.name())) { return "java.nio.ByteBuffer.wrap(new byte[" @@ -168,7 +199,13 @@ public class GoraCompiler extends SpecificCompiler { } } - + + /** + * + * @param field The field within a record. + * @return Meta Java code which creates a new collection according to the field type + * and wraps it into dirty wrapper if necessary. + */ public static String generateAppropriateValue(Field field) { switch (field.schema().getType()) { case RECORD: @@ -209,6 +246,13 @@ public class GoraCompiler extends SpecificCompiler { return (int) Math.ceil((originalSchema.getFields().size() + 1) * 0.125); } + /** + * Generates isDirty method for a field. + * + * @param schema The schema in which the field is defined. + * @param field The field for which to generate the dirty method name. + * @return The name of the isDirty method for the given field. + */ public static String generateDirtyMethod(Schema schema, Field field) { /* * TODO: See AVRO-1127. This is dirty. We need to file a bug in avro to @@ -220,6 +264,13 @@ public class GoraCompiler extends SpecificCompiler { return dirtyMethod; } + /** + * + * @param schema The schema in which the field is defined. + * @param fieldName The name of the field within a record. + * @return Meta Java code which creates a default value for byte type + * and wraps a byte array into a buffer. + */ public static String generateDefaultValueString(Schema schema, String fieldName) { if (DIRTY_BYTES_FIELD_NAME.equals(fieldName)) { return "java.nio.ByteBuffer.wrap(new byte[" @@ -230,6 +281,11 @@ public class GoraCompiler extends SpecificCompiler { } } + /** + * + * @param fieldName The name of the field within a record. + * @return True if field is not generated by Gora. + */ public static boolean isNotHiddenField(String fieldName) { return !GORA_HIDDEN_FIELD_NAMES.contains(fieldName); } @@ -323,6 +379,12 @@ public class GoraCompiler extends SpecificCompiler { return SchemaNormalization.parsingFingerprint64(schema); } + /** + * + * @param destDir Path to the directory under which .java classes will be written. + * @param schema Data bean AVRO schema. + * @return Path to the generated .java file according to the schema. + */ public static String generateDestinationFileName(String destDir, Schema schema) { return destDir + File.separatorChar + schema.getNamespace().replace('.', File.separatorChar) + File.separatorChar + schema.getName() + ".java";