From 222ea958352dc191a3684e23e526c2289c24582d Mon Sep 17 00:00:00 2001 From: Dave Brosius Date: Wed, 21 Jan 2015 21:40:21 -0500 Subject: [PATCH] minor javadoc fixes --- build.xml | 1 - src/java/org/apache/cassandra/auth/IAuthorizer.java | 4 ++-- .../apache/cassandra/cql3/MultiColumnRelation.java | 4 ++++ src/java/org/apache/cassandra/cql3/Tuples.java | 4 ++++ .../cassandra/cql3/statements/RequestValidations.java | 6 ++---- .../org/apache/cassandra/db/AbstractNativeCell.java | 4 ++++ .../org/apache/cassandra/db/AtomicBTreeColumns.java | 3 ++- .../cassandra/db/compaction/CompactionManager.java | 6 ++++-- .../org/apache/cassandra/gms/IFailureDetector.java | 4 ++-- src/java/org/apache/cassandra/gms/VersionedValue.java | 8 ++++++-- .../cassandra/hadoop/cql3/CqlBulkRecordWriter.java | 1 + .../apache/cassandra/hadoop/cql3/CqlRecordReader.java | 8 ++++++-- .../org/apache/cassandra/io/sstable/Component.java | 2 ++ .../cassandra/io/util/FastByteArrayOutputStream.java | 2 +- .../apache/cassandra/locator/CloudstackSnitch.java | 2 ++ .../cassandra/locator/NetworkTopologyStrategy.java | 6 ++++-- .../apache/cassandra/locator/PropertyFileSnitch.java | 3 ++- .../org/apache/cassandra/service/StorageProxy.java | 7 +++++-- .../org/apache/cassandra/tools/SSTableExport.java | 1 - .../org/apache/cassandra/tools/SSTableImport.java | 1 - .../cassandra/tools/SSTableRepairedAtSetter.java | 3 ++- .../apache/cassandra/utils/concurrent/OpOrder.java | 2 ++ .../org/apache/cassandra/utils/obs/OpenBitSet.java | 11 ++++++++--- 23 files changed, 65 insertions(+), 28 deletions(-) diff --git a/build.xml b/build.xml index fccd009299..353eefd8e4 100644 --- a/build.xml +++ b/build.xml @@ -447,7 +447,6 @@ artifactId="cassandra-parent" version="${version}"/> - diff --git a/src/java/org/apache/cassandra/auth/IAuthorizer.java b/src/java/org/apache/cassandra/auth/IAuthorizer.java index 7e3240ac8e..0aaebcfb07 100644 --- a/src/java/org/apache/cassandra/auth/IAuthorizer.java +++ b/src/java/org/apache/cassandra/auth/IAuthorizer.java @@ -48,8 +48,8 @@ public interface IAuthorizer * * @param performer User who grants the permissions. * @param permissions Set of permissions to grant. - * @param to Name of the role to which the permissions are to be granted. * @param resource Resource on which to grant the permissions. + * @param grantee name of the role to which the permissions are to be granted. * * @throws RequestValidationException * @throws RequestExecutionException @@ -80,7 +80,7 @@ public interface IAuthorizer * matching ones. * @param resource The resource on which permissions are requested. Can be null, in which case permissions on all * resources should be returned. - * @param of The name of the role whose permissions are requested. Can be null, in which case permissions of every + * @param grantee The name of the role whose permissions are requested. Can be null, in which case permissions of every * role should be returned. * * @return All of the matching permission that the requesting user is authorized to know about. diff --git a/src/java/org/apache/cassandra/cql3/MultiColumnRelation.java b/src/java/org/apache/cassandra/cql3/MultiColumnRelation.java index d754968332..7e7a90126d 100644 --- a/src/java/org/apache/cassandra/cql3/MultiColumnRelation.java +++ b/src/java/org/apache/cassandra/cql3/MultiColumnRelation.java @@ -36,10 +36,12 @@ import static org.apache.cassandra.cql3.statements.RequestValidations.invalidReq /** * A relation using the tuple notation, which typically affects multiple columns. * Examples: + * {@code * - SELECT ... WHERE (a, b, c) > (1, 'a', 10) * - SELECT ... WHERE (a, b, c) IN ((1, 2, 3), (4, 5, 6)) * - SELECT ... WHERE (a, b) < ? * - SELECT ... WHERE (a, b) IN ? + * } */ public class MultiColumnRelation extends Relation { @@ -65,7 +67,9 @@ public class MultiColumnRelation extends Relation /** * Creates a multi-column EQ, LT, LTE, GT, or GTE relation. + * {@code * For example: "SELECT ... WHERE (a, b) > (0, 1)" + * } * @param entities the columns on the LHS of the relation * @param relationType the relation operator * @param valuesOrMarker a Tuples.Literal instance or a Tuples.Raw marker diff --git a/src/java/org/apache/cassandra/cql3/Tuples.java b/src/java/org/apache/cassandra/cql3/Tuples.java index a66c534988..ca436a11dc 100644 --- a/src/java/org/apache/cassandra/cql3/Tuples.java +++ b/src/java/org/apache/cassandra/cql3/Tuples.java @@ -277,7 +277,9 @@ public class Tuples /** * A raw placeholder for a tuple of values for different multiple columns, each of which may have a different type. + * {@code * For example, "SELECT ... WHERE (col1, col2) > ?". + * } */ public static class Raw extends AbstractMarker.Raw implements Term.MultiColumnRaw { @@ -363,7 +365,9 @@ public class Tuples } /** + * {@code * Represents a marker for a single tuple, like "SELECT ... WHERE (a, b, c) > ?" + * } */ public static class Marker extends AbstractMarker { diff --git a/src/java/org/apache/cassandra/cql3/statements/RequestValidations.java b/src/java/org/apache/cassandra/cql3/statements/RequestValidations.java index ce15e159ef..c822325df3 100644 --- a/src/java/org/apache/cassandra/cql3/statements/RequestValidations.java +++ b/src/java/org/apache/cassandra/cql3/statements/RequestValidations.java @@ -35,8 +35,7 @@ public final class RequestValidations * be thrown. * * @param expression the expression to test - * @param messageTemplate the error message - * @param messageArgs the message arguments + * @param message the error message * @throws InvalidRequestException if the specified expression is false. */ public static void checkTrue(boolean expression, String message) throws InvalidRequestException @@ -66,8 +65,7 @@ public final class RequestValidations * Checks that the specified list does not contains duplicates. * * @param list the list to test - * @param messageTemplate the template used to build the error message - * @param messageArgs the message arguments + * @param message the error message * @throws InvalidRequestException if the specified list contains duplicates. */ public static void checkContainsNoDuplicates(List list, String message) throws InvalidRequestException diff --git a/src/java/org/apache/cassandra/db/AbstractNativeCell.java b/src/java/org/apache/cassandra/db/AbstractNativeCell.java index e01d860e69..207a972b4c 100644 --- a/src/java/org/apache/cassandra/db/AbstractNativeCell.java +++ b/src/java/org/apache/cassandra/db/AbstractNativeCell.java @@ -37,6 +37,8 @@ import org.apache.cassandra.utils.memory.*; /** + * 
+ * {@code
  * Packs a CellName AND a Cell into one off-heap representation.
  * Layout is:
  *
@@ -55,6 +57,8 @@ import org.apache.cassandra.utils.memory.*;
  * name extra:  lowest 2 bits indicate the clustering size delta (i.e. how many name items are NOT part of the clustering key)
  *              the next 2 bits indicate the CellNameType
  *              the next bit indicates if the column is a static or clustered/dynamic column
+ * }
+ *
*/ public abstract class AbstractNativeCell extends AbstractCell implements CellName { diff --git a/src/java/org/apache/cassandra/db/AtomicBTreeColumns.java b/src/java/org/apache/cassandra/db/AtomicBTreeColumns.java index 0f083e3746..0b1a58c5fe 100644 --- a/src/java/org/apache/cassandra/db/AtomicBTreeColumns.java +++ b/src/java/org/apache/cassandra/db/AtomicBTreeColumns.java @@ -55,8 +55,9 @@ import static org.apache.cassandra.db.index.SecondaryIndexManager.Updater; * isolated (in the sense of ACID). Typically a addAll is guaranteed that no * other thread can see the state where only parts but not all columns have * been added. - *

+ *

* WARNING: removing element through getSortedColumns().iterator() is *not* supported + *

*/ public class AtomicBTreeColumns extends ColumnFamily { diff --git a/src/java/org/apache/cassandra/db/compaction/CompactionManager.java b/src/java/org/apache/cassandra/db/compaction/CompactionManager.java index 1e06f5e38c..7b45dd351d 100644 --- a/src/java/org/apache/cassandra/db/compaction/CompactionManager.java +++ b/src/java/org/apache/cassandra/db/compaction/CompactionManager.java @@ -85,8 +85,9 @@ import org.apache.cassandra.utils.concurrent.OpOrder; import org.apache.cassandra.utils.*; /** + *

* A singleton which manages a private executor of ongoing compactions. - *

+ *

* Scheduling for compaction is accomplished by swapping sstables to be compacted into * a set via DataTracker. New scheduling attempts will ignore currently compacting * sstables. @@ -411,7 +412,8 @@ public class CompactionManager implements CompactionManagerMBean * @param cfs * @param ranges Ranges that the repair was carried out on * @param validatedForRepair SSTables containing the repaired ranges. Should be referenced before passing them. - * @throws InterruptedException, ExecutionException, IOException + * @throws InterruptedException + * @throws IOException */ public void performAnticompaction(ColumnFamilyStore cfs, Collection> ranges, diff --git a/src/java/org/apache/cassandra/gms/IFailureDetector.java b/src/java/org/apache/cassandra/gms/IFailureDetector.java index 92338e9e89..a860c7cc3a 100644 --- a/src/java/org/apache/cassandra/gms/IFailureDetector.java +++ b/src/java/org/apache/cassandra/gms/IFailureDetector.java @@ -41,7 +41,7 @@ public interface IFailureDetector * This method is invoked by any entity wanting to interrogate the status of an endpoint. * In our case it would be the Gossiper. The Failure Detector will then calculate Phi and * deem an endpoint as suspicious or alive as explained in the Hayashibara paper. - *

+ * * param ep endpoint for which we interpret the inter arrival times. */ public void interpret(InetAddress ep); @@ -50,7 +50,7 @@ public interface IFailureDetector * This method is invoked by the receiver of the heartbeat. In our case it would be * the Gossiper. Gossiper inform the Failure Detector on receipt of a heartbeat. The * FailureDetector will then sample the arrival time as explained in the paper. - *

+ * * param ep endpoint being reported. */ public void report(InetAddress ep); diff --git a/src/java/org/apache/cassandra/gms/VersionedValue.java b/src/java/org/apache/cassandra/gms/VersionedValue.java index a779982bd2..e8cf748d8e 100644 --- a/src/java/org/apache/cassandra/gms/VersionedValue.java +++ b/src/java/org/apache/cassandra/gms/VersionedValue.java @@ -43,11 +43,15 @@ import org.apache.commons.lang3.StringUtils; * application wants to make available to the rest of the nodes in the cluster. * Whenever a piece of state needs to be disseminated to the rest of cluster wrap * the state in an instance of ApplicationState and add it to the Gossiper. - *

+ *

* e.g. if we want to disseminate load information for node A do the following: - *

+ *

+ * 
+ * {@code
  * ApplicationState loadState = new ApplicationState();
  * Gossiper.instance.addApplicationState("LOAD STATE", loadState);
+ * }
+ *
*/ public class VersionedValue implements Comparable diff --git a/src/java/org/apache/cassandra/hadoop/cql3/CqlBulkRecordWriter.java b/src/java/org/apache/cassandra/hadoop/cql3/CqlBulkRecordWriter.java index ebae7a4f94..60cd5118c1 100644 --- a/src/java/org/apache/cassandra/hadoop/cql3/CqlBulkRecordWriter.java +++ b/src/java/org/apache/cassandra/hadoop/cql3/CqlBulkRecordWriter.java @@ -136,6 +136,7 @@ public class CqlBulkRecordWriter extends AbstractBulkRecordWriter * The column values must correspond to the order in which * they appear in the insert stored procedure. * diff --git a/src/java/org/apache/cassandra/hadoop/cql3/CqlRecordReader.java b/src/java/org/apache/cassandra/hadoop/cql3/CqlRecordReader.java index be257c8389..affae5ab53 100644 --- a/src/java/org/apache/cassandra/hadoop/cql3/CqlRecordReader.java +++ b/src/java/org/apache/cassandra/hadoop/cql3/CqlRecordReader.java @@ -57,15 +57,19 @@ import org.apache.hadoop.mapreduce.RecordReader; import org.apache.hadoop.mapreduce.TaskAttemptContext; /** + *

* CqlRecordReader reads the rows return from the CQL query * It uses CQL auto-paging. - *

+ *

+ *

* Return a Long as a local CQL row key starts from 0; - *

+ *

+ * {@code * Row as C* java driver CQL result set row * 1) select clause must include partition key columns (to calculate the progress based on the actual CF row processed) * 2) where clause must include token(partition_key1, ... , partition_keyn) > ? and * token(partition_key1, ... , partition_keyn) <= ? (in the right order) + * } */ public class CqlRecordReader extends RecordReader implements org.apache.hadoop.mapred.RecordReader, AutoCloseable diff --git a/src/java/org/apache/cassandra/io/sstable/Component.java b/src/java/org/apache/cassandra/io/sstable/Component.java index 3eacd0796d..7f6cc7984f 100644 --- a/src/java/org/apache/cassandra/io/sstable/Component.java +++ b/src/java/org/apache/cassandra/io/sstable/Component.java @@ -111,7 +111,9 @@ public class Component } /** + * {@code * Filename of the form "/-[tmp-][-]-", + * } * @return A Descriptor for the SSTable, and a Component for this particular file. * TODO move descriptor into Component field */ diff --git a/src/java/org/apache/cassandra/io/util/FastByteArrayOutputStream.java b/src/java/org/apache/cassandra/io/util/FastByteArrayOutputStream.java index c831508a16..0e509b3ea5 100644 --- a/src/java/org/apache/cassandra/io/util/FastByteArrayOutputStream.java +++ b/src/java/org/apache/cassandra/io/util/FastByteArrayOutputStream.java @@ -72,7 +72,7 @@ public class FastByteArrayOutputStream extends OutputStream { * initial size for the underlying byte array, must be * non-negative. * @throws IllegalArgumentException - * if {@code size} < 0. + * if {@code size < 0}. */ public FastByteArrayOutputStream(int size) { if (size >= 0) { diff --git a/src/java/org/apache/cassandra/locator/CloudstackSnitch.java b/src/java/org/apache/cassandra/locator/CloudstackSnitch.java index 4771f6bb70..afcd083b96 100644 --- a/src/java/org/apache/cassandra/locator/CloudstackSnitch.java +++ b/src/java/org/apache/cassandra/locator/CloudstackSnitch.java @@ -44,9 +44,11 @@ import org.apache.cassandra.utils.FBUtilities; import org.apache.cassandra.utils.JVMStabilityInspector; /** + * {@code * A snitch that assumes a Cloudstack Zone follows the typical convention * -- and uses the country/location * tuple as a datacenter and the availability zone as a rack + * } */ public class CloudstackSnitch extends AbstractNetworkTopologySnitch diff --git a/src/java/org/apache/cassandra/locator/NetworkTopologyStrategy.java b/src/java/org/apache/cassandra/locator/NetworkTopologyStrategy.java index 5e5ecb78ba..b0d540cb18 100644 --- a/src/java/org/apache/cassandra/locator/NetworkTopologyStrategy.java +++ b/src/java/org/apache/cassandra/locator/NetworkTopologyStrategy.java @@ -32,15 +32,17 @@ import org.apache.cassandra.utils.FBUtilities; import com.google.common.collect.Multimap; /** + *

* This Replication Strategy takes a property file that gives the intended * replication factor in each datacenter. The sum total of the datacenter * replication factor values should be equal to the keyspace replication * factor. - *

+ *

+ *

* So for example, if the keyspace replication factor is 6, the * datacenter replication factors could be 3, 2, and 1 - so 3 replicas in * one datacenter, 2 in another, and 1 in another - totalling 6. - *

+ *

* This class also caches the Endpoints and invalidates the cache if there is a * change in the number of tokens. */ diff --git a/src/java/org/apache/cassandra/locator/PropertyFileSnitch.java b/src/java/org/apache/cassandra/locator/PropertyFileSnitch.java index a8b26d8d50..247eb00864 100644 --- a/src/java/org/apache/cassandra/locator/PropertyFileSnitch.java +++ b/src/java/org/apache/cassandra/locator/PropertyFileSnitch.java @@ -37,8 +37,9 @@ import org.apache.cassandra.utils.WrappedRunnable; import org.apache.commons.lang3.StringUtils; /** + *

* Used to determine if two IP's are in the same datacenter or on the same rack. - *

+ *

* Based on a properties file in the following format: * * 10.0.0.13=DC1:RAC2 diff --git a/src/java/org/apache/cassandra/service/StorageProxy.java b/src/java/org/apache/cassandra/service/StorageProxy.java index 39b21e7e1b..cf9990b635 100644 --- a/src/java/org/apache/cassandra/service/StorageProxy.java +++ b/src/java/org/apache/cassandra/service/StorageProxy.java @@ -831,13 +831,16 @@ public class StorageProxy implements StorageProxyMBean * is not available. * * Note about hints: - * + * 
+     * {@code
      * | Hinted Handoff | Consist. Level |
      * | on             |       >=1      | --> wait for hints. We DO NOT notify the handler with handler.response() for hints;
      * | on             |       ANY      | --> wait for hints. Responses count towards consistency.
      * | off            |       >=1      | --> DO NOT fire hints. And DO NOT wait for them to complete.
      * | off            |       ANY      | --> DO NOT fire hints. And DO NOT wait for them to complete.
-     *
+     * }
+     *
+ * * @throws OverloadedException if the hints cannot be written/enqueued */ public static void sendToHintedEndpoints(final Mutation mutation, diff --git a/src/java/org/apache/cassandra/tools/SSTableExport.java b/src/java/org/apache/cassandra/tools/SSTableExport.java index 64dc2d84c7..76bfa3b158 100644 --- a/src/java/org/apache/cassandra/tools/SSTableExport.java +++ b/src/java/org/apache/cassandra/tools/SSTableExport.java @@ -387,7 +387,6 @@ public class SSTableExport * export the contents of the SSTable to JSON. * * @param args command lines arguments - * @throws IOException on failure to open/read/write files or output streams * @throws ConfigurationException on configuration failure (wrong params given) */ public static void main(String[] args) throws ConfigurationException diff --git a/src/java/org/apache/cassandra/tools/SSTableImport.java b/src/java/org/apache/cassandra/tools/SSTableImport.java index f51610bc8c..ee6bf591d1 100644 --- a/src/java/org/apache/cassandra/tools/SSTableImport.java +++ b/src/java/org/apache/cassandra/tools/SSTableImport.java @@ -459,7 +459,6 @@ public class SSTableImport * using an optional command line argument, or supplied on standard in. * * @param args command line arguments - * @throws IOException on failure to open/read/write files or output streams * @throws ParseException on failure to parse JSON input * @throws ConfigurationException on configuration error. */ diff --git a/src/java/org/apache/cassandra/tools/SSTableRepairedAtSetter.java b/src/java/org/apache/cassandra/tools/SSTableRepairedAtSetter.java index 233318969c..2ddb632e3f 100644 --- a/src/java/org/apache/cassandra/tools/SSTableRepairedAtSetter.java +++ b/src/java/org/apache/cassandra/tools/SSTableRepairedAtSetter.java @@ -36,8 +36,9 @@ import org.apache.cassandra.service.ActiveRepairService; * * If you know you ran repair 2 weeks ago, you can do something like * + * {@code * sstablerepairset --is-repaired -f <(find /var/lib/cassandra/data/.../ -iname "*Data.db*" -mtime +14) - * + * } */ public class SSTableRepairedAtSetter { diff --git a/src/java/org/apache/cassandra/utils/concurrent/OpOrder.java b/src/java/org/apache/cassandra/utils/concurrent/OpOrder.java index 5cebf4413d..b80fe99e50 100644 --- a/src/java/org/apache/cassandra/utils/concurrent/OpOrder.java +++ b/src/java/org/apache/cassandra/utils/concurrent/OpOrder.java @@ -30,6 +30,7 @@ import java.util.concurrent.atomic.AtomicIntegerFieldUpdater; * *

The typical usage is something like: * 

+ * {@code
      public final class ExampleShared
      {
         final OpOrder order = new OpOrder();
@@ -73,6 +74,7 @@ import java.util.concurrent.atomic.AtomicIntegerFieldUpdater;
             }
         }
     }
+ * }
  *
*/ public class OpOrder diff --git a/src/java/org/apache/cassandra/utils/obs/OpenBitSet.java b/src/java/org/apache/cassandra/utils/obs/OpenBitSet.java index 7edf06f8cc..e793f6cb60 100644 --- a/src/java/org/apache/cassandra/utils/obs/OpenBitSet.java +++ b/src/java/org/apache/cassandra/utils/obs/OpenBitSet.java @@ -25,25 +25,30 @@ import java.io.IOException; import org.apache.cassandra.db.TypeSizes; /** + *

* An "open" BitSet implementation that allows direct access to the arrays of words * storing the bits. Derived from Lucene's OpenBitSet, but with a paged backing array * (see bits delaration, below). - *

+ *

+ *

* Unlike java.util.bitset, the fact that bits are packed into an array of longs * is part of the interface. This allows efficient implementation of other algorithms * by someone other than the author. It also allows one to efficiently implement * alternate serialization or interchange formats. - *

+ *

+ *

* OpenBitSet is faster than java.util.BitSet in most operations * and *much* faster at calculating cardinality of sets and results of set operations. * It can also handle sets of larger cardinality (up to 64 * 2**32-1) - *

+ *

+ *

* The goals of OpenBitSet are the fastest implementation possible, and * maximum code reuse. Extra safety and encapsulation * may always be built on top, but if that's built in, the cost can never be removed (and * hence people re-implement their own version in order to get better performance). * If you want a "safe", totally encapsulated (and slower and limited) BitSet * class, use java.util.BitSet. + *

*/ public class OpenBitSet implements IBitSet