add comments for classes/interfaces
git-svn-id: https://asterixdb.googlecode.com/svn/branches/asterix_opentype@371 eaa15691-b419-025a-1212-ee371bd00084
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/AFlatValuePointable.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/AFlatValuePointable.java
index 2416cc4..41d55b6 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/AFlatValuePointable.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/AFlatValuePointable.java
@@ -22,11 +22,16 @@
import edu.uci.ics.asterix.runtime.util.container.IElementFactory;
import edu.uci.ics.hyracks.data.std.api.IValueReference;
+/**
+ * This class is to represent a flat field, e.g., int field, string field, and
+ * so on, based on an binary representation
+ */
public class AFlatValuePointable extends AbstractVisitablePointable {
/**
* DO NOT allow to create AFlatValuePointable object arbitrarily, force to
- * use object pool based allocator
+ * use object pool based allocator. The factory is not public so that it
+ * cannot called in other places than PointableAllocator.
*/
static IElementFactory<IVisitablePointable, IAType> FACTORY = new IElementFactory<IVisitablePointable, IAType>() {
public AFlatValuePointable createElement(IAType type) {
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/AListPointable.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/AListPointable.java
index 558ec58..85b5297 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/AListPointable.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/AListPointable.java
@@ -31,6 +31,12 @@
import edu.uci.ics.asterix.runtime.util.ResettableByteArrayOutputStream;
import edu.uci.ics.asterix.runtime.util.container.IElementFactory;
+/**
+ * This class is to interpret the binary data representation of a list, one can
+ * call getItems and getItemTags to get pointable objects for items and item
+ * type tags
+ *
+ */
public class AListPointable extends AbstractVisitablePointable {
/**
@@ -43,10 +49,6 @@
}
};
- private IAType itemType;
- private ATypeTag itemTag;
- private boolean typedItemList = false;
-
private final List<IVisitablePointable> items = new ArrayList<IVisitablePointable>();
private final List<IVisitablePointable> itemTags = new ArrayList<IVisitablePointable>();
private final PointableAllocator allocator = new PointableAllocator();
@@ -55,8 +57,12 @@
private final ResettableByteArrayOutputStream dataBos = new ResettableByteArrayOutputStream();
private final DataOutputStream dataDos = new DataOutputStream(dataBos);
+ private IAType itemType;
+ private ATypeTag itemTag;
+ private boolean typedItemList = false;
+
/**
- * private constructor, to prevent constructing it
+ * private constructor, to prevent constructing it arbitrarily
*
* @param inputType
* , the input type
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/ARecordPointable.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/ARecordPointable.java
index 75a3737..8535db3 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/ARecordPointable.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/ARecordPointable.java
@@ -35,6 +35,12 @@
import edu.uci.ics.asterix.runtime.util.container.IElementFactory;
import edu.uci.ics.hyracks.api.dataflow.value.INullWriter;
+/**
+ * This class is to interpret the binary data representation of a record, one
+ * can call getFieldNames, getFieldTypeTags and getFieldValues to get pointable
+ * objects for field names, field type tags, and field values
+ *
+ */
public class ARecordPointable extends AbstractVisitablePointable {
/**
@@ -48,32 +54,33 @@
};
// access results: field names, field types, and field values
- private List<IVisitablePointable> fieldNames = new ArrayList<IVisitablePointable>();
- private List<IVisitablePointable> fieldTypeTags = new ArrayList<IVisitablePointable>();
- private List<IVisitablePointable> fieldValues = new ArrayList<IVisitablePointable>();
+ private final List<IVisitablePointable> fieldNames = new ArrayList<IVisitablePointable>();
+ private final List<IVisitablePointable> fieldTypeTags = new ArrayList<IVisitablePointable>();
+ private final List<IVisitablePointable> fieldValues = new ArrayList<IVisitablePointable>();
// pointable allocator
- private PointableAllocator allocator = new PointableAllocator();
+ private final PointableAllocator allocator = new PointableAllocator();
- private byte[] typeBuffer = new byte[32768];
- private ResettableByteArrayOutputStream typeBos = new ResettableByteArrayOutputStream();
- private DataOutputStream typeDos = new DataOutputStream(typeBos);
+ private final byte[] typeBuffer = new byte[32768];
+ private final ResettableByteArrayOutputStream typeBos = new ResettableByteArrayOutputStream();
+ private final DataOutputStream typeDos = new DataOutputStream(typeBos);
- private byte[] dataBuffer = new byte[32768];
- private ResettableByteArrayOutputStream dataBos = new ResettableByteArrayOutputStream();
- private DataOutputStream dataDos = new DataOutputStream(dataBos);
+ private final byte[] dataBuffer = new byte[32768];
+ private final ResettableByteArrayOutputStream dataBos = new ResettableByteArrayOutputStream();
+ private final DataOutputStream dataDos = new DataOutputStream(dataBos);
+
+ private final ARecordType inputRecType;
+
+ private final int numberOfSchemaFields;
+ private final int[] fieldOffsets;
+ private final IVisitablePointable nullReference = AFlatValuePointable.FACTORY.createElement(null);
private int closedPartTypeInfoSize = 0;
- private ARecordType inputRecType;
-
- private int numberOfSchemaFields;
private int offsetArrayOffset;
- private int[] fieldOffsets;
private ATypeTag typeTag;
- private IVisitablePointable nullReference = AFlatValuePointable.FACTORY.createElement(null);
/**
- * private constructor, to prevent constructing it
+ * private constructor, to prevent constructing it arbitrarily
*
* @param inputType
* , the input type
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/AbstractVisitablePointable.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/AbstractVisitablePointable.java
index 47fd7e5..6b844a0 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/AbstractVisitablePointable.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/AbstractVisitablePointable.java
@@ -18,12 +18,17 @@
import edu.uci.ics.asterix.runtime.pointables.base.IVisitablePointable;
import edu.uci.ics.hyracks.data.std.api.IValueReference;
+/**
+ * This class implements several "routine" methods in IVisitablePointable
+ * interface, so that subclasses do not need to repeat the same code
+ *
+ */
public abstract class AbstractVisitablePointable implements IVisitablePointable {
private byte[] data;
private int start;
private int len;
-
+
@Override
public byte[] getByteArray() {
return data;
@@ -45,7 +50,7 @@
this.start = start;
this.len = len;
}
-
+
@Override
public void set(IValueReference ivf) {
set(ivf.getByteArray(), ivf.getStartOffset(), ivf.getLength());
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/PointableAllocator.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/PointableAllocator.java
index 2b654db..7675a2b 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/PointableAllocator.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/PointableAllocator.java
@@ -22,6 +22,11 @@
import edu.uci.ics.asterix.runtime.util.container.IElementAllocator;
import edu.uci.ics.asterix.runtime.util.container.ListElementAllocator;
+/**
+ * This class is the ONLY place to create IVisitablePointable object instances,
+ * so that all the client code are forced to have object reuse for those
+ * IVisitablePointable objects
+ */
public class PointableAllocator {
private IElementAllocator<IVisitablePointable, IAType> flatValueAllocator = new ListElementAllocator<IVisitablePointable, IAType>(
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/base/DefaultOpenFieldType.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/base/DefaultOpenFieldType.java
index f1f54bc..0c39aa0 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/base/DefaultOpenFieldType.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/base/DefaultOpenFieldType.java
@@ -22,6 +22,13 @@
import edu.uci.ics.asterix.om.types.BuiltinType;
import edu.uci.ics.asterix.om.types.IAType;
+/**
+ * This class serves as the repository for default record type and list type
+ * fields in the open part, e.g., a "record" (nested) field in the open part is
+ * always a fully open one, and a "list" field in the open part is always a list
+ * of "ANY"
+ *
+ */
public class DefaultOpenFieldType {
// nested open field rec type
@@ -35,13 +42,13 @@
// nested open list type
public static AUnorderedListType NESTED_OPEN_AUNORDERED_LIST_TYPE = new AUnorderedListType(BuiltinType.ANY,
"nested-unordered-list");
-
- public static IAType getDefaultOpenFieldType(ATypeTag tag){
- if(tag.equals(ATypeTag.RECORD))
+
+ public static IAType getDefaultOpenFieldType(ATypeTag tag) {
+ if (tag.equals(ATypeTag.RECORD))
return NESTED_OPEN_RECORD_TYPE;
- if(tag.equals(ATypeTag.ORDEREDLIST))
+ if (tag.equals(ATypeTag.ORDEREDLIST))
return NESTED_OPEN_AORDERED_LIST_TYPE;
- if(tag.equals(ATypeTag.UNORDEREDLIST))
+ if (tag.equals(ATypeTag.UNORDEREDLIST))
return NESTED_OPEN_AUNORDERED_LIST_TYPE;
else
return null;
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/base/IVisitablePointable.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/base/IVisitablePointable.java
index b3c088b..f630e24 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/base/IVisitablePointable.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/base/IVisitablePointable.java
@@ -19,6 +19,10 @@
import edu.uci.ics.asterix.runtime.pointables.visitor.IVisitablePointableVisitor;
import edu.uci.ics.hyracks.data.std.api.IPointable;
+/**
+ * This interface extends IPointable with a visitor interface in order to ease
+ * programming for recursive record structures
+ */
public interface IVisitablePointable extends IPointable {
public <R, T> R accept(IVisitablePointableVisitor<R, T> vistor, T tag) throws AsterixException;
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/cast/ACastVisitor.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/cast/ACastVisitor.java
index 67ff67e..9d3fe73 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/cast/ACastVisitor.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/cast/ACastVisitor.java
@@ -29,13 +29,27 @@
import edu.uci.ics.asterix.runtime.pointables.visitor.IVisitablePointableVisitor;
import edu.uci.ics.hyracks.algebricks.common.utils.Triple;
+/**
+ * This class is a IVisitablePointableVisitor implementation which recursively
+ * visit a given record, list or flat value of a given type, and recursively
+ * cast it to a specified type For example,
+ *
+ * A record { "hobby": {{"music", "coding"}}, "id": "001", "name":
+ * "Person Three"} which confirms to closed type ( id: string, name: string,
+ * hobby: {{string}}? ) can be casted to a open type (id: string )
+ *
+ * Since the open/close part of a record has completely different underlying
+ * memory/storage layout, the visitor will change the layout as specified at
+ * runtime.
+ */
public class ACastVisitor implements IVisitablePointableVisitor<Void, Triple<IVisitablePointable, IAType, Boolean>> {
- private Map<IVisitablePointable, ARecordCaster> raccessorToCaster = new HashMap<IVisitablePointable, ARecordCaster>();
- private Map<IVisitablePointable, AListCaster> laccessorToCaster = new HashMap<IVisitablePointable, AListCaster>();
+ private final Map<IVisitablePointable, ARecordCaster> raccessorToCaster = new HashMap<IVisitablePointable, ARecordCaster>();
+ private final Map<IVisitablePointable, AListCaster> laccessorToCaster = new HashMap<IVisitablePointable, AListCaster>();
@Override
- public Void visit(AListPointable accessor, Triple<IVisitablePointable, IAType, Boolean> arg) throws AsterixException {
+ public Void visit(AListPointable accessor, Triple<IVisitablePointable, IAType, Boolean> arg)
+ throws AsterixException {
AListCaster caster = laccessorToCaster.get(accessor);
if (caster == null) {
caster = new AListCaster();
@@ -50,7 +64,8 @@
}
@Override
- public Void visit(ARecordPointable accessor, Triple<IVisitablePointable, IAType, Boolean> arg) throws AsterixException {
+ public Void visit(ARecordPointable accessor, Triple<IVisitablePointable, IAType, Boolean> arg)
+ throws AsterixException {
ARecordCaster caster = raccessorToCaster.get(accessor);
if (caster == null) {
caster = new ARecordCaster();
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/cast/AListCaster.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/cast/AListCaster.java
index 930bb8b..9423a0c 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/cast/AListCaster.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/cast/AListCaster.java
@@ -36,23 +36,27 @@
import edu.uci.ics.asterix.runtime.util.ResettableByteArrayOutputStream;
import edu.uci.ics.hyracks.algebricks.common.utils.Triple;
+/**
+ * This class is to do the runtime type cast for a list. It is ONLY visible to
+ * ACastVisitor, so that no other client places can call into that caster and
+ * unnecessary bugs could be prevented.
+ */
class AListCaster {
-
- private IAType reqItemType;
// pointable allocator
- private PointableAllocator allocator = new PointableAllocator();
+ private final PointableAllocator allocator = new PointableAllocator();
// for storing the cast result
- private IVisitablePointable itemTempReference = allocator.allocateEmpty();
- private Triple<IVisitablePointable, IAType, Boolean> itemVisitorArg = new Triple<IVisitablePointable, IAType, Boolean>(
+ private final IVisitablePointable itemTempReference = allocator.allocateEmpty();
+ private final Triple<IVisitablePointable, IAType, Boolean> itemVisitorArg = new Triple<IVisitablePointable, IAType, Boolean>(
itemTempReference, null, null);
- private UnorderedListBuilder unOrderedListBuilder = new UnorderedListBuilder();
- private OrderedListBuilder orderedListBuilder = new OrderedListBuilder();
+ private final UnorderedListBuilder unOrderedListBuilder = new UnorderedListBuilder();
+ private final OrderedListBuilder orderedListBuilder = new OrderedListBuilder();
- private byte[] dataBuffer = new byte[32768];
- private ResettableByteArrayOutputStream dataBos = new ResettableByteArrayOutputStream();
- private DataOutput dataDos = new DataOutputStream(dataBos);
+ private final ResettableByteArrayOutputStream dataBos = new ResettableByteArrayOutputStream();
+ private final DataOutput dataDos = new DataOutputStream(dataBos);
+ private final byte[] dataBuffer = new byte[32768];
+ private IAType reqItemType;
public AListCaster() {
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/cast/ARecordCaster.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/cast/ARecordCaster.java
index 52aab9d..70fbc4a 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/cast/ARecordCaster.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/pointables/cast/ARecordCaster.java
@@ -41,11 +41,41 @@
import edu.uci.ics.hyracks.data.std.accessors.PointableBinaryComparatorFactory;
import edu.uci.ics.hyracks.data.std.api.IValueReference;
import edu.uci.ics.hyracks.data.std.primitive.UTF8StringPointable;
+import edu.uci.ics.hyracks.dataflow.common.comm.io.ByteArrayAccessibleOutputStream;
+/**
+ * This class is to do the runtime type cast for a record. It is ONLY visible to
+ * ACastVisitor, so that no other client places can call into that caster and
+ * unnecessary bugs could be prevented.
+ */
class ARecordCaster {
// pointable allocator
- private PointableAllocator allocator = new PointableAllocator();
+ private final PointableAllocator allocator = new PointableAllocator();
+
+ private final List<IVisitablePointable> reqFieldNames = new ArrayList<IVisitablePointable>();
+ private final List<IVisitablePointable> reqFieldTypeTags = new ArrayList<IVisitablePointable>();
+ private ARecordType cachedReqType = null;
+
+ private final byte[] buffer = new byte[32768];
+ private final ResettableByteArrayOutputStream bos = new ResettableByteArrayOutputStream();
+ private final DataOutputStream dos = new DataOutputStream(bos);
+
+ private final RecordBuilder recBuilder = new RecordBuilder();
+ private final IVisitablePointable nullReference = allocator.allocateEmpty();
+ private final IVisitablePointable nullTypeTag = allocator.allocateEmpty();
+
+ private final IBinaryComparator fieldNameComparator = PointableBinaryComparatorFactory.of(
+ UTF8StringPointable.FACTORY).createBinaryComparator();
+
+ private final ByteArrayAccessibleOutputStream outputBos = new ByteArrayAccessibleOutputStream();
+ private final DataOutputStream outputDos = new DataOutputStream(outputBos);
+
+ private final IVisitablePointable fieldTempReference = allocator.allocateEmpty();
+ private final Triple<IVisitablePointable, IAType, Boolean> nestedVisitorArg = new Triple<IVisitablePointable, IAType, Boolean>(
+ fieldTempReference, null, null);
+
+ private int numInputFields = 0;
// describe closed fields in the required type
private int[] fieldPermutation;
@@ -54,31 +84,7 @@
// describe fields (open or not) in the input records
private boolean[] openFields;
private int[] fieldNamesSortedIndex;
-
- private List<IVisitablePointable> reqFieldNames = new ArrayList<IVisitablePointable>();
private int[] reqFieldNamesSortedIndex;
- private List<IVisitablePointable> reqFieldTypeTags = new ArrayList<IVisitablePointable>();
- private ARecordType cachedReqType = null;
-
- private byte[] buffer = new byte[32768];
- private ResettableByteArrayOutputStream bos = new ResettableByteArrayOutputStream();
- private DataOutputStream dos = new DataOutputStream(bos);
-
- private RecordBuilder recBuilder = new RecordBuilder();
- private IVisitablePointable nullReference = allocator.allocateEmpty();
- private IVisitablePointable nullTypeTag = allocator.allocateEmpty();
-
- private int numInputFields = 0;
- private IBinaryComparator fieldNameComparator = PointableBinaryComparatorFactory.of(UTF8StringPointable.FACTORY)
- .createBinaryComparator();
-
- private byte[] outputBuffer = new byte[32768];
- private ResettableByteArrayOutputStream outputBos = new ResettableByteArrayOutputStream();
- private DataOutputStream outputDos = new DataOutputStream(outputBos);
-
- private IVisitablePointable fieldTempReference = allocator.allocateEmpty();
- private Triple<IVisitablePointable, IAType, Boolean> nestedVisitorArg = new Triple<IVisitablePointable, IAType, Boolean>(
- fieldTempReference, null, null);
public ARecordCaster() {
try {
@@ -116,7 +122,7 @@
reset();
matchClosedPart(fieldNames, fieldTypeTags, fieldValues);
writeOutput(fieldNames, fieldTypeTags, fieldValues, outputDos, visitor);
- resultAccessor.set(outputBuffer, 0, outputBos.size());
+ resultAccessor.set(outputBos.getByteArray(), 0, outputBos.size());
}
private void reset() {
@@ -126,7 +132,7 @@
fieldPermutation[i] = -1;
for (int i = 0; i < numInputFields; i++)
fieldNamesSortedIndex[i] = i;
- outputBos.setByteArray(outputBuffer, 0);
+ outputBos.reset();
}
private void loadRequiredType(ARecordType reqType) throws IOException {
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/ResettableByteArrayInputStream.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/ResettableByteArrayInputStream.java
deleted file mode 100644
index af18133..0000000
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/ResettableByteArrayInputStream.java
+++ /dev/null
@@ -1,61 +0,0 @@
-/*
- * Copyright 2009-2010 by The Regents of the University of California
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * you may obtain a copy of the License from
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-package edu.uci.ics.asterix.runtime.util;
-
-import java.io.ByteArrayInputStream;
-import java.util.logging.Level;
-import java.util.logging.Logger;
-
-public class ResettableByteArrayInputStream extends ByteArrayInputStream {
- private static final Logger LOGGER = Logger.getLogger(ResettableByteArrayInputStream.class.getName());
-
- private byte[] data;
- private int position;
-
- public ResettableByteArrayInputStream(byte[] data) {
- super(data);
- }
-
- public void setByteArray(byte[] data, int position) {
- this.data = data;
- this.position = position;
- }
-
- @Override
- public int read() {
- int remaining = data.length - position;
- int value = remaining > 0 ? (data[position++] & 0xff) : -1;
- if (LOGGER.isLoggable(Level.FINEST)) {
- LOGGER.finest("read(): value: " + value + " remaining: " + remaining + " position: " + position);
- }
- return value;
- }
-
- @Override
- public int read(byte[] bytes, int offset, int length) {
- int remaining = data.length - position;
- if (LOGGER.isLoggable(Level.FINEST)) {
- LOGGER.finest("read(bytes[], int, int): remaining: " + remaining + " offset: " + offset + " length: "
- + length + " position: " + position);
- }
- if (remaining == 0) {
- return -1;
- }
- int l = Math.min(length, remaining);
- System.arraycopy(data, position, bytes, offset, l);
- position += l;
- return l;
- }
-}
\ No newline at end of file
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/container/IElementAllocator.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/container/IElementAllocator.java
index b99f379..8172e56 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/container/IElementAllocator.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/container/IElementAllocator.java
@@ -20,7 +20,19 @@
*/
public interface IElementAllocator<E, T> {
+ /**
+ * Give client an E instance
+ *
+ * @param arg
+ * , the argument to create E
+ * @return a E instance
+ */
public E allocate(T arg);
+ /**
+ * Clean all the used(assigned) instances in the pool. Then all instances in
+ * the pool are marked as "unused" and can be returned to next bunch of
+ * allocate call from a client
+ */
public void reset();
}
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/container/IElementFactory.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/container/IElementFactory.java
index 293720e..f914d13 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/container/IElementFactory.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/container/IElementFactory.java
@@ -16,13 +16,16 @@
package edu.uci.ics.asterix.runtime.util.container;
/**
- * A factory interface to create elements
+ * A factory interface to create elements. Elements in a reusable pool/container
+ * can ONLY be instantiated from the corresponding factory
*/
public interface IElementFactory<E, T> {
/**
* create an element of type E
- * @param arg of type T
+ *
+ * @param arg
+ * of type T
* @return an E element
*/
public E createElement(T arg);
diff --git a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/container/ListElementAllocator.java b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/container/ListElementAllocator.java
index a2b2273..dc96153 100644
--- a/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/container/ListElementAllocator.java
+++ b/asterix-runtime/src/main/java/edu/uci/ics/asterix/runtime/util/container/ListElementAllocator.java
@@ -25,7 +25,11 @@
* other words, however elements in the list should be exactly the same class,
* this is forced by IElementFactory<E, T> factory as a parameter to the
* constructor once a ListElementAllocator is constructed, it can only store
- * objects of the same class
+ * objects of the same class.
+ *
+ * The argument for creating E instances could be different. This class also
+ * considers arguments in object reusing, e.g., reuse an E instances ONLY when
+ * the construction argument is "equal".
*/
public class ListElementAllocator<E, T> implements IElementAllocator<E, T> {