added javadoc comments
diff --git a/bundles/org.eclipse.core.resources/src/org/eclipse/core/internal/localstore/Bucket.java b/bundles/org.eclipse.core.resources/src/org/eclipse/core/internal/localstore/Bucket.java index 780c32d..3b19c0e 100644 --- a/bundles/org.eclipse.core.resources/src/org/eclipse/core/internal/localstore/Bucket.java +++ b/bundles/org.eclipse.core.resources/src/org/eclipse/core/internal/localstore/Bucket.java
@@ -19,6 +19,10 @@ import org.eclipse.core.resources.IResourceStatus; import org.eclipse.core.runtime.*; +/** + * A bucket is a persistent dictionary having paths as keys. Values are determined + * by subclasses. + */ public abstract class Bucket { public static abstract class Entry { @@ -97,6 +101,9 @@ } } + /** + * A visitor for bucket entries. + */ public static abstract class Visitor { // should continue the traversal public final static int CONTINUE = 0; @@ -187,6 +194,9 @@ } } + /** + * Factory method for creating entries. Subclasses to override. + */ protected abstract Entry createEntry(IPath path, Object value); /** @@ -201,24 +211,44 @@ delete(toDelete.getParentFile()); } + /** + * Returns how many entries there are in this bucket. + */ public final int getEntryCount() { return entries.size(); } + /** + * Returns the value for entry corresponding to the given path (null if none found). + */ public final Object getEntryValue(String path) { return entries.get(path); } + /** + * Returns the directory where this bucket should be stored. + */ public File getLocation() { return location == null ? null : location.getParentFile(); } + /** + * Returns the version number for the file format used to persist this bucket. + */ protected abstract byte getVersion(); + /** + * Loads the contents from a file under the given directory. + */ public final void load(File baseLocation) throws CoreException { load(baseLocation, false); } + /** + * Loads the contents from a file under the given directory. If <code>force</code> is + * <code>false</code>, if this bucket already contains the contents from the current location, + * avoids reloading. + */ public final void load(File baseLocation, boolean force) throws CoreException { try { // avoid reloading @@ -252,8 +282,14 @@ } } + /** + * Defines how data for a given entry is to be read from a bucket file. To be implemented by subclasses. + */ protected abstract Object readEntryValue(DataInputStream source) throws IOException; + /** + * Saves this bucket's contents back to its location. + */ public final void save() throws CoreException { if (!needSaving) return; @@ -285,6 +321,10 @@ } } + /** + * Sets the value for the entry with the given path. If <code>value</code> is <code>null</code>, + * removes the entry. + */ public final void setEntryValue(String path, Object value) { if (value == null) entries.remove(path); @@ -293,5 +333,8 @@ needSaving = true; } + /** + * Defines how an entry is to be persisted to the bucket file. + */ protected abstract void writeEntryValue(DataOutputStream destination, Object entryValue) throws IOException; }
diff --git a/bundles/org.eclipse.core.resources/src/org/eclipse/core/internal/properties/PropertyBucket.java b/bundles/org.eclipse.core.resources/src/org/eclipse/core/internal/properties/PropertyBucket.java index 71c5884..c8b1e0b 100644 --- a/bundles/org.eclipse.core.resources/src/org/eclipse/core/internal/properties/PropertyBucket.java +++ b/bundles/org.eclipse.core.resources/src/org/eclipse/core/internal/properties/PropertyBucket.java
@@ -31,8 +31,8 @@ /** * Deletes the property with the given name, and returns the result array. Returns the original - * array if the property to be deleted could not be found. Returns nul if the property was found - * and the original array had size 1. + * array if the property to be deleted could not be found. Returns <code>null</code> if the property was found + * and the original array had size 1 (instead of a zero-length array). */ public static String[][] delete(String[][] existing, String propertyName) { // a size-1 array is a special case @@ -72,6 +72,40 @@ return newValue; } + /** + * Merges two entries (are always sorted). Duplicated additions replace existing ones. + */ + static Object merge(String[][] base, String[][] additions) { + int additionPointer = 0; + int basePointer = 0; + int added = 0; + String[][] result = new String[base.length + additions.length][]; + while (basePointer < base.length && additionPointer < additions.length) { + int comparison = base[basePointer][0].compareTo(additions[additionPointer][0]); + if (comparison == 0) { + result[added++] = additions[additionPointer++]; + // duplicate, override + basePointer++; + } else if (comparison < 0) + result[added++] = base[basePointer++]; + else + result[added++] = additions[additionPointer++]; + } + // copy the remaining states from either additions or base arrays + String[][] remaining = basePointer == base.length ? additions : base; + int remainingPointer = basePointer == base.length ? additionPointer : basePointer; + int remainingCount = remaining.length - remainingPointer; + System.arraycopy(remaining, remainingPointer, result, added, remainingCount); + added += remainingCount; + if (added == base.length + additions.length) + // no collisions + return result; + // there were collisions, need to compact + String[][] finalResult = new String[added][]; + System.arraycopy(result, 0, finalResult, 0, finalResult.length); + return finalResult; + } + private static int search(String[][] existing, String propertyName) { return Arrays.binarySearch(existing, new String[] {propertyName, null}, COMPARATOR); } @@ -82,6 +116,10 @@ System.arraycopy(base.value, 0, this.value, 0, this.value.length); } + /** + * @param path + * @param value is a String[][] {{propertyKey, propertyValue}} + */ protected PropertyEntry(IPath path, String[][] value) { super(path); this.value = value; @@ -136,40 +174,6 @@ public void visited() { compact(); } - - /** - * Merges two entries (are always sorted). Duplicated additions replace existing ones. - */ - static Object merge(String[][] base, String[][] additions) { - int additionPointer = 0; - int basePointer = 0; - int added = 0; - String[][] result = new String[base.length + additions.length][]; - while (basePointer < base.length && additionPointer < additions.length) { - int comparison = base[basePointer][0].compareTo(additions[additionPointer][0]); - if (comparison == 0) { - result[added++] = additions[additionPointer++]; - // duplicate, override - basePointer++; - } else if (comparison < 0) - result[added++] = base[basePointer++]; - else - result[added++] = additions[additionPointer++]; - } - // copy the remaining states from either additions or base arrays - String[][] remaining = basePointer == base.length ? additions : base; - int remainingPointer = basePointer == base.length ? additionPointer : basePointer; - int remainingCount = remaining.length - remainingPointer; - System.arraycopy(remaining, remainingPointer, result, added, remainingCount); - added += remainingCount; - if (added == base.length + additions.length) - // no collisions - return result; - // there were collisions, need to compact - String[][] finalResult = new String[added][]; - System.arraycopy(result, 0, finalResult, 0, finalResult.length); - return finalResult; - } } /** Version number for the current implementation file's format. @@ -260,7 +264,9 @@ String[][] properties = (String[][]) entryValue; destination.writeShort(properties.length); for (int j = 0; j < properties.length; j++) { + // writes the property key destination.writeUTF(properties[j][0]); + // then the property value destination.writeUTF(properties[j][1]); } }