Merge pull request #224 from podorvanova/document-gora-compiler
GORA-213 Document every method in GoraCompiler
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 @@
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 @@
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 @@
}
}
+ /**
+ *
+ * @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 @@
}
}
+ /**
+ *
+ * @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 @@
}
}
+ /**
+ *
+ * @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 @@
}
}
-
+
+ /**
+ *
+ * @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 @@
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 @@
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 @@
}
}
+ /**
+ *
+ * @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 @@
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";
