Index: src/java/org/apache/hcatalog/data/schema/HCatSchema.java =================================================================== --- src/java/org/apache/hcatalog/data/schema/HCatSchema.java (revision 1356106) +++ src/java/org/apache/hcatalog/data/schema/HCatSchema.java (working copy) @@ -27,7 +27,7 @@ import org.apache.hcatalog.common.HCatException; /** - * HCatSchema. This class is NOT thread-safe. + * The HCatalog schema class. This class is NOT thread-safe. */ public class HCatSchema implements Serializable{ @@ -39,10 +39,14 @@ private final List fieldNames; /** + * Instantiate an HCatSchema with a list of field schemas. * - * @param fieldSchemas is now owned by HCatSchema. Any subsequent modifications - * on fieldSchemas won't get reflected in HCatSchema. Each fieldSchema's name - * in the list must be unique, otherwise throws IllegalArgumentException. + * @param fieldSchemas + * is now owned by HCatSchema. Any subsequent modifications + * on fieldSchemas won't get reflected in HCatSchema. Each + * fieldSchema's name in the list must be unique, otherwise + * throws IllegalArgumentException. + * @throws IllegalArgumentException */ public HCatSchema(final List fieldSchemas){ this.fieldSchemas = new ArrayList(fieldSchemas); @@ -63,6 +67,12 @@ } } + /** + * + * @param hfs + * an HCatalog field schema + * @throws HCatException + */ public void append(final HCatFieldSchema hfs) throws HCatException{ if(hfs == null) throw new HCatException("Attempt to append null HCatFieldSchema in HCatSchema."); @@ -80,6 +90,8 @@ /** * Users are not allowed to modify the list directly, since HCatSchema * maintains internal state. Use append/remove to modify the schema. + * + * @return a list of field schemas */ public List getFields(){ return Collections.unmodifiableList(this.fieldSchemas); @@ -87,29 +99,57 @@ /** * @param fieldName - * @return the index of field named fieldName in Schema. If field is not - * present, returns null. + * the field name + * @return the index of a field named fieldName in Schema. If the field + * is not present, returns null. */ public Integer getPosition(String fieldName) { return fieldPositionMap.get(fieldName); } + /** + * + * @param fieldName + * the field name + * @return the schema for the specified field + * @throws HCatException + */ public HCatFieldSchema get(String fieldName) throws HCatException { return get(getPosition(fieldName)); } + /** + * + * @return a list of field names + */ public List getFieldNames(){ return this.fieldNames; } + /** + * + * @param position + * the field location + * @return the schema for the specified position + */ public HCatFieldSchema get(int position) { return fieldSchemas.get(position); } + /** + * + * @return the size + */ public int size(){ return fieldSchemas.size(); } + /** + * + * @param hcatFieldSchema + * the field schema to remove + * @throws HCatException + */ public void remove(final HCatFieldSchema hcatFieldSchema) throws HCatException { if(!fieldSchemas.contains(hcatFieldSchema)){ @@ -140,6 +180,10 @@ return sb.toString(); } + /** + * + * @return the schema as a String + */ public String getSchemaAsTypeString(){ boolean first = true; StringBuilder sb = new StringBuilder(); Index: src/java/org/apache/hcatalog/data/schema/HCatSchemaUtils.java =================================================================== --- src/java/org/apache/hcatalog/data/schema/HCatSchemaUtils.java (revision 1356106) +++ src/java/org/apache/hcatalog/data/schema/HCatSchemaUtils.java (working copy) @@ -102,8 +102,10 @@ /** - * Convert a HCatFieldSchema to a FieldSchema - * @param fs FieldSchema to convert + * Convert a FieldSchema to an HCatFieldSchema. + * + * @param fs + * FieldSchema to convert * @return HCatFieldSchema representation of FieldSchema * @throws HCatException */ Index: src/java/org/apache/hcatalog/data/schema/HCatFieldSchema.java =================================================================== --- src/java/org/apache/hcatalog/data/schema/HCatFieldSchema.java (revision 1356106) +++ src/java/org/apache/hcatalog/data/schema/HCatFieldSchema.java (working copy) @@ -89,6 +89,7 @@ /** * Returns type of the field + * * @return type of the field */ public Type getType(){ @@ -97,6 +98,7 @@ /** * Returns category of the field + * * @return category of the field */ public Category getCategory(){ @@ -105,6 +107,7 @@ /** * Returns name of the field + * * @return name of the field */ public String getName(){ @@ -116,10 +119,14 @@ } /** - * Constructor constructing a primitive datatype HCatFieldSchema - * @param fieldName Name of the primitive field - * @param type Type of the primitive field - * @throws HCatException if call made on non-primitive types + * Constructor for constructing a primitive datatype HCatFieldSchema. + * + * @param fieldName + * Name of the primitive field + * @param type + * Type of the primitive field + * @throws HCatException + * if call made on non-primitive types */ public HCatFieldSchema(String fieldName, Type type, String comment) throws HCatException { assertTypeInCategory(type,Category.PRIMITIVE,fieldName); @@ -130,11 +137,18 @@ } /** - * Constructor for constructing a ARRAY type or STRUCT type HCatFieldSchema, passing type and subschema - * @param fieldName Name of the array or struct field - * @param type Type of the field - either Type.ARRAY or Type.STRUCT - * @param subSchema - subschema of the struct, or element schema of the elements in the array - * @throws HCatException if call made on Primitive or Map types + * Constructor for constructing an ARRAY type or STRUCT type + * HCatFieldSchema, passing type and subschema. + * + * @param fieldName + * Name of the array or struct field + * @param type + * Type of the field - either Type.ARRAY or Type.STRUCT + * @param subSchema + * subschema of the struct, or element schema of the elements + * in the array + * @throws HCatException + * if call made on Primitive or Map type */ public HCatFieldSchema(String fieldName, Type type, HCatSchema subSchema,String comment) throws HCatException{ assertTypeNotInCategory(type,Category.PRIMITIVE); @@ -154,12 +168,19 @@ } /** - * Constructor for constructing a MAP type HCatFieldSchema, passing type of key and value - * @param fieldName Name of the array or struct field - * @param type Type of the field - must be Type.MAP - * @param mapKeyType - key type of the Map - * @param mapValueSchema - subschema of the value of the Map - * @throws HCatException if call made on non-Map types + * Constructor for constructing a MAP type HCatFieldSchema, passing type + * of key and value. + * + * @param fieldName + * Name of the array or struct field + * @param type + * Type of the field - must be Type.MAP + * @param mapKeyType + * key type of the Map + * @param mapValueSchema + * subschema of the value of the Map + * @throws HCatException + * if call made on non-Map types */ public HCatFieldSchema(String fieldName, Type type, Type mapKeyType, HCatSchema mapValueSchema, String comment) throws HCatException{ assertTypeInCategory(type,Category.MAP, fieldName); Index: src/java/org/apache/hcatalog/data/HCatRecordable.java =================================================================== --- src/java/org/apache/hcatalog/data/HCatRecordable.java (revision 1356106) +++ src/java/org/apache/hcatalog/data/HCatRecordable.java (working copy) @@ -23,33 +23,41 @@ import org.apache.hcatalog.common.HCatException; /** - * Interface that determines whether we can implement a HCatRecord on top of it + * Interface that determines whether we can implement an HCatRecord + * on top of it. */ public interface HCatRecordable extends Writable { /** * Gets the field at the specified index. - * @param fieldNum the field number + * + * @param fieldNum + * the field number * @return the object at the specified index * @throws HCatException */ Object get(int fieldNum); /** - * Gets all the fields of the hcat record. + * Gets all the fields of the HCat record. + * * @return the list of fields */ List getAll(); /** * Sets the field at the specified index. - * @param fieldNum the field number - * @param value the value to set + * + * @param fieldNum + * the field number + * @param value + * the value to set */ void set(int fieldNum, Object value); /** - * Gets the size of the hcat record. + * Gets the size of the HCat record. + * * @return the size */ int size(); Index: src/java/org/apache/hcatalog/data/transfer/state/StateProvider.java =================================================================== --- src/java/org/apache/hcatalog/data/transfer/state/StateProvider.java (revision 1356106) +++ src/java/org/apache/hcatalog/data/transfer/state/StateProvider.java (working copy) @@ -22,15 +22,15 @@ import org.apache.hadoop.mapred.TaskTracker; /** - * If external system wants to communicate any state to slaves, they can do so - * via this interface. One example of this in case of Map-Reduce is ids assigned - * by {@link JobTracker} to {@link TaskTracker} + * If an external system wants to communicate any state to slaves, it can do so + * via this interface. One example of this in the case of Map-Reduce is ids + * assigned by {@link JobTracker} to {@link TaskTracker}. */ public interface StateProvider { /** - * This method should return id assigned to slave node. - * + * This method should return the identifier assigned to a slave node. + * * @return id */ public int getId(); Index: src/java/org/apache/hcatalog/data/transfer/WriterContext.java =================================================================== --- src/java/org/apache/hcatalog/data/transfer/WriterContext.java (revision 1356106) +++ src/java/org/apache/hcatalog/data/transfer/WriterContext.java (working copy) @@ -27,10 +27,10 @@ import org.apache.hadoop.conf.Configuration; /** - * This contains information obtained at master node to help prepare slave nodes - * for writer. This class implements {@link Externalizable} so it can be - * serialized using standard java mechanisms. Master should serialize it and - * make it available to slaves to prepare for writes. + * This contains information obtained at the master node to help prepare slave + * nodes for writing. This class implements {@link Externalizable} so it can be + * serialized using standard Java mechanisms. The master should serialize it + * and make it available to slaves to prepare for writes. */ public class WriterContext implements Externalizable, Configurable { @@ -41,21 +41,50 @@ conf = new Configuration(); } + /** + * Get the configuration used by this writer. + * + * @return the writer's configuration + */ @Override public Configuration getConf() { return conf; } + /** + * Set the configuration to be used by this writer. + * + * @param config + * the configuration to set + */ @Override public void setConf(final Configuration config) { this.conf = config; } + /** + * Write the configuration to an external location. + * + * @param out + * the stream to write the output to + * @throws IOException + * if I/O errors occur + */ @Override public void writeExternal(ObjectOutput out) throws IOException { conf.write(out); } + /** + * Restore the contents of this WriterContext with data read from an + * external location. + * + * @param in + * the stream to read data from in order to restore writer context + * @throws IOException + * if I/O errors occur + * @throws ClassNotFoundException + */ @Override public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException { Index: src/java/org/apache/hcatalog/data/transfer/EntityBase.java =================================================================== --- src/java/org/apache/hcatalog/data/transfer/EntityBase.java (revision 1356106) +++ src/java/org/apache/hcatalog/data/transfer/EntityBase.java (working copy) @@ -40,18 +40,38 @@ abstract static class Entity extends EntityBase { + /** + * Get the region. + * + * @return the name of the region + */ public String getRegion() { return region; } + /** + * Get the table name. + * + * @return the table name + */ public String getTableName() { return tableName; } + /** + * Get the database name. + * + * @return the database name + */ public String getDbName() { return dbName; } + /** + * Get the partition key values. + * + * @return a Map of partition key values + */ public Map getPartitionKVs() { return partitionKVs; } Index: src/java/org/apache/hcatalog/data/transfer/ReaderContext.java =================================================================== --- src/java/org/apache/hcatalog/data/transfer/ReaderContext.java (revision 1356106) +++ src/java/org/apache/hcatalog/data/transfer/ReaderContext.java (working copy) @@ -33,7 +33,7 @@ /** * This class will contain information of different {@link InputSplit} obtained * at master node and configuration. This class implements - * {@link Externalizable} so it can be serialized using standard java + * {@link Externalizable} so it can be serialized using standard Java * mechanisms. */ public class ReaderContext implements Externalizable, Configurable { @@ -47,24 +47,54 @@ this.conf = new Configuration(); } + /** + * Set the input splits to be used by this reader. + * + * @param splits + * a List of input splits + */ public void setInputSplits(final List splits) { this.splits = splits; } + /** + * Get the input splits used by this reader. + * + * @return a list of input splits + */ public List getSplits() { return splits; } + /** + * Get the configuration used by this reader. + * + * @return the reader's configuration + */ @Override public Configuration getConf() { return conf; } + /** + * Set the configuration to be used by this reader. + * + * @param config + * the configuration to set + */ @Override public void setConf(final Configuration config) { conf = config; } + /** + * Write the input splits used by this reader to an external location. + * + * @param out + * the stream to write the output to + * @throws IOException + * if I/O errors occur + */ @Override public void writeExternal(ObjectOutput out) throws IOException { conf.write(out); @@ -74,6 +104,16 @@ } } + /** + * Read an external list of input splits to restore the contents of this + * ReaderContext. + * + * @param in + * the stream to read data from in order to restore reader context + * @throws IOException + * if I/O errors occur + * @throws ClassNotFoundException + */ @Override public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException { Index: src/java/org/apache/hcatalog/data/transfer/WriteEntity.java =================================================================== --- src/java/org/apache/hcatalog/data/transfer/WriteEntity.java (revision 1356106) +++ src/java/org/apache/hcatalog/data/transfer/WriteEntity.java (working copy) @@ -20,13 +20,16 @@ import java.util.Map; +/** + * This class is used on the master node to instantiate an {@link HCatWriter} + * or an HCatOutputFormatWriter. + */ public class WriteEntity extends EntityBase.Entity { /** - * Don't instantiate {@link WriteEntity} directly. Use, {@link Builder} to + * Don't instantiate {@link WriteEntity} directly. Use {@link Builder} to * build {@link WriteEntity}. */ - private WriteEntity() { // Not allowed. } @@ -39,33 +42,59 @@ } /** - * This class should be used to build {@link WriteEntity}. It follows builder - * pattern, letting you build your {@link WriteEntity} with whatever level of - * detail you want. - * + * This class should be used to build a {@link WriteEntity}. It follows + * the builder pattern, letting you build your {@link WriteEntity} with + * whatever level of detail you want. */ public static class Builder extends EntityBase { + /** + * Build a {@link WriteEntity} specifying the region. + * + * @param region + * the region for this {@link WriteEntity} + */ public Builder withRegion(final String region) { this.region = region; return this; } + /** + * Build a {@link WriteEntity} specifying the database. + * + * @param dbName + * the name of the database + */ public Builder withDatabase(final String dbName) { this.dbName = dbName; return this; } + /** + * Build a {@link WriteEntity} specifying the table name. + * + * @param tblName + * the name of the table + */ public Builder withTable(final String tblName) { this.tableName = tblName; return this; } + /** + * Build a {@link WriteEntity} specifying the partition key values. + * + * @param partKVs + * a Map of partition key values + */ public Builder withPartition(final Map partKVs) { this.partitionKVs = partKVs; return this; } + /** + * Build a {@link WriteEntity} without specifying any parameters. + */ public WriteEntity build() { return new WriteEntity(this); } Index: src/java/org/apache/hcatalog/data/transfer/ReadEntity.java =================================================================== --- src/java/org/apache/hcatalog/data/transfer/ReadEntity.java (revision 1356106) +++ src/java/org/apache/hcatalog/data/transfer/ReadEntity.java (working copy) @@ -20,14 +20,17 @@ import java.util.Map; +/** + * This class is used on the master node to instantiate an {@link HCatReader} + * or an HCatInputFormatReader. + */ public class ReadEntity extends EntityBase.Entity { private String filterString; /** - * Don't instantiate {@link ReadEntity} directly. Use, + * Don't instantiate {@link ReadEntity} directly. Use * {@link ReadEntity.Builder} instead. - * */ private ReadEntity() { // Not allowed @@ -42,45 +45,83 @@ this.filterString = builder.filterString; } + /** + * Get the filter string. + * + * @return the filter string + */ public String getFilterString() { return this.filterString; } /** - * This class should be used to build {@link ReadEntity}. It follows builder - * pattern, letting you build your {@link ReadEntity} with whatever level of - * detail you want. - * + * This class should be used to build a {@link ReadEntity}. It follows the + * builder pattern, letting you build your {@link ReadEntity} with whatever + * level of detail you want. + * */ public static class Builder extends EntityBase { private String filterString; + /** + * Build a {@link ReadEntity} specifying the region. + * + * @param region + * the region for this {@link ReadEntity} + */ public Builder withRegion(final String region) { this.region = region; return this; } + /** + * Build a {@link ReadEntity} specifying the database. + * + * @param dbName + * the name of the database + */ public Builder withDatabase(final String dbName) { this.dbName = dbName; return this; } + /** + * Build a {@link ReadEntity} specifying the table name. + * + * @param tblName + * the name of the table + */ public Builder withTable(final String tblName) { this.tableName = tblName; return this; } + /** + * Build a {@link ReadEntity} specifying the partition key values. + * + * @param partKVs + * a Map of partition key values + */ public Builder withPartition(final Map partKVs) { this.partitionKVs = partKVs; return this; } + /** + * Build a {@link ReadEntity} specifying a filter string. + * + * @param filterString + * the filter for this {@link ReadEntity} + */ public Builder withFilter(String filterString) { this.filterString = filterString; return this; } + /** + * Build a {@link ReadEntity} without specifying any parameters. + */ public ReadEntity build() { return new ReadEntity(this); } Index: src/java/org/apache/hcatalog/data/transfer/HCatWriter.java =================================================================== --- src/java/org/apache/hcatalog/data/transfer/HCatWriter.java (revision 1356106) +++ src/java/org/apache/hcatalog/data/transfer/HCatWriter.java (working copy) @@ -30,7 +30,7 @@ /** * This abstraction is internal to HCatalog. This is to facilitate writing to * HCatalog from external systems. Don't try to instantiate this directly. - * Instead, use {@link DataTransferFactory} + * Instead, use {@link DataTransferFactory}. */ public abstract class HCatWriter { @@ -50,11 +50,11 @@ public abstract WriterContext prepareWrite() throws HCatException; /** - * This method should be used at slave needs to perform writes. + * This method should be used at slave nodes to perform writes. * * @param recordItr * {@link Iterator} records to be written into HCatalog. - * @throws {@link HCatException} + * @throws HCatException */ public abstract void write(final Iterator recordItr) throws HCatException; @@ -63,7 +63,7 @@ * This method should be called at master node. Primary purpose of this is to * do metadata commit. * - * @throws {@link HCatException} + * @throws HCatException */ public abstract void commit(final WriterContext context) throws HCatException; @@ -71,12 +71,12 @@ * This method should be called at master node. Primary purpose of this is to * do cleanups in case of failures. * - * @throws {@link HCatException} * + * @throws HCatException */ public abstract void abort(final WriterContext context) throws HCatException; /** - * This constructor will be used at master node + * This constructor will be used at master node. * * @param we * WriteEntity defines where in storage records should be written to. @@ -93,6 +93,10 @@ * This constructor will be used at slave nodes. * * @param config + * Any configuration which external system wants to communicate + to slave nodes. + * @param sp + * {@link StateProvider} for node identification */ protected HCatWriter(final Configuration config, final StateProvider sp) { this.conf = config; Index: src/java/org/apache/hcatalog/data/HCatRecord.java =================================================================== --- src/java/org/apache/hcatalog/data/HCatRecord.java (revision 1356106) +++ src/java/org/apache/hcatalog/data/HCatRecord.java (working copy) @@ -27,8 +27,8 @@ /** * Abstract class exposing get and set semantics for basic record usage. - * Note : - * HCatRecord is designed only to be used as in-memory representation only. + * Note: + * HCatRecord is designed to be used as in-memory representation only. * Don't use it to store data on the physical device. */ public abstract class HCatRecord implements HCatRecordable {