Repository: gora Updated Branches: refs/heads/pull_93 [created] d5d673cdf
GORA-501 Fix Javadoc for JDK1.8 Project: http://git-wip-us.apache.org/repos/asf/gora/repo Commit: http://git-wip-us.apache.org/repos/asf/gora/commit/d5d673cd Tree: http://git-wip-us.apache.org/repos/asf/gora/tree/d5d673cd Diff: http://git-wip-us.apache.org/repos/asf/gora/diff/d5d673cd Branch: refs/heads/pull_93 Commit: d5d673cdf06aacf707c3aff8134a713e189d15b9 Parents: fb7622f Author: Kevin Ratnasekera <djkevi...@yahoo.com> Authored: Sun Jan 29 22:52:35 2017 +0530 Committer: Kevin Ratnasekera <djkevi...@yahoo.com> Committed: Sun Jan 29 22:52:35 2017 +0530 ---------------------------------------------------------------------- .../java/org/apache/gora/util/AvroUtils.java | 36 ++- .../java/org/apache/gora/util/ByteUtils.java | 293 +++++++++++-------- .../org/apache/gora/util/ClassLoadingUtils.java | 12 +- .../main/java/org/apache/gora/util/IOUtils.java | 220 +++++++++++--- .../java/org/apache/gora/util/NodeWalker.java | 4 +- .../org/apache/gora/util/ReflectionUtils.java | 53 +++- .../java/org/apache/gora/util/StringUtils.java | 29 +- .../java/org/apache/gora/util/VersionInfo.java | 25 +- pom.xml | 34 +++ 9 files changed, 513 insertions(+), 193 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/gora/blob/d5d673cd/gora-core/src/main/java/org/apache/gora/util/AvroUtils.java ---------------------------------------------------------------------- diff --git a/gora-core/src/main/java/org/apache/gora/util/AvroUtils.java b/gora-core/src/main/java/org/apache/gora/util/AvroUtils.java index d07c6c2..c1e3a88 100644 --- a/gora-core/src/main/java/org/apache/gora/util/AvroUtils.java +++ b/gora-core/src/main/java/org/apache/gora/util/AvroUtils.java @@ -36,12 +36,15 @@ import org.apache.avro.specific.SpecificDatumWriter; import org.apache.gora.persistency.impl.PersistentBase; /** - * An utility class for Avro related tasks + * An utility class for Avro related tasks. */ public class AvroUtils { /** * Returns a map of field name to Field for schema's fields. + * + * @param schema the schema object to get the map of field name to Field. + * @return map of field name to Field. */ public static Map<String, Field> getFieldMap(Schema schema) { List<Field> fields = schema.getFields(); @@ -63,7 +66,16 @@ public class AvroUtils { } /** - * Returns the schema of the class + * Returns the schema of the class. + * + * @param clazz Class instance of the persistent bean. + * @throws SecurityException if the caller's class loader is not the same as the + * class loader of above class. + * @throws NoSuchFieldException if a field with the specified name is not found. + * @throws IllegalArgumentException this will not be thrown since <code>field.get(obj)</code> passing obj is ignored + * since the SCHEMA field is a static class level variable inside the persistent bean class. + * @throws IllegalAccessException if the field is inaccessible due to java language access control. + * @return the schema of persistent bean instance. */ public static Schema getSchema(Class<? extends PersistentBase> clazz) throws SecurityException, NoSuchFieldException, IllegalArgumentException, @@ -74,21 +86,20 @@ public class AvroUtils { } /** - * Return the field names from a persistent object + * Return the field names from a persistent object. * - * @param persistent - * the persistent object to get the fields names from - * @return the field names + * @param persistent the persistent object to get the fields names from. + * @return the field names String array. */ public static String[] getPersistentFieldNames(PersistentBase persistent) { return getSchemaFieldNames(persistent.getSchema()); } /** - * Return the field names from a schema object + * Return the field names from a schema object. * - * @param schema the schema object to get the fields names from - * @return the field names + * @param schema the schema object to get the fields names from. + * @return the field names String array. */ public static String[] getSchemaFieldNames(Schema schema) { List<Field> fields = schema.getFields(); @@ -99,6 +110,13 @@ public class AvroUtils { return fieldNames; } + /** + * Utility method for deep clone a given AVRO persistent bean instance. + * + * @param persistent source persistent bean instance. + * @param <T> persistent bean type. + * @return cloned persistent bean to be returned. + */ public static <T extends PersistentBase> T deepClonePersistent(T persistent) { final SpecificDatumWriter<PersistentBase> writer = new SpecificDatumWriter<>(persistent.getSchema()); final byte[] byteData; http://git-wip-us.apache.org/repos/asf/gora/blob/d5d673cd/gora-core/src/main/java/org/apache/gora/util/ByteUtils.java ---------------------------------------------------------------------- diff --git a/gora-core/src/main/java/org/apache/gora/util/ByteUtils.java b/gora-core/src/main/java/org/apache/gora/util/ByteUtils.java index 933f33d..e48607c 100644 --- a/gora-core/src/main/java/org/apache/gora/util/ByteUtils.java +++ b/gora-core/src/main/java/org/apache/gora/util/ByteUtils.java @@ -85,12 +85,13 @@ public class ByteUtils { /** * Put bytes at the specified byte array position. - * @param tgtBytes the byte array - * @param tgtOffset position in the array - * @param srcBytes byte to write out - * @param srcOffset - * @param srcLength - * @return incremented offset + * + * @param tgtBytes the byte array which source/input bytes are written. + * @param tgtOffset offset position in the array to be considered to write bytes. + * @param srcBytes source of byte to write out on target byte array. + * @param srcOffset offset of source byte array to be considered. + * @param srcLength length from offset of source byte array to be considered. + * @return incremented offset. */ public static int putBytes(byte[] tgtBytes, int tgtOffset, byte[] srcBytes, int srcOffset, int srcLength) { @@ -100,10 +101,11 @@ public class ByteUtils { /** * Write a single byte out to the specified byte array position. - * @param bytes the byte array - * @param offset position in the array - * @param b byte to write out - * @return incremented offset + * + * @param bytes the byte array input. + * @param offset position in the array. + * @param b byte to write out. + * @return incremented offset. */ public static int putByte(byte[] bytes, int offset, byte b) { bytes[offset] = b; @@ -112,8 +114,9 @@ public class ByteUtils { /** * Returns a new byte array, copied from the passed ByteBuffer. - * @param bb A ByteBuffer - * @return the byte array + * + * @param bb A ByteBuffer as input. + * @return the byte array of <code>bb</code>. */ public static byte[] toBytes(ByteBuffer bb) { int length = bb.limit(); @@ -123,8 +126,10 @@ public class ByteUtils { } /** + * Converts a byte array to it s String representation. + * * @param b Presumed UTF-8 encoded byte array. - * @return String made from <code>b</code> + * @return String made from <code>b</code>. */ public static String toString(final byte [] b) { if (b == null) { @@ -133,6 +138,14 @@ public class ByteUtils { return toString(b, 0, b.length); } + /** + * Converts two byte array given a separator string in between to single String representation. + * + * @param b1 Presumed UTF-8 encoded byte array input 1. + * @param b2 Presumed UTF-8 encoded byte array input 2. + * @param sep Separator String. + * @return String made from <code>b1</code>+<code>sep</code>+<code>b2</code>. + */ public static String toString(final byte [] b1, String sep, final byte [] b2) { @@ -140,10 +153,12 @@ public class ByteUtils { } /** + * Converts byte array given offset and length to it s String representation. + * * @param b Presumed UTF-8 encoded byte array. - * @param off - * @param len - * @return String made from <code>b</code> + * @param off offset to be from the input byte array. + * @param len length to be considered from the offset. + * @return String made from <code>b</code>. */ public static String toString(final byte [] b, int off, int len) { if(b == null) { @@ -161,10 +176,12 @@ public class ByteUtils { } return result; } + /** * Converts a string to a UTF-8 byte array. - * @param s - * @return the byte array + * + * @param s input String value. + * @return the byte array. */ public static byte[] toBytes(String s) { if (s == null) { @@ -182,7 +199,8 @@ public class ByteUtils { /** * Convert a boolean to a byte array. - * @param b + * + * @param b input boolean value. * @return <code>b</code> encoded in a byte array. */ public static byte [] toBytes(final boolean b) { @@ -192,8 +210,10 @@ public class ByteUtils { } /** - * @param b - * @return True or false. + * Convert a byte array to it s boolean value. + * + * @param b input byte array. + * @return boolean value either True or false. */ public static boolean toBoolean(final byte [] b) { if (b == null || b.length > 1) { @@ -203,9 +223,10 @@ public class ByteUtils { } /** - * Convert a long value to a byte array - * @param val - * @return the byte array + * Convert a long value to a byte array. + * + * @param val input long value. + * @return the byte array. */ public static byte[] toBytes(long val) { byte [] b = new byte[8]; @@ -218,30 +239,33 @@ public class ByteUtils { } /** - * Converts a byte array to a long value - * @param bytes - * @return the long value + * Converts a byte array to a long value. + * + * @param bytes input byte array. + * @return the long value. */ public static long toLong(byte[] bytes) { return toLong(bytes, 0); } /** - * Converts a byte array to a long value - * @param bytes - * @param offset - * @return the long value + * Converts a byte array to a long value. + * + * @param bytes input byte array. + * @param offset offset to be from the input byte array. + * @return the long value. */ public static long toLong(byte[] bytes, int offset) { return toLong(bytes, offset, SIZEOF_LONG); } /** - * Converts a byte array to a long value - * @param bytes - * @param offset - * @param length - * @return the long value + * Converts a byte array to a long value. + * + * @param bytes input byte array. + * @param offset offset to be from the input byte array. + * @param length length to be considered from the offset. + * @return the long value. */ public static long toLong(byte[] bytes, int offset, final int length) { if (bytes == null || length != SIZEOF_LONG || @@ -257,8 +281,9 @@ public class ByteUtils { } /** - * Presumes float encoded as IEEE 754 floating-point "single format" - * @param bytes + * Presumes float encoded as IEEE 754 floating-point "single format". + * + * @param bytes offset to be considered from byte array. * @return Float made from passed byte array. */ public static float toFloat(byte [] bytes) { @@ -266,9 +291,10 @@ public class ByteUtils { } /** - * Presumes float encoded as IEEE 754 floating-point "single format" - * @param bytes - * @param offset + * Presumes float encoded as IEEE 754 floating-point "single format". + * + * @param bytes input byte array to be considered. + * @param offset offset to be considered from byte array. * @return Float made from passed byte array. */ public static float toFloat(byte [] bytes, int offset) { @@ -276,8 +302,10 @@ public class ByteUtils { return Float.intBitsToFloat(i); } /** - * @param f - * @return the float represented as byte [] + * Converts float value to it s byte array representation. + * + * @param f input float value. + * @return the float represented as byte []. */ public static byte [] toBytes(final float f) { // Encode it as int @@ -286,7 +314,9 @@ public class ByteUtils { } /** - * @param bytes + * Converts byte array to a double value. + * + * @param bytes input byte array to be considered. * @return Return double made from passed bytes. */ public static double toDouble(final byte [] bytes) { @@ -294,8 +324,10 @@ public class ByteUtils { } /** - * @param bytes - * @param offset + * Converts byte array given offset to double value. + * + * @param bytes input byte array. + * @param offset offset to be considered from input array. * @return Return double made from passed bytes. */ public static double toDouble(final byte [] bytes, final int offset) { @@ -304,8 +336,10 @@ public class ByteUtils { } /** - * @param d - * @return the double represented as byte [] + * Converts double value to byte array. + * + * @param d double input value. + * @return the double represented as byte []. */ public static byte [] toBytes(final double d) { // Encode it as a long @@ -314,9 +348,10 @@ public class ByteUtils { } /** - * Convert an int value to a byte array - * @param val - * @return the byte array + * Convert an int value to a byte array. + * + * @param val int input value. + * @return the byte array. */ public static byte[] toBytes(int val) { byte [] b = new byte[4]; @@ -329,8 +364,9 @@ public class ByteUtils { } /** - * Converts a byte array to an int value - * @param bytes + * Converts a byte array to an int value. + * + * @param bytes input byte array to be converted. * @return the int value */ public static int toInt(byte[] bytes) { @@ -338,21 +374,23 @@ public class ByteUtils { } /** - * Converts a byte array to an int value - * @param bytes - * @param offset - * @return the int value + * Converts a byte array to an int value. + * + * @param bytes input byte array. + * @param offset input byte array offset. + * @return the int value. */ public static int toInt(byte[] bytes, int offset) { return toInt(bytes, offset, SIZEOF_INT); } /** - * Converts a byte array to an int value - * @param bytes - * @param offset - * @param length - * @return the int value + * Converts a byte array to an int value. + * + * @param bytes input byte array. + * @param offset input byte array offset. + * @param length length from offset position. + * @return the int value. */ public static int toInt(byte[] bytes, int offset, final int length) { if (bytes == null || length != SIZEOF_INT || @@ -368,9 +406,10 @@ public class ByteUtils { } /** - * Convert a short value to a byte array - * @param val - * @return the byte array + * Convert a short value to a byte array. + * + * @param val input short value. + * @return the byte array. */ public static byte[] toBytes(short val) { byte[] b = new byte[SIZEOF_SHORT]; @@ -381,30 +420,33 @@ public class ByteUtils { } /** - * Converts a byte array to a short value - * @param bytes - * @return the short value + * Converts a byte array to a short value. + * + * @param bytes input byte array. + * @return the short value. */ public static short toShort(byte[] bytes) { return toShort(bytes, 0); } /** - * Converts a byte array to a short value - * @param bytes - * @param offset - * @return the short value + * Converts a byte array to a short value. + * + * @param bytes input byte array. + * @param offset offset position of input array. + * @return the short value. */ public static short toShort(byte[] bytes, int offset) { return toShort(bytes, offset, SIZEOF_SHORT); } /** - * Converts a byte array to a short value - * @param bytes - * @param offset - * @param length - * @return the short value + * Converts a byte array to a short value. + * + * @param bytes input byte array. + * @param offset offset position from input byte array. + * @param length length to be considered from offset. + * @return the short value. */ public static short toShort(byte[] bytes, int offset, final int length) { if (bytes == null || length != SIZEOF_SHORT || @@ -419,10 +461,10 @@ public class ByteUtils { } /** - * Convert a char value to a byte array + * Convert a char value to a byte array. * - * @param val - * @return the byte array + * @param val input char value. + * @return the byte array. */ public static byte[] toBytes(char val) { byte[] b = new byte[SIZEOF_CHAR]; @@ -433,10 +475,10 @@ public class ByteUtils { } /** - * Converts a byte array to a char value + * Converts a byte array to a char value. * - * @param bytes - * @return the char value + * @param bytes input bytes array. + * @return the char value. */ public static char toChar(byte[] bytes) { return toChar(bytes, 0); @@ -444,23 +486,23 @@ public class ByteUtils { /** - * Converts a byte array to a char value + * Converts a byte array to a char value. * - * @param bytes - * @param offset - * @return the char value + * @param bytes input bytes array. + * @param offset offset to be considered from input array. + * @return the char value. */ public static char toChar(byte[] bytes, int offset) { return toChar(bytes, offset, SIZEOF_CHAR); } /** - * Converts a byte array to a char value + * Converts a byte array to a char value. * - * @param bytes - * @param offset - * @param length - * @return the char value + * @param bytes input byte array. + * @param offset offset to be considered from input array. + * @param length length to be considered from offset. + * @return the char value. */ public static char toChar(byte[] bytes, int offset, final int length) { if (bytes == null || length != SIZEOF_CHAR || @@ -475,33 +517,33 @@ public class ByteUtils { } /** - * Converts a byte array to a char array value + * Converts a byte array to a char array value. * - * @param bytes - * @return the char value + * @param bytes input byte array. + * @return the char value. */ public static char[] toChars(byte[] bytes) { return toChars(bytes, 0, bytes.length); } /** - * Converts a byte array to a char array value + * Converts a byte array to a char array value. * - * @param bytes - * @param offset - * @return the char value + * @param bytes input byte array. + * @param offset offset to be considered from input array. + * @return the char value. */ public static char[] toChars(byte[] bytes, int offset) { return toChars(bytes, offset, bytes.length-offset); } /** - * Converts a byte array to a char array value + * Converts a byte array to a char array value. * - * @param bytes - * @param offset - * @param length - * @return the char value + * @param bytes input byte array. + * @param offset offset to be considered from input array. + * @param length length to be considered from offset. + * @return the char value. */ public static char[] toChars(byte[] bytes, int offset, final int length) { int max = offset + length; @@ -521,6 +563,8 @@ public class ByteUtils { } /** + * Converts a int value to it s variable length byte array representation. + * * @param vint Integer to make a vint of. * @return Vint as bytes array. */ @@ -559,7 +603,9 @@ public class ByteUtils { } /** - * @param buffer + * Converts variable length byte array to it s long value representation. + * + * @param buffer input byte array. * @return vint bytes as an integer. */ public static long bytesToVlong(final byte [] buffer) { @@ -579,7 +625,9 @@ public class ByteUtils { } /** - * @param buffer + * Converts variable length byte array to it s int value representation. + * + * @param buffer input byte array. * @return vint bytes as an integer. */ public static int bytesToVint(final byte [] buffer) { @@ -600,9 +648,10 @@ public class ByteUtils { /** * Reads a zero-compressed encoded long from input stream and returns it. - * @param buffer Binary array + * + * @param buffer Binary input array. * @param offset Offset into array at which vint begins. - * @throws java.io.IOException + * @throws java.io.IOException when read error occurs while extracting data from input stream. * @return deserialized long from stream. */ public static long readVLong(final byte [] buffer, final int offset) @@ -622,8 +671,10 @@ public class ByteUtils { } /** - * @param left - * @param right + * Compare byte two byte arrays, and returns a int value accordingly. + * + * @param left left byte array to be considered. + * @param right right byte array to be considered. * @return 0 if equal, {@literal <} 0 if left is less than right, etc. */ public static int compareTo(final byte [] left, final byte [] right) { @@ -631,12 +682,14 @@ public class ByteUtils { } /** - * @param b1 - * @param b2 - * @param s1 Where to start comparing in the left buffer - * @param s2 Where to start comparing in the right buffer - * @param l1 How much to compare from the left buffer - * @param l2 How much to compare from the right buffer + * Compare byte two byte arrays given offset and length, and returns a int value accordingly. + * + * @param b1 left byte array to be considered. + * @param b2 right byte array to be considered. + * @param s1 Where to start comparing in the left buffer. + * @param s2 Where to start comparing in the right buffer. + * @param l1 How much to compare from the left buffer. + * @param l2 How much to compare from the right buffer. * @return 0 if equal, {@literal <} 0 if left is less than right, etc. */ public static int compareTo(byte[] b1, int s1, int l1, @@ -655,9 +708,11 @@ public class ByteUtils { } /** - * @param left - * @param right - * @return True if equal + * Compare byte two byte arrays for equality, and returns a boolean value accordingly. + * + * @param left left byte array to be considered. + * @param right right byte array to be considered. + * @return True if equal. */ public static boolean equals(final byte [] left, final byte [] right) { // Could use Arrays.equals? http://git-wip-us.apache.org/repos/asf/gora/blob/d5d673cd/gora-core/src/main/java/org/apache/gora/util/ClassLoadingUtils.java ---------------------------------------------------------------------- diff --git a/gora-core/src/main/java/org/apache/gora/util/ClassLoadingUtils.java b/gora-core/src/main/java/org/apache/gora/util/ClassLoadingUtils.java index ea77c1a..70607fd 100644 --- a/gora-core/src/main/java/org/apache/gora/util/ClassLoadingUtils.java +++ b/gora-core/src/main/java/org/apache/gora/util/ClassLoadingUtils.java @@ -12,8 +12,9 @@ public class ClassLoadingUtils { * 2. The thread context class loader is being used. * If both approaches fail, returns null. * - * @param className The name of the class to load. + * @param className The name of the class to load. * @return The class or null if no class loader could load the class. + * @throws ClassNotFoundException if and only if no definition for the class with the specified name could be found. */ public static Class<?> loadClass(String className) throws ClassNotFoundException { return ClassLoadingUtils.loadClass(ClassLoadingUtils.class,className); @@ -26,8 +27,9 @@ public class ClassLoadingUtils { * If both approaches fail, returns null. * * @param contextClass The name of a context class to use. - * @param className The name of the class to load + * @param className The name of the class to load. * @return The class or null if no class loader could load the class. + * @throws ClassNotFoundException Aif and only if no definition for the class with the specified name could be found. */ public static Class<?> loadClass(Class<?> contextClass, String className) throws ClassNotFoundException { Class<?> clazz = null; @@ -46,9 +48,9 @@ public class ClassLoadingUtils { /** * Loads a {@link Class} from the specified {@link ClassLoader} without throwing {@ClassNotFoundException}. * - * @param className - * @param classLoader - * @return + * @param className The name of the class to load. + * @param classLoader Class loader instance where given class to be loaded. + * @return The class or null if no class loader could load the class. */ private static Class<?> loadClass(String className, ClassLoader classLoader) { Class<?> clazz = null; http://git-wip-us.apache.org/repos/asf/gora/blob/d5d673cd/gora-core/src/main/java/org/apache/gora/util/IOUtils.java ---------------------------------------------------------------------- diff --git a/gora-core/src/main/java/org/apache/gora/util/IOUtils.java b/gora-core/src/main/java/org/apache/gora/util/IOUtils.java index 2dd2467..ed095de 100644 --- a/gora-core/src/main/java/org/apache/gora/util/IOUtils.java +++ b/gora-core/src/main/java/org/apache/gora/util/IOUtils.java @@ -97,9 +97,17 @@ public class IOUtils { + out.getClass()); } - /** Serializes the object to the given dataoutput using - * available Hadoop serializations - * @throws IOException */ + /** + * Serializes the object to the given data output using + * available Hadoop serializations. + * + * @param conf Hadoop conf. + * @param obj object instance to be serialized. + * @param out data stream which serialized content is written. + * @param objClass Class type of the object to be serialized. + * @param <T> class type of object to be serialized. + * @throws IOException occurred while serializing the object to bytes. + */ public static<T> void serialize(Configuration conf, DataOutput out , T obj, Class<T> objClass) throws IOException { @@ -128,9 +136,16 @@ public class IOUtils { } } - /** Serializes the object to the given dataoutput using - * available Hadoop serializations - * @throws IOException */ + /** + * Serializes the object to the given data output using + * available Hadoop serializations. + * + * @param <T> class type of object to be serialized. + * @param conf Hadoop conf. + * @param obj object instance to be serialized. + * @param out data stream which serialized content is written. + * @throws IOException occurred while serializing the object to bytes. + */ @SuppressWarnings("unchecked") public static<T> void serialize(Configuration conf, DataOutput out , T obj) throws IOException { @@ -138,8 +153,16 @@ public class IOUtils { serialize(conf, out, obj, (Class<T>)obj.getClass()); } - /** Serializes the object to the given dataoutput using - * available Hadoop serializations*/ + /** + * Serializes the object to the given data output using + * available Hadoop serializations + * + * @param conf Hadoop conf. + * @param <T> class type of object to be serialized. + * @param obj object instance to be serialized. + * @return serialized byte array. + * @throws IOException occurred while serializing the object to bytes. + */ public static<T> byte[] serialize(Configuration conf, T obj) throws IOException { DataOutputBuffer buffer = new DataOutputBuffer(); serialize(conf, buffer, obj); @@ -149,6 +172,12 @@ public class IOUtils { /** * Serializes the field object using the datumWriter. + * + * @param <T> class type of object to be serialized. + * @param datumWriter AVRO datum writer for given schema. + * @param object object to be serialized. + * @param os output stream which serialized content is written. + * @throws IOException occurred while serializing the object to bytes. */ public static<T extends SpecificRecord> void serialize(OutputStream os, SpecificDatumWriter<T> datumWriter, T object) @@ -161,6 +190,12 @@ public class IOUtils { /** * Serializes the field object using the datumWriter. + * + * @param <T> class type of object to be serialized. + * @param datumWriter AVRO datum writer for given schema. + * @param object object to be serialized. + * @param os output stream which serialized content is written. + * @throws IOException occurred while serializing the object to bytes. */ public static<T> void serialize(OutputStream os, SpecificDatumWriter<T> datumWriter, T object) @@ -173,6 +208,12 @@ public class IOUtils { /** * Serializes the field object using the datumWriter. + * + * @param <T> class type of object to be serialized. + * @param datumWriter AVRO datum writer for given schema. + * @param object object to be serialized. + * @return serialized byte array. + * @throws IOException occurred while serializing the object to bytes. */ public static<T extends SpecificRecord> byte[] serialize(SpecificDatumWriter<T> datumWriter , T object) throws IOException { @@ -183,6 +224,12 @@ public class IOUtils { /** * Serializes the field object using the datumWriter. + * + * @param <T> class type of object to be serialized. + * @param datumWriter AVRO datum writer for given schema. + * @param object object to be serialized. + * @return serialized byte array. + * @throws IOException occurred while serializing the object to bytes. */ public static<T> byte[] serialize(SpecificDatumWriter<T> datumWriter , T object) throws IOException { @@ -191,10 +238,19 @@ public class IOUtils { return os.toByteArray(); } - /** Deserializes the object in the given datainput using + /** + * Deserializes the object in the given data input using * available Hadoop serializations. - * @throws IOException - * @throws ClassNotFoundException */ + * + * @param conf Hadoop conf. + * @param in data input stream where serialized content is read. + * @param <T> object class type. + * @param obj data object. + * @param objClass object class type as String. + * @return deserialized object. + * @throws IOException occurred while deserializing the byte content. + * @throws ClassNotFoundException class definition cannot be found for given class name. + */ @SuppressWarnings("unchecked") public static<T> T deserialize(Configuration conf, DataInput in , T obj , String objClass) throws IOException, ClassNotFoundException { @@ -204,9 +260,18 @@ public class IOUtils { return deserialize(conf, in, obj, c); } - /** Deserializes the object in the given datainput using + /** + * Deserializes the object in the given data input using * available Hadoop serializations. - * @throws IOException */ + * + * @param conf Hadoop conf. + * @param in data input stream where serialized content is read. + * @param <T> object class type. + * @param obj data object. + * @param objClass object class type. + * @throws IOException occurred while deserializing the byte content. + * @return deserialized object. + */ public static<T> T deserialize(Configuration conf, DataInput in , T obj , Class<T> objClass) throws IOException { SerializationFactory serializationFactory = new SerializationFactory(getOrCreateConf(conf)); @@ -230,10 +295,18 @@ public class IOUtils { } } - /** Deserializes the object in the given datainput using + /** + * Deserializes the object in the given data input using * available Hadoop serializations. - * @throws IOException - * @throws ClassNotFoundException */ + * + * @param conf Hadoop conf. + * @param in data input stream where serialized content is read. + * @param <T> object class type. + * @param obj data object. + * @throws IOException occurred while deserializing the byte content. + * @throws ClassNotFoundException class definition cannot be found for given class name. + * @return deserialized object. + */ @SuppressWarnings("unchecked") public static<T> T deserialize(Configuration conf, DataInput in , T obj) throws IOException, ClassNotFoundException { @@ -242,10 +315,18 @@ public class IOUtils { return deserialize(conf, in, obj, c); } - /** Deserializes the object in the given datainput using + /** + * Deserializes the object in the given data input using * available Hadoop serializations. - * @throws IOException - * @throws ClassNotFoundException */ + * + * @param conf Hadoop conf. + * @param in serialized byte array of object. + * @param <T> object class type. + * @param obj data object. + * @throws IOException occurred while deserializing the byte content. + * @throws ClassNotFoundException class definition cannot be found for given class name. + * @return deserialized object. + */ public static<T> T deserialize(Configuration conf, byte[] in , T obj) throws IOException, ClassNotFoundException { try (DataInputBuffer buffer = new DataInputBuffer()) { @@ -256,6 +337,14 @@ public class IOUtils { /** * Deserializes the field object using the datumReader. + * + * @param is data input stream. + * @param datumReader AVRO datum reader associated schema. + * @param <T> field class type. + * @param <K> key class type. + * @param object data field object. + * @return deserialized field object. + * @throws IOException while deserializing the byte content. */ public static<K, T extends SpecificRecord> T deserialize(InputStream is, SpecificDatumReader<T> datumReader, T object) @@ -266,6 +355,14 @@ public class IOUtils { /** * Deserializes the field object using the datumReader. + * + * @param bytes serialized byte array of field. + * @param datumReader AVRO datum reader associated schema. + * @param <T> field class type. + * @param <K> key class type. + * @param object data field object. + * @return deserialized field object. + * @throws IOException while deserializing the byte content. */ public static<K, T extends SpecificRecord> T deserialize(byte[] bytes, SpecificDatumReader<T> datumReader, T object) @@ -276,6 +373,14 @@ public class IOUtils { /** * Deserializes the field object using the datumReader. + * + * @param bytes serialized byte array of field. + * @param datumReader AVRO datum reader associated schema. + * @param object data field object. + * @param <T> field class type. + * @param <K> key class type. + * @return deserialized field object. + * @throws IOException while deserializing the byte content. */ public static<K, T> T deserialize(byte[] bytes, SpecificDatumReader<T> datumReader, T object) @@ -287,9 +392,10 @@ public class IOUtils { /** * Writes a byte[] to the output, representing whether each given field is null * or not. A Vint and ceil( fields.length / 8 ) bytes are written to the output. - * @param out the output to write to - * @param fields the fields to check for null - * @see #readNullFieldsInfo(DataInput) + * + * @param out the output to write to. + * @param fields the fields to check for null. @see #readNullFieldsInfo(DataInput). + * @throws IOException when writing the data to the stream. */ public static void writeNullFieldsInfo(DataOutput out, Object ... fields) throws IOException { @@ -306,8 +412,10 @@ public class IOUtils { /** * Reads the data written by {@link #writeNullFieldsInfo(DataOutput, Object...)} * and returns a boolean array representing whether each field is null or not. - * @param in the input to read from + * + * @param in the input to read from. * @return a boolean[] representing whether each field is null or not. + * @throws IOException when value is too long to fit in integer. */ public static boolean[] readNullFieldsInfo(DataInput in) throws IOException { return readBoolArray(in); @@ -315,6 +423,10 @@ public class IOUtils { /** * Writes a boolean[] to the output. + * + * @param out the output to write to. + * @param boolArray boolean array. + * @throws IOException when writing the data to the stream. */ public static void writeBoolArray(DataOutput out, boolean[] boolArray) throws IOException { @@ -345,8 +457,11 @@ public class IOUtils { } /** - * Reads a boolean[] from input - * @throws IOException + * Reads a boolean[] from input. + * + * @param in data input stream to read values. + * @return boolean array. + * @throws IOException when value too long to fit in integer. */ public static boolean[] readBoolArray(DataInput in) throws IOException { int length = WritableUtils.readVInt(in); @@ -366,6 +481,10 @@ public class IOUtils { /** * Writes a boolean[] to the output. + * + * @param out encoder instance which wraps the output stream where data is written. + * @param boolArray boolean array. + * @throws IOException when failed writing the data to the stream. */ public static void writeBoolArray(Encoder out, boolean[] boolArray) throws IOException { @@ -401,8 +520,11 @@ public class IOUtils { } /** - * Reads a boolean[] from input - * @throws IOException + * Reads a boolean[] from input. + * + * @param in decoder instance which wraps the input stream where data is read. + * @return boolean array. + * @throws IOException when failed reading the data from stream. */ public static boolean[] readBoolArray(Decoder in) throws IOException { @@ -427,9 +549,10 @@ public class IOUtils { /** * Writes the String array to the given DataOutput. - * @param out the data output to write to - * @param arr the array to write - * @see #readStringArray(DataInput) + * + * @param out the data output to write to. + * @param arr the array to write. @see #readStringArray(DataInput). + * @throws IOException when failed writing the data to output stream. */ public static void writeStringArray(DataOutput out, String[] arr) throws IOException { @@ -442,8 +565,10 @@ public class IOUtils { /** * Reads and returns a String array that is written by * {@link #writeStringArray(DataOutput, String[])}. - * @param in the data input to read from - * @return read String[] + * + * @param in the data input to read from. + * @return read String[]. + * @throws IOException when failed reading the data from stream. */ public static String[] readStringArray(DataInput in) throws IOException { int len = WritableUtils.readVInt(in); @@ -455,10 +580,13 @@ public class IOUtils { } /** - * Stores the given object in the configuration under the given dataKey - * @param obj the object to store - * @param conf the configuration to store the object into - * @param dataKey the key to store the data + * Stores the given object in the configuration under the given dataKey. + * + * @param obj the object to store. + * @param conf the configuration to store the object into. + * @param dataKey the key to store the data. + * @param <T> the given object class type. + * @throws IOException when failed storing the given data in Hadoop conf. */ public static<T> void storeToConf(T obj, Configuration conf, String dataKey) throws IOException { @@ -470,9 +598,12 @@ public class IOUtils { /** * Loads the object stored by {@link #storeToConf(Object, Configuration, String)} * method from the configuration under the given dataKey. - * @param conf the configuration to read from - * @param dataKey the key to get the data from - * @return the store object + * + * @param conf the configuration to read from. + * @param dataKey the key to get the data from. + * @param <T> the given object class type. + * @return the store object. + * @throws IOException when failed retrieving the data given key from Hadoop conf. */ @SuppressWarnings("unchecked") public static<T> T loadFromConf(Configuration conf, String dataKey) @@ -488,7 +619,10 @@ public class IOUtils { } /** - * Copies the contents of the buffers into a single byte[] + * Copies the contents of the buffers into a single byte[]. + * + * @param buffers input buffers to be merged. + * @return merged byte array. */ //TODO: not tested public static byte[] getAsBytes(List<ByteBuffer> buffers) { @@ -511,7 +645,11 @@ public class IOUtils { } /** - * Reads until the end of the input stream, and returns the contents as a byte[] + * Reads until the end of the input stream, and returns the contents as a byte[]. + * + * @param in input stream where the data is read. + * @return byte array of read data from the stream. + * @throws IOException when failed reading the data from input stream. */ public static byte[] readFully(InputStream in) throws IOException { List<ByteBuffer> buffers = new ArrayList<>(4); http://git-wip-us.apache.org/repos/asf/gora/blob/d5d673cd/gora-core/src/main/java/org/apache/gora/util/NodeWalker.java ---------------------------------------------------------------------- diff --git a/gora-core/src/main/java/org/apache/gora/util/NodeWalker.java b/gora-core/src/main/java/org/apache/gora/util/NodeWalker.java index 216e658..5241e5b 100644 --- a/gora-core/src/main/java/org/apache/gora/util/NodeWalker.java +++ b/gora-core/src/main/java/org/apache/gora/util/NodeWalker.java @@ -42,7 +42,7 @@ public class NodeWalker { /** * Starts the <code>Node</code> tree from the root node. * - * @param rootNode + * @param rootNode reference for noot node of the DOM tree. */ public NodeWalker(Node rootNode) { @@ -105,6 +105,8 @@ public class NodeWalker { /** * Returns true if there are more nodes on the current stack. + * + * @return node size. */ public boolean hasNext() { return (nodes.size() > 0); http://git-wip-us.apache.org/repos/asf/gora/blob/d5d673cd/gora-core/src/main/java/org/apache/gora/util/ReflectionUtils.java ---------------------------------------------------------------------- diff --git a/gora-core/src/main/java/org/apache/gora/util/ReflectionUtils.java b/gora-core/src/main/java/org/apache/gora/util/ReflectionUtils.java index bf3dc32..76560e7 100644 --- a/gora-core/src/main/java/org/apache/gora/util/ReflectionUtils.java +++ b/gora-core/src/main/java/org/apache/gora/util/ReflectionUtils.java @@ -33,6 +33,13 @@ public class ReflectionUtils { /** * Returns the empty argument constructor of the class. + * + * @param clazz the class reference of given type <code>T</code>. + * @param <T> class type variable. + * @return constructor for the given class type <code>T</code>. + * @throws SecurityException if the caller's class loader is not the same as the + * class loader of above class. + * @throws NoSuchMethodException default construct cannot by found for given class type. */ public static<T> Constructor<T> getConstructor(Class<T> clazz) throws SecurityException, NoSuchMethodException { @@ -46,6 +53,12 @@ public class ReflectionUtils { /** * Returns whether the class defines an empty argument constructor. + * + * @param clazz class reference of given type <code>T</code>. + * @return boolean indicating constructor for the given class type <code>T</code> exist. + * @throws SecurityException if the caller's class loader is not the same as the + * class loader of above class. + * @throws NoSuchMethodException default construct cannot by found for given class type. */ public static boolean hasConstructor(Class<?> clazz) throws SecurityException, NoSuchMethodException { @@ -66,8 +79,18 @@ public class ReflectionUtils { /** * Constructs a new instance of the class using the no-arg constructor. - * @param clazz the class of the object - * @return a new instance of the object + * + * @param clazz the class of the object. + * @param <T> class type variable. + * @return a new instance of the object. + * @throws SecurityException if the caller's class loader is not the same as the + * class loader of above class. + * @throws IllegalArgumentException this will not be thrown since <code>field.get(obj)</code> passing obj is null + * since the field is a static class level variable inside the class. + * @throws IllegalAccessException if the field is inaccessible due to java language access control. + * @throws InstantiationException could not be instantiated from the given constructor. + * @throws NoSuchMethodException default construct cannot by found for given class type. + * @throws InvocationTargetException if the underlying constructor throws an exception. */ public static <T> T newInstance(Class<T> clazz) throws InstantiationException, IllegalAccessException, @@ -81,8 +104,18 @@ public class ReflectionUtils { /** * Constructs a new instance of the class using the no-arg constructor. - * @param classStr the class name of the object - * @return a new instance of the object + * + * @param classStr the class name of the object. + * @return a new instance of the object. + * @throws SecurityException if the caller's class loader is not the same as the + * class loader of above class. + * @throws IllegalArgumentException this will not be thrown since <code>field.get(obj)</code> passing obj is null. + * since the field is a static class level variable inside the class. + * @throws IllegalAccessException if the field is inaccessible due to java language access control. + * @throws ClassNotFoundException class definition cannot be found for the class type. + * @throws InstantiationException could not be instantiated from the given constructor. + * @throws NoSuchMethodException default construct cannot by found for given class type. + * @throws InvocationTargetException if the underlying constructor throws an exception. */ public static Object newInstance(String classStr) throws InstantiationException, IllegalAccessException, @@ -96,7 +129,17 @@ public class ReflectionUtils { } /** - * Returns the value of a named static field + * Returns the value of a named static field. + * + * @param clazz the class of the object. + * @param fieldName field name of the instance which value is required. + * @return a new instance of the object. + * @throws SecurityException if the caller's class loader is not the same as the + * class loader of above class. + * @throws NoSuchFieldException if a field with the specified name is not found. + * @throws IllegalArgumentException this will not be thrown since <code>field.get(obj)</code> passing obj is null + * since the field is a static class level variable inside the class. + * @throws IllegalAccessException if the field is inaccessible due to java language access control. */ public static Object getStaticField(Class<?> clazz, String fieldName) throws IllegalArgumentException, SecurityException, http://git-wip-us.apache.org/repos/asf/gora/blob/d5d673cd/gora-core/src/main/java/org/apache/gora/util/StringUtils.java ---------------------------------------------------------------------- diff --git a/gora-core/src/main/java/org/apache/gora/util/StringUtils.java b/gora-core/src/main/java/org/apache/gora/util/StringUtils.java index 9a38d8b..57e3ff8 100644 --- a/gora-core/src/main/java/org/apache/gora/util/StringUtils.java +++ b/gora-core/src/main/java/org/apache/gora/util/StringUtils.java @@ -32,6 +32,10 @@ public class StringUtils { /** * Joins the two given arrays, removing dup elements. + * + * @param arr1 first string array. + * @param arr2 second string array. + * @return joined array. */ public static String[] joinStringArrays(String[] arr1, String... arr2) { HashSet<String> set = new HashSet<>(); @@ -67,7 +71,12 @@ public class StringUtils { return builder; } - /** helper for string null and empty checking*/ + /** + * Helper for string null and empty checking + * + * @param str input string. + * @return True or False indicating not null condition. + */ public static boolean is(String str) { return str != null && str.length() > 0; } @@ -77,6 +86,7 @@ public class StringUtils { * Returns the power set from the given set by using a binary counter * Example: S = {a,b,c} * P(S) = {[], [c], [b], [b, c], [a], [a, c], [a, b], [a, b, c]} + * * @param set String[] * @return LinkedHashSet */ @@ -117,11 +127,12 @@ public class StringUtils { /** * Converts the given integer to a String representing a binary number - * with the specified number of digits - * For example when using 4 digits the binary 1 is 0001 - * @param binary int - * @param digits int - * @return String + * with the specified number of digits. + * For example when using 4 digits the binary 1 is 0001. + * + * @param binary int. + * @param digits int. + * @return String. */ private static String intToBinary(int binary, int digits) { String temp = Integer.toBinaryString(binary); @@ -142,6 +153,9 @@ public class StringUtils { /** * Returns the name of the class without the package name. + * + * @param clazz Class type instance which name is to be returned. + * @return class name string. */ public static String getClassname(Class<?> clazz) { return getClassname(clazz.getName()); @@ -149,6 +163,9 @@ public class StringUtils { /** * Returns the name of the class without the package name. + * + * @param classname class name including package as string. + * @return class name as string. */ public static String getClassname(String classname) { String[] parts = classname.split("\\."); http://git-wip-us.apache.org/repos/asf/gora/blob/d5d673cd/gora-core/src/main/java/org/apache/gora/util/VersionInfo.java ---------------------------------------------------------------------- diff --git a/gora-core/src/main/java/org/apache/gora/util/VersionInfo.java b/gora-core/src/main/java/org/apache/gora/util/VersionInfo.java index 71285c5..4c59eed 100644 --- a/gora-core/src/main/java/org/apache/gora/util/VersionInfo.java +++ b/gora-core/src/main/java/org/apache/gora/util/VersionInfo.java @@ -40,7 +40,8 @@ public class VersionInfo { /** * Get the meta-data for the Gora package. - * @return + * + * @return package instance. */ static Package getPackage() { return myPackage; @@ -48,15 +49,17 @@ public class VersionInfo { /** * Get the Gora version. - * @return the Gora version string, eg. "X.Y" + * + * @return the Gora version string, eg. "X.Y". */ public static String getVersion() { return version != null ? version.version() : "Unknown"; } /** - * Get the subversion revision number for the root directory - * @return the revision number, eg. "451451" + * Get the subversion revision number for the root directory. + * + * @return the revision number, eg. "451451". */ public static String getRevision() { return version != null ? version.revision() : "Unknown"; @@ -64,6 +67,7 @@ public class VersionInfo { /** * The date that Gora was compiled. + * * @return the compilation date in unix date format */ public static String getDate() { @@ -72,7 +76,8 @@ public class VersionInfo { /** * The user that compiled Gora. - * @return the username of the user + * + * @return the username of the user. */ public static String getUser() { return version != null ? version.user() : "Unknown"; @@ -80,6 +85,8 @@ public class VersionInfo { /** * Get the subversion URL for the root Gora directory. + * + * @return subversion URL. */ public static String getUrl() { return version != null ? version.url() : "Unknown"; @@ -88,14 +95,18 @@ public class VersionInfo { /** * Get the checksum of the source files from which Gora was * built. - **/ + * + * @return checksum of the source files. + */ public static String getSrcChecksum() { return version != null ? version.srcChecksum() : "Unknown"; } /** * Returns the buildVersion which includes version, - * revision, user and date. + * revision, user and date. + * + * @return build version. */ public static String getBuildVersion(){ return VersionInfo.getVersion() + http://git-wip-us.apache.org/repos/asf/gora/blob/d5d673cd/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index 3ce77d5..c8990dc 100644 --- a/pom.xml +++ b/pom.xml @@ -471,6 +471,37 @@ <fork>true</fork> </configuration> </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <version>${maven-javadoc-plugin.version}</version> + <configuration> + <excludePackageNames>org.apache.gora.tutorial.log.generated;org.apache.gora.goraci.generated</excludePackageNames> + </configuration> + <executions> + <execution> + <id>attach-javadocs</id> + <goals> + <goal>jar</goal> + </goals> + <configuration> + <quiet>true</quiet> + <archive> + <manifest> + <addDefaultImplementationEntries>true</addDefaultImplementationEntries> + <addDefaultSpecificationEntries>true</addDefaultSpecificationEntries> + </manifest> + <manifestEntries> + <Implementation-Build>${implementation.build}</Implementation-Build> + <Implementation-Build-Date>${maven.build.timestamp}</Implementation-Build-Date> + <X-Compile-Source-JDK>${javac.src.version}</X-Compile-Source-JDK> + <X-Compile-Target-JDK>${javac.target.version}</X-Compile-Target-JDK> + </manifestEntries> + </archive> + </configuration> + </execution> + </executions> + </plugin> </plugins> </pluginManagement> <plugins> @@ -615,6 +646,9 @@ <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>${maven-javadoc-plugin.version}</version> + <configuration> + <excludePackageNames>org.apache.gora.tutorial.log.generated;org.apache.gora.goraci.generated</excludePackageNames> + </configuration> <executions> <execution> <id>attach-javadocs</id>
