This is an automated email from the ASF dual-hosted git repository.
dlmarion pushed a commit to branch 2.1
in repository https://gitbox.apache.org/repos/asf/accumulo.git
The following commit(s) were added to refs/heads/2.1 by this push:
new 3eab49fe66 Improve JavaDocs for VolumeChooser classes (#3152)
3eab49fe66 is described below
commit 3eab49fe66485cd1cc77fe1d0319e266ce0f54ad
Author: Daniel Roberts <ddani...@gmail.com>
AuthorDate: Tue Jan 17 07:45:37 2023 -0500
Improve JavaDocs for VolumeChooser classes (#3152)
Added more documentation for implementations of the VolumeChooser.
Added property table and basic usage examples to PreferredVolumeChooser.
Fixed minor grammatical issues.
Closes #3110
---
.../core/spi/fs/PreferredVolumeChooser.java | 103 ++++++++++++++++++++-
.../accumulo/core/spi/fs/RandomVolumeChooser.java | 9 ++
.../core/spi/fs/SpaceAwareVolumeChooser.java | 2 +-
.../apache/accumulo/core/spi/fs/VolumeChooser.java | 32 ++++---
.../core/spi/fs/VolumeChooserEnvironment.java | 8 +-
.../org/apache/accumulo/core/spi/package-info.java | 2 +-
6 files changed, 134 insertions(+), 22 deletions(-)
diff --git
a/core/src/main/java/org/apache/accumulo/core/spi/fs/PreferredVolumeChooser.java
b/core/src/main/java/org/apache/accumulo/core/spi/fs/PreferredVolumeChooser.java
index 9543e07f4c..c90fcde244 100644
---
a/core/src/main/java/org/apache/accumulo/core/spi/fs/PreferredVolumeChooser.java
+++
b/core/src/main/java/org/apache/accumulo/core/spi/fs/PreferredVolumeChooser.java
@@ -23,17 +23,102 @@ import java.util.Collections;
import java.util.Set;
import java.util.stream.Collectors;
+import org.apache.accumulo.core.conf.Property;
import org.apache.accumulo.core.spi.fs.VolumeChooserEnvironment.Scope;
import org.apache.accumulo.core.volume.Volume;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
- * A {@link RandomVolumeChooser} that limits its choices from a given set of
options to the subset
- * of those options preferred for a particular table. Defaults to selecting
from all of the options
- * presented. Can be customized via the table property
table.custom.volume.preferred, which should
- * contain a comma separated list of {@link Volume} URIs. Note that both the
property name and the
- * format of its value are specific to this particular implementation.
+ * A {@link RandomVolumeChooser} that selects preferred volumes to use from
the provided volume
+ * options. Preferred Volumes are set on either the per-table, per-scope, or
default configuration
+ * level. Configuration details are overridden based on the top-down
"Default","Site","System"
+ * scopes.
+ * <p>
+ * Defaults to selecting a volume at random from the provided volume options.
+ *
+ * <p>
+ * Property Details:
+ * <p>
+ * Preferred volumes can be set on a per-table basis via the custom property
+ * {@code volume.preferred}.
+ *
+ * <p>
+ * This property should contain a comma separated list of {@link Volume} URIs.
Since this is a
+ * custom property, it can be accessed under the prefix {@code
table.custom}.<br>
+ *
+ * The {@code volume.preferred} property can be set at various configuration
levels depending on the
+ * scope. Note: Both the property name and the format of its value are
specific to this particular
+ * implementation.
+ * <table border="1">
+ * <caption>Scope Property Lookups and Defaults locations</caption>
+ * <tr>
+ * <th>Scope</th>
+ * <th>Property Value Lookup</th>
+ * <th>Default Property Lookup</th>
+ * </tr>
+ * <tr>
+ * <td>{@code Scope.DEFAULT}</td>
+ * <td>{@code general.custom.volume.preferred.default}</td>
+ * <td>Throws RuntimeException if not set</td>
+ * </tr>
+ * <tr>
+ * <td>{@code Scope.INIT}</td>
+ * <td>{@code general.custom.volume.preferred.init}</td>
+ * <td>{@code general.custom.volume.preferred.default}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code Scope.LOGGER}</td>
+ * <td>{@code general.custom.volume.preferred.logger}</td>
+ * <td>{@code general.custom.volume.preferred.default}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code Scope.TABLE}</td>
+ * <td>{@code table.custom.volume.preferred}</td>
+ * <td>{@code general.custom.volume.preferred.default}</td>
+ * </tr>
+ * </table>
+ * <br>
+ * <p>
+ * Examples of expected usage:
+ * <ul>
+ * <li>Separate metadata table and write ahead logs from general data location.
+ *
+ * <pre>
+ * <code>
+ * // Set list of volumes
+ * instance.volumes=hdfs://namenode_A/accumulo,hdfs://namenode_B/general
+ * // Enable the preferred volume chooser
+ *
general.volume.chooser=org.apache.accumulo.core.spi.fs.PreferredVolumeChooser
+ * // Set default preferred volume
+ * general.custom.volume.preferred.default=hdfs://namenode_B/general
+ * // Set write-ahead log preferred volume
+ * general.custom.volume.preferred.logger=hdfs://namenode_A/accumulo
+ * // Initialize and start accumulo
+ * // Once accumulo is up, open the shell and configure the metadata table to
use a preferred volume
+ * config -t accumulo.metadata -s
table.custom.volume.preferred=hdfs://namenode_A/accumulo
+ * </code>
+ * </pre>
+ *
+ * </li>
+ * <li>Allow general data to use all volumes, but limit a specific table to a
preferred volume
+ *
+ * <pre>
+ * <code>
+ * // Set list of volumes
+ * instance.volumes=hdfs://namenode/accumulo,hdfs://namenode/accumulo_select
+ * // Enable the preferred volume chooser
+ *
general.volume.chooser=org.apache.accumulo.core.spi.fs.PreferredVolumeChooser
+ * // Set default preferred volumes
+ *
general.custom.volume.preferred.default=hdfs://namenode/accumulo,hdfs://namenode/accumulo_select
+ * // Initialize and start accumulo
+ * // Once accumulo is up, open the shell and configure the metadata table to
use a preferred volume
+ * config -t accumulo.metadata -s
table.custom.volume.preferred=hdfs://namenode/accumulo_select
+ * </code>
+ * </pre>
+ *
+ * </li>
+ * </ul>
*
* @since 2.1.0
*/
@@ -58,6 +143,14 @@ public class PreferredVolumeChooser extends
RandomVolumeChooser {
return choice;
}
+ /**
+ *
+ * Returns the subset of volumes that match the defined preferred volumes
value
+ *
+ * @param env the server environment provided by the calling framework
+ * @param options the subset of volumes to choose from
+ * @return an array of preferred volumes that are a subset of {@link
Property#INSTANCE_VOLUMES}
+ */
@Override
public Set<String> choosable(VolumeChooserEnvironment env, Set<String>
options) {
return getPreferredVolumes(env, options);
diff --git
a/core/src/main/java/org/apache/accumulo/core/spi/fs/RandomVolumeChooser.java
b/core/src/main/java/org/apache/accumulo/core/spi/fs/RandomVolumeChooser.java
index 21eca16437..77549914bb 100644
---
a/core/src/main/java/org/apache/accumulo/core/spi/fs/RandomVolumeChooser.java
+++
b/core/src/main/java/org/apache/accumulo/core/spi/fs/RandomVolumeChooser.java
@@ -22,17 +22,26 @@ import java.security.SecureRandom;
import java.util.Set;
/**
+ * A {@link VolumeChooser} that selects a volume at random from the list of
provided volumes.
+ *
* @since 2.1.0
*/
public class RandomVolumeChooser implements VolumeChooser {
private static final SecureRandom random = new SecureRandom();
+ /**
+ * Selects a volume at random from the provided set of volumes. The
environment scope is not
+ * utilized.
+ */
@Override
public String choose(VolumeChooserEnvironment env, Set<String> options) {
String[] optionsArray = options.toArray(new String[0]);
return optionsArray[random.nextInt(optionsArray.length)];
}
+ /**
+ * @return same set of volume options that were originally provided.
+ */
@Override
public Set<String> choosable(VolumeChooserEnvironment env, Set<String>
options) {
return options;
diff --git
a/core/src/main/java/org/apache/accumulo/core/spi/fs/SpaceAwareVolumeChooser.java
b/core/src/main/java/org/apache/accumulo/core/spi/fs/SpaceAwareVolumeChooser.java
index 17a84357ae..20b92e001e 100644
---
a/core/src/main/java/org/apache/accumulo/core/spi/fs/SpaceAwareVolumeChooser.java
+++
b/core/src/main/java/org/apache/accumulo/core/spi/fs/SpaceAwareVolumeChooser.java
@@ -41,7 +41,7 @@ import com.google.common.cache.LoadingCache;
/**
* A {@link PreferredVolumeChooser} that takes remaining HDFS space into
account when making a
- * volume choice rather than a simpler round robin. The list of volumes to use
can be limited using
+ * volume choice rather than a simpler round-robin. The list of volumes to use
can be limited using
* the same properties as {@link PreferredVolumeChooser}
*
* @since 2.1.0
diff --git
a/core/src/main/java/org/apache/accumulo/core/spi/fs/VolumeChooser.java
b/core/src/main/java/org/apache/accumulo/core/spi/fs/VolumeChooser.java
index c5292f1535..6f5885976a 100644
--- a/core/src/main/java/org/apache/accumulo/core/spi/fs/VolumeChooser.java
+++ b/core/src/main/java/org/apache/accumulo/core/spi/fs/VolumeChooser.java
@@ -23,13 +23,18 @@ import java.util.Set;
import org.apache.accumulo.core.conf.Property;
/**
- * Helper used to select from a set of Volume URIs. N.B. implementations must
be threadsafe.
- * VolumeChooser.equals will be used for internal caching.
- *
+ * Helper used to select a volume from a set of Volume URIs.
+ * <p>
+ * Volumes will be selected based on defined option criteria. Note:
Implementations must be
+ * threadsafe.<br>
+ * VolumeChooser.equals will be used for internal caching.<br>
* <p>
- * Implementations may wish to store configuration in Accumulo's system
configuration using the
- * {@link Property#GENERAL_ARBITRARY_PROP_PREFIX}. They may also benefit from
using per-table
- * configuration using {@link Property#TABLE_ARBITRARY_PROP_PREFIX}.
+ * Property Details:<br>
+ * {@link Property#GENERAL_ARBITRARY_PROP_PREFIX} and {@link
Property#TABLE_ARBITRARY_PROP_PREFIX}
+ * can be used to define user-specific properties to ensure separation from
Accumulo System
+ * defaults.<br>
+ *
+ * Note: The default VolumeChooser implementation is set by {@link
Property#GENERAL_VOLUME_CHOOSER}.
*
* @since 2.1.0
*/
@@ -40,19 +45,18 @@ public interface VolumeChooser {
*
* @param env the server environment provided by the calling framework
* @param options the list of volumes to choose from
- * @return one of the options
+ * @return a volume from the list of volume options
*/
String choose(VolumeChooserEnvironment env, Set<String> options);
/**
- * Return the subset of volumes that could possibly be chosen by this
chooser across all
- * invocations of {@link #choose(VolumeChooserEnvironment, Set)}. Currently
this is used to
- * determine if all of the volumes that could be chosen for write ahead logs
support the needed
- * filesystem operations. There may be other use cases in the future.
+ * Return the subset of all possible volumes that could be chosen across all
invocations of
+ * {@link #choose(VolumeChooserEnvironment, Set)}.<br>
*
- * @param env the server environment provided by the calling framework
- * @param options the subset of volumes to choose from
- * @return array of valid options
+ * This is currently used to determine if the chosen volumes can support the
required filesystem
+ * operations for write ahead logs.<br>
+ *
+ * There may be other use cases in the future.
*/
Set<String> choosable(VolumeChooserEnvironment env, Set<String> options);
}
diff --git
a/core/src/main/java/org/apache/accumulo/core/spi/fs/VolumeChooserEnvironment.java
b/core/src/main/java/org/apache/accumulo/core/spi/fs/VolumeChooserEnvironment.java
index 7137efd186..2f5c9c5227 100644
---
a/core/src/main/java/org/apache/accumulo/core/spi/fs/VolumeChooserEnvironment.java
+++
b/core/src/main/java/org/apache/accumulo/core/spi/fs/VolumeChooserEnvironment.java
@@ -29,7 +29,7 @@ import org.apache.hadoop.io.Text;
*/
public interface VolumeChooserEnvironment {
/**
- * A scope the volume chooser environment; a TABLE scope should be
accompanied by a tableId.
+ * A scope for the volume chooser environment; a TABLE scope should be
accompanied by a tableId.
*
* @since 2.1.0
*/
@@ -37,6 +37,12 @@ public interface VolumeChooserEnvironment {
DEFAULT, TABLE, INIT, LOGGER
}
+ /**
+ * The end row of the tablet for which a volume is being chosen. Only call
this when the scope is
+ * TABLE
+ *
+ * @since 2.0.0
+ */
public Text getEndRow();
public Optional<TableId> getTable();
diff --git a/core/src/main/java/org/apache/accumulo/core/spi/package-info.java
b/core/src/main/java/org/apache/accumulo/core/spi/package-info.java
index 3e3488b7ee..824e75edbe 100644
--- a/core/src/main/java/org/apache/accumulo/core/spi/package-info.java
+++ b/core/src/main/java/org/apache/accumulo/core/spi/package-info.java
@@ -52,7 +52,7 @@
* </ul>
*
* <p>
- * Before this package was created many plugin interface were created for
Accumulo. These plugin
+ * Before this package was created many plugin interfaces were created for
Accumulo. These plugin
* interfaces used internal Accumulo types, which transitively used other
internal types. This
* undisciplined use of any types made it impractical to reason about,
analyze, or make any
* guarantees about plugin stability. This package was created to solve that
problem. Hopefully
