From 467d516b9cd00c1aefd2569b41ef43bc187d1312 Mon Sep 17 00:00:00 2001 From: Thomas Neidhart Date: Mon, 10 Jun 2013 21:46:19 +0000 Subject: [PATCH] Cleanup of trie package. git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1491615 13f79535-47bb-0310-9956-ffa450edef68 --- .../trie/AbstractKeyAnalyzer.java | 72 ---- .../collections4/trie/AbstractTrie.java | 39 +-- .../collections4/trie/KeyAnalyzer.java | 85 ++++- .../collections4/trie/PatriciaTrie.java | 314 ++++-------------- .../collections4/trie/PatriciaTrieBase.java | 182 ++-------- .../{ => analyzer}/ByteArrayKeyAnalyzer.java | 52 +-- .../trie/{ => analyzer}/ByteKeyAnalyzer.java | 42 +-- .../{ => analyzer}/CharArrayKeyAnalyzer.java | 42 +-- .../{ => analyzer}/CharacterKeyAnalyzer.java | 42 +-- .../{ => analyzer}/IntegerKeyAnalyzer.java | 41 +-- .../trie/{ => analyzer}/LongKeyAnalyzer.java | 41 +-- .../trie/{ => analyzer}/ShortKeyAnalyzer.java | 54 +-- .../{ => analyzer}/StringKeyAnalyzer.java | 46 +-- .../trie/analyzer/package-info.java | 22 ++ .../collections4/trie/PatriciaTrieTest.java | 4 + .../ByteArrayKeyAnalyzerTest.java | 4 +- 16 files changed, 300 insertions(+), 782 deletions(-) delete mode 100644 src/main/java/org/apache/commons/collections4/trie/AbstractKeyAnalyzer.java rename src/main/java/org/apache/commons/collections4/trie/{ => analyzer}/ByteArrayKeyAnalyzer.java (82%) rename src/main/java/org/apache/commons/collections4/trie/{ => analyzer}/ByteKeyAnalyzer.java (78%) rename src/main/java/org/apache/commons/collections4/trie/{ => analyzer}/CharArrayKeyAnalyzer.java (84%) rename src/main/java/org/apache/commons/collections4/trie/{ => analyzer}/CharacterKeyAnalyzer.java (77%) rename src/main/java/org/apache/commons/collections4/trie/{ => analyzer}/IntegerKeyAnalyzer.java (78%) rename src/main/java/org/apache/commons/collections4/trie/{ => analyzer}/LongKeyAnalyzer.java (78%) rename src/main/java/org/apache/commons/collections4/trie/{ => analyzer}/ShortKeyAnalyzer.java (78%) rename src/main/java/org/apache/commons/collections4/trie/{ => analyzer}/StringKeyAnalyzer.java (81%) create mode 100644 src/main/java/org/apache/commons/collections4/trie/analyzer/package-info.java rename src/test/java/org/apache/commons/collections4/trie/{ => analyzer}/ByteArrayKeyAnalyzerTest.java (95%) diff --git a/src/main/java/org/apache/commons/collections4/trie/AbstractKeyAnalyzer.java b/src/main/java/org/apache/commons/collections4/trie/AbstractKeyAnalyzer.java deleted file mode 100644 index 55297ec78..000000000 --- a/src/main/java/org/apache/commons/collections4/trie/AbstractKeyAnalyzer.java +++ /dev/null @@ -1,72 +0,0 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 at - * - * 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 org.apache.commons.collections4.trie; - -/** - * TODO: add javadoc - * - * @since 4.0 - * @version $Id$ - */ -public abstract class AbstractKeyAnalyzer implements KeyAnalyzer { - - private static final long serialVersionUID = -20497563720380683L; - - /** - * {@inheritDoc} - */ - @SuppressWarnings("unchecked") - public int compare(final K o1, final K o2) { - if (o1 == null) { - return o2 == null ? 0 : -1; - } else if (o2 == null) { - return 1; - } - - return ((Comparable)o1).compareTo(o2); - } - - /** - * Returns true if bitIndex is a {@link KeyAnalyzer#OUT_OF_BOUNDS_BIT_KEY} - */ - static boolean isOutOfBoundsIndex(final int bitIndex) { - return bitIndex == OUT_OF_BOUNDS_BIT_KEY; - } - - /** - * Returns true if bitIndex is a {@link KeyAnalyzer#EQUAL_BIT_KEY} - */ - static boolean isEqualBitKey(final int bitIndex) { - return bitIndex == EQUAL_BIT_KEY; - } - - /** - * Returns true if bitIndex is a {@link KeyAnalyzer#NULL_BIT_KEY} - */ - static boolean isNullBitKey(final int bitIndex) { - return bitIndex == NULL_BIT_KEY; - } - - /** - * Returns true if the given bitIndex is valid. Indices - * are considered valid if they're between 0 and - * {@link Integer#MAX_VALUE} - */ - static boolean isValidBitIndex(final int bitIndex) { - return bitIndex >= 0; - } -} diff --git a/src/main/java/org/apache/commons/collections4/trie/AbstractTrie.java b/src/main/java/org/apache/commons/collections4/trie/AbstractTrie.java index a5e14adce..67717f2af 100644 --- a/src/main/java/org/apache/commons/collections4/trie/AbstractTrie.java +++ b/src/main/java/org/apache/commons/collections4/trie/AbstractTrie.java @@ -60,9 +60,6 @@ abstract class AbstractTrie extends AbstractMap return keyAnalyzer; } - /** - * {@inheritDoc} - */ public K selectKey(final K key) { final Map.Entry entry = select(key); if (entry == null) { @@ -71,9 +68,6 @@ abstract class AbstractTrie extends AbstractMap return entry.getKey(); } - /** - * {@inheritDoc} - */ public V selectValue(final K key) { final Map.Entry entry = select(key); if (entry == null) { @@ -94,12 +88,11 @@ abstract class AbstractTrie extends AbstractMap } /** - * A utility method to cast keys. It actually doesn't - * cast anything. It's just fooling the compiler! + * A utility method to cast keys. It actually doesn't cast anything. It's just fooling the compiler! */ @SuppressWarnings("unchecked") final K castKey(final Object key) { - return (K)key; + return (K) key; } /** @@ -125,8 +118,7 @@ abstract class AbstractTrie extends AbstractMap } /** - * Returns whether or not the given bit on the - * key is set or false if the key is null. + * Returns whether or not the given bit on the key is set or false if the key is null. * * @see KeyAnalyzer#isBitSet(Object, int, int) */ @@ -138,11 +130,10 @@ abstract class AbstractTrie extends AbstractMap } /** - * Utility method for calling {@link KeyAnalyzer#bitIndex(Object, int, int, Object, int, int)} + * Utility method for calling {@link KeyAnalyzer#bitIndex(Object, int, int, Object, int, int)}. */ final int bitIndex(final K key, final K foundKey) { - return keyAnalyzer.bitIndex(key, 0, lengthInBits(key), - foundKey, 0, lengthInBits(foundKey)); + return keyAnalyzer.bitIndex(key, 0, lengthInBits(key), foundKey, 0, lengthInBits(foundKey)); } /** @@ -159,14 +150,14 @@ abstract class AbstractTrie extends AbstractMap } /** - * Returns true if both values are either null or equal + * Returns true if both values are either null or equal. */ static boolean compare(final Object a, final Object b) { return a == null ? b == null : a.equals(b); } /** - * A basic implementation of {@link Entry} + * A basic implementation of {@link Entry}. */ abstract static class BasicEntry implements Map.Entry, Serializable { @@ -186,37 +177,25 @@ abstract class AbstractTrie extends AbstractMap public BasicEntry(final K key, final V value) { this.key = key; this.value = value; - - this.hashCode = (key != null ? key.hashCode() : 0) - ^ (value != null ? value.hashCode() : 0); + this.hashCode = (key != null ? key.hashCode() : 0) ^ (value != null ? value.hashCode() : 0); } /** - * Replaces the current key and value with the provided - * key & value + * Replaces the current key and value with the provided key & value. */ public V setKeyValue(final K key, final V value) { this.key = key; return setValue(value); } - /** - * {@inheritDoc} - */ public K getKey() { return key; } - /** - * {@inheritDoc} - */ public V getValue() { return value; } - /** - * {@inheritDoc} - */ public V setValue(final V value) { final V previous = this.value; this.value = value; diff --git a/src/main/java/org/apache/commons/collections4/trie/KeyAnalyzer.java b/src/main/java/org/apache/commons/collections4/trie/KeyAnalyzer.java index c1825454f..f3ed2aa24 100644 --- a/src/main/java/org/apache/commons/collections4/trie/KeyAnalyzer.java +++ b/src/main/java/org/apache/commons/collections4/trie/KeyAnalyzer.java @@ -32,7 +32,10 @@ import java.util.Comparator; * @since 4.0 * @version $Id$ */ -public interface KeyAnalyzer extends Comparator, Serializable { +public abstract class KeyAnalyzer implements Comparator, Serializable { + + /** Serialization version */ + private static final long serialVersionUID = -20497563720380683L; /** * Returned by {@link #bitIndex(Object, int, int, Object, int, int)} @@ -49,13 +52,43 @@ public interface KeyAnalyzer extends Comparator, Serializable { public static final int OUT_OF_BOUNDS_BIT_KEY = -3; + /** + * Returns true if bitIndex is a {@link KeyAnalyzer#OUT_OF_BOUNDS_BIT_KEY} + */ + static boolean isOutOfBoundsIndex(final int bitIndex) { + return bitIndex == OUT_OF_BOUNDS_BIT_KEY; + } + + /** + * Returns true if bitIndex is a {@link KeyAnalyzer#EQUAL_BIT_KEY} + */ + static boolean isEqualBitKey(final int bitIndex) { + return bitIndex == EQUAL_BIT_KEY; + } + + /** + * Returns true if bitIndex is a {@link KeyAnalyzer#NULL_BIT_KEY} + */ + static boolean isNullBitKey(final int bitIndex) { + return bitIndex == NULL_BIT_KEY; + } + + /** + * Returns true if the given bitIndex is valid. Indices + * are considered valid if they're between 0 and + * {@link Integer#MAX_VALUE} + */ + static boolean isValidBitIndex(final int bitIndex) { + return bitIndex >= 0; + } + /** * Returns the number of bits per element in the key. * This is only useful for variable-length keys, such as Strings. * * @return the number of bits per element */ - public int bitsPerElement(); + public abstract int bitsPerElement(); /** * Returns the length of the Key in bits. @@ -63,23 +96,55 @@ public interface KeyAnalyzer extends Comparator, Serializable { * @param key the key * @return the bit length of the key */ - public int lengthInBits(K key); + public abstract int lengthInBits(K key); /** * Returns whether or not a bit is set. + * + * @param key the key to check, may not be null + * @param bitIndex the bit index to check + * @param lengthInBits the maximum key length in bits to check + * @return {@code true} if the bit is set in the given key and + * {@code bitIndex} < {@code lengthInBits}, {@code false} otherwise. */ - public boolean isBitSet(K key, int bitIndex, int lengthInBits); + public abstract boolean isBitSet(K key, int bitIndex, int lengthInBits); /** - * Returns the n-th different bit between key and found. This starts the comparison in - * key at 'keyStart' and goes for 'keyLength' bits, and compares to the found key starting - * at 'foundStart' and going for 'foundLength' bits. + * Returns the n-th different bit between key and other. This starts the comparison in + * key at 'offsetInBits' and goes for 'lengthInBits' bits, and compares to the other key starting + * at 'otherOffsetInBits' and going for 'otherLengthInBits' bits. + * + * @param key the key to use + * @param offsetInBits the bit offset in the key + * @param lengthInBits the maximum key length in bits to use + * @param other the other key to use + * @param otherOffsetInBits the bit offset in the other key + * @param otherLengthInBits the maximum key length in bits for the other key + * @return the bit index where the key and other first differ */ - public int bitIndex(K key, int offsetInBits, int lengthInBits, - K other, int otherOffsetInBits, int otherLengthInBits); + public abstract int bitIndex(K key, int offsetInBits, int lengthInBits, + K other, int otherOffsetInBits, int otherLengthInBits); /** * Determines whether or not the given prefix (from offset to length) is a prefix of the given key. + * + * @param prefix the prefix to check + * @param offsetInBits the bit offset in the key + * @param lengthInBits the maximum key length in bits to use + * @param key the key to check + * @return {@code true} if this is a valid prefix for the given key */ - public boolean isPrefix(K prefix, int offsetInBits, int lengthInBits, K key); + public abstract boolean isPrefix(K prefix, int offsetInBits, int lengthInBits, K key); + + @SuppressWarnings("unchecked") + public int compare(final K o1, final K o2) { + if (o1 == null) { + return o2 == null ? 0 : -1; + } else if (o2 == null) { + return 1; + } + + return ((Comparable) o1).compareTo(o2); + } + } diff --git a/src/main/java/org/apache/commons/collections4/trie/PatriciaTrie.java b/src/main/java/org/apache/commons/collections4/trie/PatriciaTrie.java index 1bf86b58d..5cae3cdf5 100644 --- a/src/main/java/org/apache/commons/collections4/trie/PatriciaTrie.java +++ b/src/main/java/org/apache/commons/collections4/trie/PatriciaTrie.java @@ -77,57 +77,35 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie keyAnalyzer, - final Map m) { + public PatriciaTrie(final KeyAnalyzer keyAnalyzer, final Map m) { super(keyAnalyzer, m); } - /** - * {@inheritDoc} - */ public Comparator comparator() { return keyAnalyzer; } - /** - * {@inheritDoc} - */ public SortedMap getPrefixedBy(final K key) { return getPrefixedByBits(key, 0, lengthInBits(key)); } - /** - * {@inheritDoc} - */ public SortedMap getPrefixedBy(final K key, final int length) { return getPrefixedByBits(key, 0, length * bitsPerElement()); } - /** - * {@inheritDoc} - */ public SortedMap getPrefixedBy(final K key, final int offset, final int length) { final int bitsPerElement = bitsPerElement(); return getPrefixedByBits(key, offset*bitsPerElement, length*bitsPerElement); } - /** - * {@inheritDoc} - */ public SortedMap getPrefixedByBits(final K key, final int lengthInBits) { return getPrefixedByBits(key, 0, lengthInBits); } - /** - * {@inheritDoc} - */ public K firstKey() { return firstEntry().getKey(); } - /** - * {@inheritDoc} - */ public K lastKey() { final TrieEntry entry = lastEntry(); if (entry != null) { @@ -165,23 +143,14 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie headMap(final K toKey) { return new RangeEntryMap(null, toKey); } - /** - * {@inheritDoc} - */ public SortedMap subMap(final K fromKey, final K toKey) { return new RangeEntryMap(fromKey, toKey); } - /** - * {@inheritDoc} - */ public SortedMap tailMap(final K fromKey) { return new RangeEntryMap(fromKey, null); } @@ -216,7 +185,7 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie added = new TrieEntry(key, null, bitIndex); addEntry(added, lengthInBits); incrementSize(); // must increment because remove will decrement @@ -224,7 +193,7 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie 1) { @@ -232,7 +201,7 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie added = new TrieEntry(key, null, bitIndex); addEntry(added, lengthInBits); incrementSize(); // must increment because remove will decrement @@ -287,13 +256,13 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie added = new TrieEntry(key, null, bitIndex); addEntry(added, lengthInBits); incrementSize(); // must increment because remove will decrement @@ -343,9 +312,9 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie added = new TrieEntry(key, null, bitIndex); addEntry(added, lengthInBits); incrementSize(); // must increment because remove will decrement @@ -385,13 +354,13 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie current = root.left; TrieEntry path = root; while(true) { - if (current.bitIndex <= path.bitIndex - || lengthInBits < current.bitIndex) { + if (current.bitIndex <= path.bitIndex || lengthInBits < current.bitIndex) { break; } path = current; - if (!isBitSet(prefix, offsetInBits + current.bitIndex, - offsetInBits + lengthInBits)) { + if (!isBitSet(prefix, offsetInBits + current.bitIndex, offsetInBits + lengthInBits)) { current = current.left; } else { current = current.right; @@ -503,7 +470,7 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie previousEntry(final TrieEntry start) { if (start.predecessor == null) { @@ -560,52 +527,43 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie implements SortedMap { - /** - * The {@link #entrySet()} view - */ + /** The {@link #entrySet()} view. */ private transient volatile Set> entrySet; /** - * Creates and returns an {@link #entrySet()} - * view of the {@link RangeMap} + * Creates and returns an {@link #entrySet()} view of the {@link RangeMap}. */ protected abstract Set> createEntrySet(); /** - * Returns the FROM Key + * Returns the FROM Key. */ protected abstract K getFromKey(); /** - * Whether or not the {@link #getFromKey()} is in the range + * Whether or not the {@link #getFromKey()} is in the range. */ protected abstract boolean isFromInclusive(); /** - * Returns the TO Key + * Returns the TO Key. */ protected abstract K getToKey(); /** - * Whether or not the {@link #getToKey()} is in the range + * Whether or not the {@link #getToKey()} is in the range. */ protected abstract boolean isToInclusive(); - /** - * {@inheritDoc} - */ public Comparator comparator() { return PatriciaTrie.this.comparator(); } - /** - * {@inheritDoc} - */ @Override public boolean containsKey(final Object key) { if (!inRange(castKey(key))) { @@ -615,9 +573,6 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie> entrySet() { if (entrySet == null) { @@ -663,81 +607,56 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie subMap(final K fromKey, final K toKey) { if (!inRange2(fromKey)) { - throw new IllegalArgumentException( - "FromKey is out of range: " + fromKey); + throw new IllegalArgumentException("FromKey is out of range: " + fromKey); } if (!inRange2(toKey)) { - throw new IllegalArgumentException( - "ToKey is out of range: " + toKey); + throw new IllegalArgumentException("ToKey is out of range: " + toKey); } - return createRangeMap(fromKey, isFromInclusive(), - toKey, isToInclusive()); + return createRangeMap(fromKey, isFromInclusive(), toKey, isToInclusive()); } - /** - * {@inheritDoc} - */ public SortedMap headMap(final K toKey) { if (!inRange2(toKey)) { - throw new IllegalArgumentException( - "ToKey is out of range: " + toKey); + throw new IllegalArgumentException("ToKey is out of range: " + toKey); } - - return createRangeMap(getFromKey(), isFromInclusive(), - toKey, isToInclusive()); + return createRangeMap(getFromKey(), isFromInclusive(), toKey, isToInclusive()); } - /** - * {@inheritDoc} - */ public SortedMap tailMap(final K fromKey) { if (!inRange2(fromKey)) { - throw new IllegalArgumentException( - "FromKey is out of range: " + fromKey); + throw new IllegalArgumentException("FromKey is out of range: " + fromKey); } - - return createRangeMap(fromKey, isFromInclusive(), - getToKey(), isToInclusive()); + return createRangeMap(fromKey, isFromInclusive(), getToKey(), isToInclusive()); } /** - * Returns true if the provided key is greater than TO and - * less than FROM + * Returns true if the provided key is greater than TO and less than FROM. */ protected boolean inRange(final K key) { - final K fromKey = getFromKey(); final K toKey = getToKey(); - return (fromKey == null || inFromRange(key, false)) - && (toKey == null || inToRange(key, false)); + return (fromKey == null || inFromRange(key, false)) && (toKey == null || inToRange(key, false)); } /** - * This form allows the high endpoint (as well as all legit keys) + * This form allows the high endpoint (as well as all legit keys). */ protected boolean inRange2(final K key) { - final K fromKey = getFromKey(); final K toKey = getToKey(); - return (fromKey == null || inFromRange(key, false)) - && (toKey == null || inToRange(key, true)); + return (fromKey == null || inFromRange(key, false)) && (toKey == null || inToRange(key, true)); } /** - * Returns true if the provided key is in the FROM range - * of the {@link RangeMap} + * Returns true if the provided key is in the FROM range of the {@link RangeMap}. */ protected boolean inFromRange(final K key, final boolean forceInclusive) { - final K fromKey = getFromKey(); final boolean fromInclusive = isFromInclusive(); @@ -750,11 +669,9 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie createRangeMap(K fromKey, - boolean fromInclusive, K toKey, boolean toInclusive); + protected abstract SortedMap createRangeMap(K fromKey, boolean fromInclusive, + K toKey, boolean toInclusive); } /** - * A {@link RangeMap} that deals with {@link Entry}s + * A {@link RangeMap} that deals with {@link Entry}s. */ private class RangeEntryMap extends RangeMap { - /** - * The key to start from, null if the beginning. - */ + /** The key to start from, null if the beginning. */ private final K fromKey; - /** - * The key to end at, null if till the end. - */ + /** The key to end at, null if till the end. */ private final K toKey; - /** - * Whether or not the 'from' is inclusive. - */ + /** Whether or not the 'from' is inclusive. */ private final boolean fromInclusive; - /** - * Whether or not the 'to' is inclusive. - */ + /** Whether or not the 'to' is inclusive. */ private final boolean toInclusive; /** * Creates a {@link RangeEntryMap} with the fromKey included and - * the toKey excluded from the range + * the toKey excluded from the range. */ protected RangeEntryMap(final K fromKey, final K toKey) { this(fromKey, true, toKey, false); } /** - * Creates a {@link RangeEntryMap} + * Creates a {@link RangeEntryMap}. */ protected RangeEntryMap(final K fromKey, final boolean fromInclusive, - final K toKey, final boolean toInclusive) { + final K toKey, final boolean toInclusive) { if (fromKey == null && toKey == null) { throw new IllegalArgumentException("must have a from or to!"); @@ -827,9 +736,6 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie e = null; if (fromKey == null) { @@ -849,9 +755,6 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie e; if (toKey == null) { @@ -871,49 +774,31 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie> createEntrySet() { return new RangeEntrySet(this); } - /** - * {@inheritDoc} - */ @Override public K getFromKey() { return fromKey; } - /** - * {@inheritDoc} - */ @Override public K getToKey() { return toKey; } - /** - * {@inheritDoc} - */ @Override public boolean isFromInclusive() { return fromInclusive; } - /** - * {@inheritDoc} - */ @Override public boolean isToInclusive() { return toInclusive; } - /** - * {@inheritDoc} - */ @Override protected SortedMap createRangeMap(final K fromKey, final boolean fromInclusive, final K toKey, final boolean toInclusive) { @@ -922,7 +807,7 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie> { @@ -933,7 +818,7 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie> iterator() { final K fromKey = delegate.getFromKey(); @@ -966,9 +848,6 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie first, - final TrieEntry last) { + private EntryIterator(final TrieEntry first, final TrieEntry last) { super(first); - this.excludedKey = last != null ? last.getKey() : null; } - /** - * {@inheritDoc} - */ @Override public boolean hasNext() { return next != null && !compare(next.key, excludedKey); } - /** - * {@inheritDoc} - */ public Map.Entry next() { if (next == null || compare(next.key, excludedKey)) { throw new NoSuchElementException(); } - return nextEntry(); } } @@ -1094,7 +954,7 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie> createEntrySet() { return new PrefixRangeEntrySet(this); } - /** - * {@inheritDoc} - */ @Override public K getFromKey() { return fromKey; } - /** - * {@inheritDoc} - */ @Override public K getToKey() { return toKey; } - /** - * {@inheritDoc} - */ @Override public boolean isFromInclusive() { return false; } - /** - * {@inheritDoc} - */ @Override public boolean isToInclusive() { return false; } - /** - * {@inheritDoc} - */ @Override - protected SortedMap createRangeMap( - final K fromKey, final boolean fromInclusive, - final K toKey, final boolean toInclusive) { + protected SortedMap createRangeMap(final K fromKey, final boolean fromInclusive, + final K toKey, final boolean toInclusive) { return new RangeEntryMap(fromKey, fromInclusive, toKey, toInclusive); } } /** - * A prefix {@link RangeEntrySet} view of the {@link Trie} + * A prefix {@link RangeEntrySet} view of the {@link Trie}. */ private final class PrefixRangeEntrySet extends RangeEntrySet { @@ -1289,24 +1121,18 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie> iterator() { if (PatriciaTrie.this.modCount != expectedModCount) { @@ -1337,16 +1163,10 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie next() { if (hit != 0) { throw new NoSuchElementException(); @@ -1356,9 +1176,6 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie extends PatriciaTrieBase implements Trie next() { final Map.Entry entry = nextEntry(); if (lastOne) { @@ -1406,17 +1220,11 @@ public class PatriciaTrie extends PatriciaTrieBase implements Trie findNext(final TrieEntry prior) { return PatriciaTrie.this.nextEntryInSubtree(prior, subtree); } - /** - * {@inheritDoc} - */ @Override public void remove() { // If the current entry we're removing is the subtree diff --git a/src/main/java/org/apache/commons/collections4/trie/PatriciaTrieBase.java b/src/main/java/org/apache/commons/collections4/trie/PatriciaTrieBase.java index d7737e442..1d723863c 100644 --- a/src/main/java/org/apache/commons/collections4/trie/PatriciaTrieBase.java +++ b/src/main/java/org/apache/commons/collections4/trie/PatriciaTrieBase.java @@ -52,41 +52,29 @@ abstract class PatriciaTrieBase extends AbstractTrie { private transient volatile Collection values; private transient volatile Set> entrySet; - /** - * The current size of the {@link Trie} - */ + /** The current size of the {@link Trie}. */ private int size = 0; /** * The number of times this {@link Trie} has been modified. - * It's used to detect concurrent modifications and fail-fast - * the {@link Iterator}s. + * It's used to detect concurrent modifications and fail-fast the {@link Iterator}s. */ - transient int modCount = 0; + protected transient int modCount = 0; public PatriciaTrieBase(final KeyAnalyzer keyAnalyzer) { super(keyAnalyzer); } /** - * Constructs a new {@link org.apache.commons.collections4.Trie Trie} using the given {@link KeyAnalyzer} - * and initializes the {@link org.apache.commons.collections4.Trie Trie} with the values from the - * provided {@link Map}. + * Constructs a new {@link org.apache.commons.collections4.Trie Trie} using the given + * {@link KeyAnalyzer} and initializes the {@link org.apache.commons.collections4.Trie Trie} + * with the values from the provided {@link Map}. */ - public PatriciaTrieBase(final KeyAnalyzer keyAnalyzer, - final Map m) { + public PatriciaTrieBase(final KeyAnalyzer keyAnalyzer, final Map m) { super(keyAnalyzer); - - if (m == null) { - throw new NullPointerException("m"); - } - putAll(m); } - /** - * {@inheritDoc} - */ @Override public void clear() { root.key = null; @@ -102,17 +90,13 @@ abstract class PatriciaTrieBase extends AbstractTrie { incrementModCount(); } - /** - * {@inheritDoc} - */ @Override public int size() { return size; } /** - * A helper method to increment the {@link Trie} size - * and the modification counter. + * A helper method to increment the {@link Trie} size and the modification counter. */ void incrementSize() { size++; @@ -120,8 +104,7 @@ abstract class PatriciaTrieBase extends AbstractTrie { } /** - * A helper method to decrement the {@link Trie} size - * and increment the modification counter. + * A helper method to decrement the {@link Trie} size and increment the modification counter. */ void decrementSize() { size--; @@ -135,9 +118,6 @@ abstract class PatriciaTrieBase extends AbstractTrie { ++modCount; } - /** - * {@inheritDoc} - */ @Override public V put(final K key, final V value) { if (key == null) { @@ -168,14 +148,14 @@ abstract class PatriciaTrieBase extends AbstractTrie { } final int bitIndex = bitIndex(key, found.key); - if (!AbstractKeyAnalyzer.isOutOfBoundsIndex(bitIndex)) { - if (AbstractKeyAnalyzer.isValidBitIndex(bitIndex)) { // in 99.999...9% the case + if (!KeyAnalyzer.isOutOfBoundsIndex(bitIndex)) { + if (KeyAnalyzer.isValidBitIndex(bitIndex)) { // in 99.999...9% the case /* NEW KEY+VALUE TUPLE */ final TrieEntry t = new TrieEntry(key, value, bitIndex); addEntry(t, lengthInBits); incrementSize(); return null; - } else if (AbstractKeyAnalyzer.isNullBitKey(bitIndex)) { + } else if (KeyAnalyzer.isNullBitKey(bitIndex)) { // A bits of the Key are zero. The only place to // store such a Key is the root Node! @@ -187,7 +167,7 @@ abstract class PatriciaTrieBase extends AbstractTrie { } return root.setKeyValue(key, value); - } else if (AbstractKeyAnalyzer.isEqualBitKey(bitIndex)) { + } else if (KeyAnalyzer.isEqualBitKey(bitIndex)) { // This is a very special and rare case. /* REPLACE OLD KEY+VALUE */ @@ -198,11 +178,11 @@ abstract class PatriciaTrieBase extends AbstractTrie { } } - throw new IndexOutOfBoundsException("Failed to put: " + key + " -> " + value + ", " + bitIndex); + throw new IllegalArgumentException("Failed to put: " + key + " -> " + value + ", " + bitIndex); } /** - * Adds the given {@link TrieEntry} to the {@link Trie} + * Adds the given {@link TrieEntry} to the {@link Trie}. */ TrieEntry addEntry(final TrieEntry entry, final int lengthInBits) { TrieEntry current = root.left; @@ -249,9 +229,6 @@ abstract class PatriciaTrieBase extends AbstractTrie { } } - /** - * {@inheritDoc} - */ @Override public V get(final Object k) { final TrieEntry entry = getEntry(k); @@ -262,7 +239,7 @@ abstract class PatriciaTrieBase extends AbstractTrie { * Returns the entry associated with the specified key in the * PatriciaTrieBase. Returns null if the map contains no mapping * for this key. - * + *

* This may throw ClassCastException if the object is not of type K. */ TrieEntry getEntry(final Object k) { @@ -276,39 +253,29 @@ abstract class PatriciaTrieBase extends AbstractTrie { return !entry.isEmpty() && compareKeys(key, entry.key) ? entry : null; } - /** - * {@inheritDoc} - */ public Map.Entry select(final K key) { final int lengthInBits = lengthInBits(key); - final Reference> reference - = new Reference>(); + final Reference> reference = new Reference>(); if (!selectR(root.left, -1, key, lengthInBits, reference)) { return reference.get(); } return null; } - /** - * {@inheritDoc} - */ public Map.Entry select(final K key, final Cursor cursor) { final int lengthInBits = lengthInBits(key); - final Reference> reference - = new Reference>(); + final Reference> reference = new Reference>(); selectR(root.left, -1, key, lengthInBits, cursor, reference); return reference.get(); } /** - * This is equivalent to the other {@link #selectR(TrieEntry, int, - * Object, int, Cursor, Reference)} method but without its overhead - * because we're selecting only one best matching Entry from the - * {@link Trie}. + * This is equivalent to the other {@link #selectR(TrieEntry, int, Object, int, Cursor, Reference)} + * method but without its overhead because we're selecting only one best matching Entry from the {@link Trie}. */ private boolean selectR(final TrieEntry h, final int bitIndex, - final K key, final int lengthInBits, - final Reference> reference) { + final K key, final int lengthInBits, + final Reference> reference) { if (h.bitIndex <= bitIndex) { // If we hit the root Node and it is empty @@ -333,9 +300,6 @@ abstract class PatriciaTrieBase extends AbstractTrie { return false; } - /** - * - */ private boolean selectR(final TrieEntry h, final int bitIndex, final K key, final int lengthInBits, @@ -379,9 +343,6 @@ abstract class PatriciaTrieBase extends AbstractTrie { return false; } - /** - * {@inheritDoc} - */ public Map.Entry traverse(final Cursor cursor) { TrieEntry entry = nextEntry(null); while (entry != null) { @@ -410,9 +371,6 @@ abstract class PatriciaTrieBase extends AbstractTrie { return null; } - /** - * {@inheritDoc} - */ @Override public boolean containsKey(final Object k) { if (k == null) { @@ -425,9 +383,6 @@ abstract class PatriciaTrieBase extends AbstractTrie { return !entry.isEmpty() && compareKeys(key, entry.key); } - /** - * {@inheritDoc} - */ @Override public Set> entrySet() { if (entrySet == null) { @@ -436,9 +391,6 @@ abstract class PatriciaTrieBase extends AbstractTrie { return entrySet; } - /** - * {@inheritDoc} - */ @Override public Set keySet() { if (keySet == null) { @@ -447,9 +399,6 @@ abstract class PatriciaTrieBase extends AbstractTrie { return keySet; } - /** - * {@inheritDoc} - */ @Override public Collection values() { if (values == null) { @@ -787,7 +736,7 @@ abstract class PatriciaTrieBase extends AbstractTrie { /** * Returns the first entry the {@link Trie} is storing. - * + *

* This is implemented by going always to the left until * we encounter a valid uplink. That uplink is the first key. */ @@ -847,7 +796,7 @@ abstract class PatriciaTrieBase extends AbstractTrie { } /** - * A {@link Trie} is a set of {@link TrieEntry} nodes + * A {@link Trie} is a set of {@link TrieEntry} nodes. */ static class TrieEntry extends BasicEntry { @@ -889,22 +838,19 @@ abstract class PatriciaTrieBase extends AbstractTrie { } /** - * Neither the left nor right child is a loopback + * Neither the left nor right child is a loopback. */ public boolean isInternalNode() { return left != this && right != this; } /** - * Either the left or right child is a loopback + * Either the left or right child is a loopback. */ public boolean isExternalNode() { return !isInternalNode(); } - /** - * {@inheritDoc} - */ @Override public String toString() { final StringBuilder buffer = new StringBuilder(); @@ -968,22 +914,15 @@ abstract class PatriciaTrieBase extends AbstractTrie { /** - * This is a entry set view of the {@link Trie} as returned - * by {@link Map#entrySet()} + * This is a entry set view of the {@link Trie} as returned by {@link Map#entrySet()}. */ private class EntrySet extends AbstractSet> { - /** - * {@inheritDoc} - */ @Override public Iterator> iterator() { return new EntryIterator(); } - /** - * {@inheritDoc} - */ @Override public boolean contains(final Object o) { if (!(o instanceof Map.Entry)) { @@ -994,9 +933,6 @@ abstract class PatriciaTrieBase extends AbstractTrie { return candidate != null && candidate.equals(o); } - /** - * {@inheritDoc} - */ @Override public boolean remove(final Object o) { final int size = size(); @@ -1004,24 +940,18 @@ abstract class PatriciaTrieBase extends AbstractTrie { return size != size(); } - /** - * {@inheritDoc} - */ @Override public int size() { return PatriciaTrieBase.this.size(); } - /** - * {@inheritDoc} - */ @Override public void clear() { PatriciaTrieBase.this.clear(); } /** - * An {@link Iterator} that returns {@link Entry} Objects + * An {@link Iterator} that returns {@link Entry} Objects. */ private class EntryIterator extends TrieIterator> { public Map.Entry next() { @@ -1031,38 +961,25 @@ abstract class PatriciaTrieBase extends AbstractTrie { } /** - * This is a key set view of the {@link Trie} as returned - * by {@link Map#keySet()} + * This is a key set view of the {@link Trie} as returned by {@link Map#keySet()}. */ private class KeySet extends AbstractSet { - /** - * {@inheritDoc} - */ @Override public Iterator iterator() { return new KeyIterator(); } - /** - * {@inheritDoc} - */ @Override public int size() { return PatriciaTrieBase.this.size(); } - /** - * {@inheritDoc} - */ @Override public boolean contains(final Object o) { return containsKey(o); } - /** - * {@inheritDoc} - */ @Override public boolean remove(final Object o) { final int size = size(); @@ -1070,16 +987,13 @@ abstract class PatriciaTrieBase extends AbstractTrie { return size != size(); } - /** - * {@inheritDoc} - */ @Override public void clear() { PatriciaTrieBase.this.clear(); } /** - * An {@link Iterator} that returns Key Objects + * An {@link Iterator} that returns Key Objects. */ private class KeyIterator extends TrieIterator { public K next() { @@ -1089,46 +1003,30 @@ abstract class PatriciaTrieBase extends AbstractTrie { } /** - * This is a value view of the {@link Trie} as returned - * by {@link Map#values()} + * This is a value view of the {@link Trie} as returned by {@link Map#values()}. */ private class Values extends AbstractCollection { - /** - * {@inheritDoc} - */ @Override public Iterator iterator() { return new ValueIterator(); } - /** - * {@inheritDoc} - */ @Override public int size() { return PatriciaTrieBase.this.size(); } - /** - * {@inheritDoc} - */ @Override public boolean contains(final Object o) { return containsValue(o); } - /** - * {@inheritDoc} - */ @Override public void clear() { PatriciaTrieBase.this.clear(); } - /** - * {@inheritDoc} - */ @Override public boolean remove(final Object o) { for (final Iterator it = iterator(); it.hasNext(); ) { @@ -1142,7 +1040,7 @@ abstract class PatriciaTrieBase extends AbstractTrie { } /** - * An {@link Iterator} that returns Value Objects + * An {@link Iterator} that returns Value Objects. */ private class ValueIterator extends TrieIterator { public V next() { @@ -1156,30 +1054,28 @@ abstract class PatriciaTrieBase extends AbstractTrie { */ abstract class TrieIterator implements Iterator { - /** - * For fast-fail - */ + /** For fast-fail. */ protected int expectedModCount = PatriciaTrieBase.this.modCount; protected TrieEntry next; // the next node to return protected TrieEntry current; // the current entry we're on /** - * Starts iteration from the root + * Starts iteration from the root. */ protected TrieIterator() { next = PatriciaTrieBase.this.nextEntry(null); } /** - * Starts iteration at the given entry + * Starts iteration at the given entry. */ protected TrieIterator(final TrieEntry firstEntry) { next = firstEntry; } /** - * Returns the next {@link TrieEntry} + * Returns the next {@link TrieEntry}. */ protected TrieEntry nextEntry() { if (expectedModCount != PatriciaTrieBase.this.modCount) { @@ -1203,16 +1099,10 @@ abstract class PatriciaTrieBase extends AbstractTrie { return PatriciaTrieBase.this.nextEntry(prior); } - /** - * {@inheritDoc} - */ public boolean hasNext() { return next != null; } - /** - * {@inheritDoc} - */ public void remove() { if (current == null) { throw new IllegalStateException(); diff --git a/src/main/java/org/apache/commons/collections4/trie/ByteArrayKeyAnalyzer.java b/src/main/java/org/apache/commons/collections4/trie/analyzer/ByteArrayKeyAnalyzer.java similarity index 82% rename from src/main/java/org/apache/commons/collections4/trie/ByteArrayKeyAnalyzer.java rename to src/main/java/org/apache/commons/collections4/trie/analyzer/ByteArrayKeyAnalyzer.java index f720b2dd8..f6df1df6f 100644 --- a/src/main/java/org/apache/commons/collections4/trie/ByteArrayKeyAnalyzer.java +++ b/src/main/java/org/apache/commons/collections4/trie/analyzer/ByteArrayKeyAnalyzer.java @@ -14,7 +14,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package org.apache.commons.collections4.trie; +package org.apache.commons.collections4.trie.analyzer; + +import org.apache.commons.collections4.trie.KeyAnalyzer; /** * A {@link KeyAnalyzer} for byte[]s. @@ -22,34 +24,23 @@ package org.apache.commons.collections4.trie; * @since 4.0 * @version $Id$ */ -public class ByteArrayKeyAnalyzer extends AbstractKeyAnalyzer { +public class ByteArrayKeyAnalyzer extends KeyAnalyzer { private static final long serialVersionUID = 7382825097492285877L; - /** - * A singleton instance of {@link ByteArrayKeyAnalyzer} - */ - public static final ByteArrayKeyAnalyzer INSTANCE - = new ByteArrayKeyAnalyzer(Integer.MAX_VALUE); + /** A singleton instance of {@link ByteArrayKeyAnalyzer}. */ + public static final ByteArrayKeyAnalyzer INSTANCE = new ByteArrayKeyAnalyzer(Integer.MAX_VALUE); - /** - * The length of an {@link Byte} in bits - */ + /** The length of an {@link Byte} in bits. */ public static final int LENGTH = Byte.SIZE; - /** - * A bit mask where the first bit is 1 and the others are zero - */ + /** A bit mask where the first bit is 1 and the others are zero. */ private static final int MSB = 0x80; - /** - * A place holder for null - */ + /** A place holder for null. */ private static final byte[] NULL = new byte[0]; - /** - * The maximum length of a key in bits - */ + /** The maximum length of a key in bits. */ private final int maxLengthInBits; public ByteArrayKeyAnalyzer(final int maxLengthInBits) { @@ -76,23 +67,14 @@ public class ByteArrayKeyAnalyzer extends AbstractKeyAnalyzer { return maxLengthInBits; } - /** - * {@inheritDoc} - */ public int bitsPerElement() { return LENGTH; } - /** - * {@inheritDoc} - */ public int lengthInBits(final byte[] key) { return key != null ? key.length * bitsPerElement() : 0; } - /** - * {@inheritDoc} - */ public boolean isBitSet(final byte[] key, final int bitIndex, final int lengthInBits) { if (key == null) { return false; @@ -110,11 +92,8 @@ public class ByteArrayKeyAnalyzer extends AbstractKeyAnalyzer { return (key[index] & mask(bit)) != 0; } - /** - * {@inheritDoc} - */ public int bitIndex(final byte[] key, final int offsetInBits, final int lengthInBits, - byte[] other, final int otherOffsetInBits, final int otherLengthInBits) { + byte[] other, final int otherOffsetInBits, final int otherLengthInBits) { if (other == null) { other = NULL; @@ -151,11 +130,7 @@ public class ByteArrayKeyAnalyzer extends AbstractKeyAnalyzer { return KeyAnalyzer.EQUAL_BIT_KEY; } - /** - * {@inheritDoc} - */ - public boolean isPrefix(final byte[] prefix, final int offsetInBits, - final int lengthInBits, final byte[] key) { + public boolean isPrefix(final byte[] prefix, final int offsetInBits, final int lengthInBits, final byte[] key) { final int keyLength = lengthInBits(key); if (lengthInBits > keyLength) { @@ -173,9 +148,6 @@ public class ByteArrayKeyAnalyzer extends AbstractKeyAnalyzer { return true; } - /** - * {@inheritDoc} - */ @Override public int compare(final byte[] o1, final byte[] o2) { if (o1 == null) { diff --git a/src/main/java/org/apache/commons/collections4/trie/ByteKeyAnalyzer.java b/src/main/java/org/apache/commons/collections4/trie/analyzer/ByteKeyAnalyzer.java similarity index 78% rename from src/main/java/org/apache/commons/collections4/trie/ByteKeyAnalyzer.java rename to src/main/java/org/apache/commons/collections4/trie/analyzer/ByteKeyAnalyzer.java index 8e390ecb5..1833f6258 100644 --- a/src/main/java/org/apache/commons/collections4/trie/ByteKeyAnalyzer.java +++ b/src/main/java/org/apache/commons/collections4/trie/analyzer/ByteKeyAnalyzer.java @@ -14,7 +14,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package org.apache.commons.collections4.trie; +package org.apache.commons.collections4.trie.analyzer; + +import org.apache.commons.collections4.trie.KeyAnalyzer; /** * A {@link KeyAnalyzer} for {@link Byte}s. @@ -22,58 +24,38 @@ package org.apache.commons.collections4.trie; * @since 4.0 * @version $Id$ */ -public class ByteKeyAnalyzer extends AbstractKeyAnalyzer { +public class ByteKeyAnalyzer extends KeyAnalyzer { private static final long serialVersionUID = 3395803342983289829L; - /** - * A singleton instance of {@link ByteKeyAnalyzer} - */ + /** A singleton instance of {@link ByteKeyAnalyzer}. */ public static final ByteKeyAnalyzer INSTANCE = new ByteKeyAnalyzer(); - /** - * The length of an {@link Byte} in bits - */ + /** The length of an {@link Byte} in bits. */ public static final int LENGTH = Byte.SIZE; - /** - * A bit mask where the first bit is 1 and the others are zero - */ + /** A bit mask where the first bit is 1 and the others are zero. */ private static final int MSB = 0x80; - /** - * Returns a bit mask where the given bit is set - */ + /** Returns a bit mask where the given bit is set. */ private static int mask(final int bit) { return MSB >>> bit; } - /** - * {@inheritDoc} - */ public int bitsPerElement() { return 1; } - /** - * {@inheritDoc} - */ public int lengthInBits(final Byte key) { return LENGTH; } - /** - * {@inheritDoc} - */ public boolean isBitSet(final Byte key, final int bitIndex, final int lengthInBits) { return (key.intValue() & mask(bitIndex)) != 0; } - /** - * {@inheritDoc} - */ public int bitIndex(final Byte key, final int offsetInBits, final int lengthInBits, - final Byte other, final int otherOffsetInBits, final int otherLengthInBits) { + final Byte other, final int otherOffsetInBits, final int otherLengthInBits) { if (offsetInBits != 0 || otherOffsetInBits != 0) { throw new IllegalArgumentException("offsetInBits=" + offsetInBits @@ -99,11 +81,7 @@ public class ByteKeyAnalyzer extends AbstractKeyAnalyzer { return KeyAnalyzer.EQUAL_BIT_KEY; } - /** - * {@inheritDoc} - */ - public boolean isPrefix(final Byte prefix, final int offsetInBits, - final int lengthInBits, final Byte key) { + public boolean isPrefix(final Byte prefix, final int offsetInBits, final int lengthInBits, final Byte key) { final int value1 = prefix.byteValue() << offsetInBits; final int value2 = key.byteValue(); diff --git a/src/main/java/org/apache/commons/collections4/trie/CharArrayKeyAnalyzer.java b/src/main/java/org/apache/commons/collections4/trie/analyzer/CharArrayKeyAnalyzer.java similarity index 84% rename from src/main/java/org/apache/commons/collections4/trie/CharArrayKeyAnalyzer.java rename to src/main/java/org/apache/commons/collections4/trie/analyzer/CharArrayKeyAnalyzer.java index 2ca1b57e1..5a432e190 100644 --- a/src/main/java/org/apache/commons/collections4/trie/CharArrayKeyAnalyzer.java +++ b/src/main/java/org/apache/commons/collections4/trie/analyzer/CharArrayKeyAnalyzer.java @@ -14,7 +14,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package org.apache.commons.collections4.trie; +package org.apache.commons.collections4.trie.analyzer; + +import org.apache.commons.collections4.trie.KeyAnalyzer; /** * An {@link KeyAnalyzer} for {@code char[]}s. @@ -22,51 +24,34 @@ package org.apache.commons.collections4.trie; * @since 4.0 * @version $Id$ */ -public class CharArrayKeyAnalyzer extends AbstractKeyAnalyzer { +public class CharArrayKeyAnalyzer extends KeyAnalyzer { private static final long serialVersionUID = -8167897361549463457L; - /** - * A singleton instance of {@link CharArrayKeyAnalyzer} - */ + /** A singleton instance of {@link CharArrayKeyAnalyzer}. */ public static final CharArrayKeyAnalyzer INSTANCE = new CharArrayKeyAnalyzer(); - /** - * The number of bits per {@link Character} - */ + /** The number of bits per {@link Character}. */ public static final int LENGTH = Character.SIZE; - /** - * A bit mask where the first bit is 1 and the others are zero - */ + /** A bit mask where the first bit is 1 and the others are zero. */ private static final int MSB = 0x8000; - /** - * Returns a bit mask where the given bit is set - */ + /** Returns a bit mask where the given bit is set. */ private static int mask(final int bit) { return MSB >>> bit; } - /** - * {@inheritDoc} - */ public int bitsPerElement() { return LENGTH; } - /** - * {@inheritDoc} - */ public int lengthInBits(final char[] key) { return key != null ? key.length * LENGTH : 0; } - /** - * {@inheritDoc} - */ public int bitIndex(final char[] key, final int offsetInBits, final int lengthInBits, - final char[] other, final int otherOffsetInBits, final int otherLengthInBits) { + final char[] other, final int otherOffsetInBits, final int otherLengthInBits) { boolean allNull = true; if (offsetInBits % LENGTH != 0 || otherOffsetInBits % LENGTH != 0 @@ -123,9 +108,6 @@ public class CharArrayKeyAnalyzer extends AbstractKeyAnalyzer { return KeyAnalyzer.EQUAL_BIT_KEY; } - /** - * {@inheritDoc} - */ public boolean isBitSet(final char[] key, final int bitIndex, final int lengthInBits) { if (key == null || bitIndex >= lengthInBits) { return false; @@ -137,11 +119,7 @@ public class CharArrayKeyAnalyzer extends AbstractKeyAnalyzer { return (key[index] & mask(bit)) != 0; } - /** - * {@inheritDoc} - */ - public boolean isPrefix(final char[] prefix, final int offsetInBits, - final int lengthInBits, final char[] key) { + public boolean isPrefix(final char[] prefix, final int offsetInBits, final int lengthInBits, final char[] key) { if (offsetInBits % LENGTH != 0 || lengthInBits % LENGTH != 0) { throw new IllegalArgumentException( "Cannot determine prefix outside of Character boundaries"); diff --git a/src/main/java/org/apache/commons/collections4/trie/CharacterKeyAnalyzer.java b/src/main/java/org/apache/commons/collections4/trie/analyzer/CharacterKeyAnalyzer.java similarity index 77% rename from src/main/java/org/apache/commons/collections4/trie/CharacterKeyAnalyzer.java rename to src/main/java/org/apache/commons/collections4/trie/analyzer/CharacterKeyAnalyzer.java index e1fed3ea2..dec38e5ef 100644 --- a/src/main/java/org/apache/commons/collections4/trie/CharacterKeyAnalyzer.java +++ b/src/main/java/org/apache/commons/collections4/trie/analyzer/CharacterKeyAnalyzer.java @@ -14,7 +14,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package org.apache.commons.collections4.trie; +package org.apache.commons.collections4.trie.analyzer; + +import org.apache.commons.collections4.trie.KeyAnalyzer; /** * A {@link KeyAnalyzer} for {@link Character}s. @@ -22,60 +24,39 @@ package org.apache.commons.collections4.trie; * @since 4.0 * @version $Id$ */ -public class CharacterKeyAnalyzer extends AbstractKeyAnalyzer { +public class CharacterKeyAnalyzer extends KeyAnalyzer { private static final long serialVersionUID = 3928565962744720753L; - /** - * A singleton instance of the {@link CharacterKeyAnalyzer}. - */ + /** A singleton instance of the {@link CharacterKeyAnalyzer}. */ public static final CharacterKeyAnalyzer INSTANCE = new CharacterKeyAnalyzer(); - /** - * The length of a {@link Character} in bits - */ + /** The length of a {@link Character} in bits. */ public static final int LENGTH = Character.SIZE; - /** - * A bit mask where the first bit is 1 and the others are zero - */ + /** A bit mask where the first bit is 1 and the others are zero. */ private static final int MSB = 0x8000; - /** - * Returns a bit mask where the given bit is set - */ + /** Returns a bit mask where the given bit is set. */ private static int mask(final int bit) { return MSB >>> bit; } - /** - * {@inheritDoc} - */ public int bitsPerElement() { return 1; } - /** - * {@inheritDoc} - */ public int lengthInBits(final Character key) { return LENGTH; } - /** - * {@inheritDoc} - * @throws NullPointerException if the key is null - */ public boolean isBitSet(final Character key, final int bitIndex, final int lengthInBits) { return (key.charValue() & mask(bitIndex)) != 0; } - /** - * {@inheritDoc} - */ public int bitIndex(final Character key, final int offsetInBits, final int lengthInBits, - final Character other, final int otherOffsetInBits, final int otherLengthInBits) { + final Character other, final int otherOffsetInBits, final int otherLengthInBits) { if (offsetInBits != 0 || otherOffsetInBits != 0) { throw new IllegalArgumentException("offsetInBits=" + offsetInBits @@ -101,11 +82,8 @@ public class CharacterKeyAnalyzer extends AbstractKeyAnalyzer { return KeyAnalyzer.EQUAL_BIT_KEY; } - /** - * {@inheritDoc} - */ public boolean isPrefix(final Character prefix, final int offsetInBits, - final int lengthInBits, final Character key) { + final int lengthInBits, final Character key) { final int value1 = prefix.charValue() << offsetInBits; final int value2 = key.charValue(); diff --git a/src/main/java/org/apache/commons/collections4/trie/IntegerKeyAnalyzer.java b/src/main/java/org/apache/commons/collections4/trie/analyzer/IntegerKeyAnalyzer.java similarity index 78% rename from src/main/java/org/apache/commons/collections4/trie/IntegerKeyAnalyzer.java rename to src/main/java/org/apache/commons/collections4/trie/analyzer/IntegerKeyAnalyzer.java index 76de15aa6..b9efa3a89 100644 --- a/src/main/java/org/apache/commons/collections4/trie/IntegerKeyAnalyzer.java +++ b/src/main/java/org/apache/commons/collections4/trie/analyzer/IntegerKeyAnalyzer.java @@ -14,7 +14,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package org.apache.commons.collections4.trie; +package org.apache.commons.collections4.trie.analyzer; + +import org.apache.commons.collections4.trie.KeyAnalyzer; /** * A {@link KeyAnalyzer} for {@link Integer}s. @@ -22,58 +24,38 @@ package org.apache.commons.collections4.trie; * @since 4.0 * @version $Id$ */ -public class IntegerKeyAnalyzer extends AbstractKeyAnalyzer { +public class IntegerKeyAnalyzer extends KeyAnalyzer { private static final long serialVersionUID = 4928508653722068982L; - /** - * A singleton instance of {@link IntegerKeyAnalyzer} - */ + /** A singleton instance of {@link IntegerKeyAnalyzer}. */ public static final IntegerKeyAnalyzer INSTANCE = new IntegerKeyAnalyzer(); - /** - * The length of an {@link Integer} in bits - */ + /** The length of an {@link Integer} in bits. */ public static final int LENGTH = Integer.SIZE; - /** - * A bit mask where the first bit is 1 and the others are zero - */ + /** A bit mask where the first bit is 1 and the others are zero. */ private static final int MSB = 0x80000000; - /** - * Returns a bit mask where the given bit is set - */ + /** Returns a bit mask where the given bit is set. */ private static int mask(final int bit) { return MSB >>> bit; } - /** - * {@inheritDoc} - */ public int bitsPerElement() { return 1; } - /** - * {@inheritDoc} - */ public int lengthInBits(final Integer key) { return LENGTH; } - /** - * {@inheritDoc} - */ public boolean isBitSet(final Integer key, final int bitIndex, final int lengthInBits) { return (key.intValue() & mask(bitIndex)) != 0; } - /** - * {@inheritDoc} - */ public int bitIndex(final Integer key, final int offsetInBits, final int lengthInBits, - final Integer other, final int otherOffsetInBits, final int otherLengthInBits) { + final Integer other, final int otherOffsetInBits, final int otherLengthInBits) { if (offsetInBits != 0 || otherOffsetInBits != 0) { throw new IllegalArgumentException("offsetInBits=" + offsetInBits @@ -99,11 +81,8 @@ public class IntegerKeyAnalyzer extends AbstractKeyAnalyzer { return KeyAnalyzer.EQUAL_BIT_KEY; } - /** - * {@inheritDoc} - */ public boolean isPrefix(final Integer prefix, final int offsetInBits, - final int lengthInBits, final Integer key) { + final int lengthInBits, final Integer key) { final int value1 = prefix.intValue() << offsetInBits; final int value2 = key.intValue(); diff --git a/src/main/java/org/apache/commons/collections4/trie/LongKeyAnalyzer.java b/src/main/java/org/apache/commons/collections4/trie/analyzer/LongKeyAnalyzer.java similarity index 78% rename from src/main/java/org/apache/commons/collections4/trie/LongKeyAnalyzer.java rename to src/main/java/org/apache/commons/collections4/trie/analyzer/LongKeyAnalyzer.java index 75f29b282..82f6b0f5c 100644 --- a/src/main/java/org/apache/commons/collections4/trie/LongKeyAnalyzer.java +++ b/src/main/java/org/apache/commons/collections4/trie/analyzer/LongKeyAnalyzer.java @@ -14,7 +14,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package org.apache.commons.collections4.trie; +package org.apache.commons.collections4.trie.analyzer; + +import org.apache.commons.collections4.trie.KeyAnalyzer; /** * A {@link KeyAnalyzer} for {@link Long}s. @@ -22,58 +24,38 @@ package org.apache.commons.collections4.trie; * @since 4.0 * @version $Id$ */ -public class LongKeyAnalyzer extends AbstractKeyAnalyzer { +public class LongKeyAnalyzer extends KeyAnalyzer { private static final long serialVersionUID = -4119639247588227409L; - /** - * A singleton instance of {@link LongKeyAnalyzer} - */ + /** A singleton instance of {@link LongKeyAnalyzer}. */ public static final LongKeyAnalyzer INSTANCE = new LongKeyAnalyzer(); - /** - * The length of an {@link Long} in bits - */ + /** The length of an {@link Long} in bits. */ public static final int LENGTH = Long.SIZE; - /** - * A bit mask where the first bit is 1 and the others are zero - */ + /** A bit mask where the first bit is 1 and the others are zero. */ private static final long MSB = 0x8000000000000000L; - /** - * Returns a bit mask where the given bit is set - */ + /** Returns a bit mask where the given bit is set. */ private static long mask(final int bit) { return MSB >>> bit; } - /** - * {@inheritDoc} - */ public int bitsPerElement() { return 1; } - /** - * {@inheritDoc} - */ public int lengthInBits(final Long key) { return LENGTH; } - /** - * {@inheritDoc} - */ public boolean isBitSet(final Long key, final int bitIndex, final int lengthInBits) { return (key.longValue() & mask(bitIndex)) != 0; } - /** - * {@inheritDoc} - */ public int bitIndex(final Long key, final int offsetInBits, final int lengthInBits, - final Long other, final int otherOffsetInBits, final int otherLengthInBits) { + final Long other, final int otherOffsetInBits, final int otherLengthInBits) { if (offsetInBits != 0 || otherOffsetInBits != 0) { throw new IllegalArgumentException("offsetInBits=" + offsetInBits @@ -99,11 +81,8 @@ public class LongKeyAnalyzer extends AbstractKeyAnalyzer { return KeyAnalyzer.EQUAL_BIT_KEY; } - /** - * {@inheritDoc} - */ public boolean isPrefix(final Long prefix, final int offsetInBits, - final int lengthInBits, final Long key) { + final int lengthInBits, final Long key) { final long value1 = prefix.longValue() << offsetInBits; final long value2 = key.longValue(); diff --git a/src/main/java/org/apache/commons/collections4/trie/ShortKeyAnalyzer.java b/src/main/java/org/apache/commons/collections4/trie/analyzer/ShortKeyAnalyzer.java similarity index 78% rename from src/main/java/org/apache/commons/collections4/trie/ShortKeyAnalyzer.java rename to src/main/java/org/apache/commons/collections4/trie/analyzer/ShortKeyAnalyzer.java index 9e923c040..5a97f1ff0 100644 --- a/src/main/java/org/apache/commons/collections4/trie/ShortKeyAnalyzer.java +++ b/src/main/java/org/apache/commons/collections4/trie/analyzer/ShortKeyAnalyzer.java @@ -14,7 +14,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package org.apache.commons.collections4.trie; +package org.apache.commons.collections4.trie.analyzer; + +import org.apache.commons.collections4.trie.KeyAnalyzer; /** * A {@link KeyAnalyzer} for {@link Short}s. @@ -22,58 +24,38 @@ package org.apache.commons.collections4.trie; * @since 4.0 * @version $Id$ */ -public class ShortKeyAnalyzer implements KeyAnalyzer { +public class ShortKeyAnalyzer extends KeyAnalyzer { private static final long serialVersionUID = -8631376733513512017L; - /** - * A singleton instance of {@link ShortKeyAnalyzer} - */ + /** A singleton instance of {@link ShortKeyAnalyzer}. */ public static final ShortKeyAnalyzer INSTANCE = new ShortKeyAnalyzer(); - /** - * The length of an {@link Short} in bits - */ + /** The length of an {@link Short} in bits. */ public static final int LENGTH = Short.SIZE; - /** - * A bit mask where the first bit is 1 and the others are zero - */ + /** A bit mask where the first bit is 1 and the others are zero. */ private static final int MSB = 0x8000; - /** - * Returns a bit mask where the given bit is set - */ + /** Returns a bit mask where the given bit is set. */ private static int mask(final int bit) { return MSB >>> bit; } - /** - * {@inheritDoc} - */ public int bitsPerElement() { return 1; } - /** - * {@inheritDoc} - */ public int lengthInBits(final Short key) { return LENGTH; } - /** - * {@inheritDoc} - */ public boolean isBitSet(final Short key, final int bitIndex, final int lengthInBits) { return (key.intValue() & mask(bitIndex)) != 0; } - /** - * {@inheritDoc} - */ public int bitIndex(final Short key, final int offsetInBits, final int lengthInBits, - final Short other, final int otherOffsetInBits, final int otherLengthInBits) { + final Short other, final int otherOffsetInBits, final int otherLengthInBits) { if (offsetInBits != 0 || otherOffsetInBits != 0) { throw new IllegalArgumentException("offsetInBits=" + offsetInBits @@ -99,18 +81,8 @@ public class ShortKeyAnalyzer implements KeyAnalyzer { return KeyAnalyzer.EQUAL_BIT_KEY; } - /** - * {@inheritDoc} - */ - public int compare(final Short o1, final Short o2) { - return o1.compareTo(o2); - } - - /** - * {@inheritDoc} - */ public boolean isPrefix(final Short prefix, final int offsetInBits, - final int lengthInBits, final Short key) { + final int lengthInBits, final Short key) { final int value1 = prefix.shortValue() << offsetInBits; final int value2 = key.shortValue(); @@ -122,4 +94,10 @@ public class ShortKeyAnalyzer implements KeyAnalyzer { return (value1 & mask) == (value2 & mask); } + + @Override + public int compare(final Short o1, final Short o2) { + return o1.compareTo(o2); + } + } diff --git a/src/main/java/org/apache/commons/collections4/trie/StringKeyAnalyzer.java b/src/main/java/org/apache/commons/collections4/trie/analyzer/StringKeyAnalyzer.java similarity index 81% rename from src/main/java/org/apache/commons/collections4/trie/StringKeyAnalyzer.java rename to src/main/java/org/apache/commons/collections4/trie/analyzer/StringKeyAnalyzer.java index 206238efb..07f9b53b9 100644 --- a/src/main/java/org/apache/commons/collections4/trie/StringKeyAnalyzer.java +++ b/src/main/java/org/apache/commons/collections4/trie/analyzer/StringKeyAnalyzer.java @@ -14,7 +14,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package org.apache.commons.collections4.trie; +package org.apache.commons.collections4.trie.analyzer; + +import org.apache.commons.collections4.trie.KeyAnalyzer; /** * An {@link KeyAnalyzer} for {@link String}s. @@ -22,60 +24,42 @@ package org.apache.commons.collections4.trie; * @since 4.0 * @version $Id$ */ -public class StringKeyAnalyzer extends AbstractKeyAnalyzer { +public class StringKeyAnalyzer extends KeyAnalyzer { private static final long serialVersionUID = -7032449491269434877L; - /** - * A singleton instance of {@link StringKeyAnalyzer} - */ + /** A singleton instance of {@link StringKeyAnalyzer}. */ public static final StringKeyAnalyzer INSTANCE = new StringKeyAnalyzer(); - /** - * The number of bits per {@link Character} - */ + /** The number of bits per {@link Character}. */ public static final int LENGTH = Character.SIZE; - /** - * A bit mask where the first bit is 1 and the others are zero - */ + /** A bit mask where the first bit is 1 and the others are zero. */ private static final int MSB = 0x8000; - /** - * Returns a bit mask where the given bit is set - */ + /** Returns a bit mask where the given bit is set. */ private static int mask(final int bit) { return MSB >>> bit; } - /** - * {@inheritDoc} - */ public int bitsPerElement() { return LENGTH; } - /** - * {@inheritDoc} - */ public int lengthInBits(final String key) { return key != null ? key.length() * LENGTH : 0; } - /** - * {@inheritDoc} - */ public int bitIndex(final String key, final int offsetInBits, final int lengthInBits, - final String other, final int otherOffsetInBits, final int otherLengthInBits) { + final String other, final int otherOffsetInBits, final int otherLengthInBits) { + boolean allNull = true; if (offsetInBits % LENGTH != 0 || otherOffsetInBits % LENGTH != 0 || lengthInBits % LENGTH != 0 || otherLengthInBits % LENGTH != 0) { - throw new IllegalArgumentException( - "The offsets and lengths must be at Character boundaries"); + throw new IllegalArgumentException("The offsets and lengths must be at Character boundaries"); } - final int beginIndex1 = offsetInBits / LENGTH; final int beginIndex2 = otherOffsetInBits / LENGTH; @@ -123,9 +107,6 @@ public class StringKeyAnalyzer extends AbstractKeyAnalyzer { return KeyAnalyzer.EQUAL_BIT_KEY; } - /** - * {@inheritDoc} - */ public boolean isBitSet(final String key, final int bitIndex, final int lengthInBits) { if (key == null || bitIndex >= lengthInBits) { return false; @@ -137,11 +118,8 @@ public class StringKeyAnalyzer extends AbstractKeyAnalyzer { return (key.charAt(index) & mask(bit)) != 0; } - /** - * {@inheritDoc} - */ public boolean isPrefix(final String prefix, final int offsetInBits, - final int lengthInBits, final String key) { + final int lengthInBits, final String key) { if (offsetInBits % LENGTH != 0 || lengthInBits % LENGTH != 0) { throw new IllegalArgumentException( "Cannot determine prefix outside of Character boundaries"); diff --git a/src/main/java/org/apache/commons/collections4/trie/analyzer/package-info.java b/src/main/java/org/apache/commons/collections4/trie/analyzer/package-info.java new file mode 100644 index 000000000..953edda21 --- /dev/null +++ b/src/main/java/org/apache/commons/collections4/trie/analyzer/package-info.java @@ -0,0 +1,22 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 at + * + * 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. + */ +/** + * This package contains various {@link org.apache.commons.collections4.trie.KeyAnalyzer} implementations. + * + * @version $Id$ + */ +package org.apache.commons.collections4.trie.analyzer; diff --git a/src/test/java/org/apache/commons/collections4/trie/PatriciaTrieTest.java b/src/test/java/org/apache/commons/collections4/trie/PatriciaTrieTest.java index e502f5938..9684b4e0c 100755 --- a/src/test/java/org/apache/commons/collections4/trie/PatriciaTrieTest.java +++ b/src/test/java/org/apache/commons/collections4/trie/PatriciaTrieTest.java @@ -34,6 +34,9 @@ import java.util.TreeMap; import java.util.Map.Entry; import org.apache.commons.collections4.Trie.Cursor; +import org.apache.commons.collections4.trie.analyzer.CharacterKeyAnalyzer; +import org.apache.commons.collections4.trie.analyzer.IntegerKeyAnalyzer; +import org.apache.commons.collections4.trie.analyzer.StringKeyAnalyzer; import org.junit.Assert; import org.junit.Test; @@ -1079,6 +1082,7 @@ public class PatriciaTrieTest { } } + @SuppressWarnings("unused") void selectFor(final Object object) { selectFor = object; } diff --git a/src/test/java/org/apache/commons/collections4/trie/ByteArrayKeyAnalyzerTest.java b/src/test/java/org/apache/commons/collections4/trie/analyzer/ByteArrayKeyAnalyzerTest.java similarity index 95% rename from src/test/java/org/apache/commons/collections4/trie/ByteArrayKeyAnalyzerTest.java rename to src/test/java/org/apache/commons/collections4/trie/analyzer/ByteArrayKeyAnalyzerTest.java index 4abd6f6dd..0da5a819b 100644 --- a/src/test/java/org/apache/commons/collections4/trie/ByteArrayKeyAnalyzerTest.java +++ b/src/test/java/org/apache/commons/collections4/trie/analyzer/ByteArrayKeyAnalyzerTest.java @@ -14,12 +14,14 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package org.apache.commons.collections4.trie; +package org.apache.commons.collections4.trie.analyzer; import java.math.BigInteger; import java.util.Map; import java.util.TreeMap; +import org.apache.commons.collections4.trie.PatriciaTrie; +import org.apache.commons.collections4.trie.analyzer.ByteArrayKeyAnalyzer; import org.junit.Assert; import org.junit.Test;