Spring/spring-data-mongodb
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

DATAMONGO-1552 - Polishing.

Browse Source 
Updated doc, removed whitespaces, minor method wording changes.

Original Pull Request: #426
This commit is contained in:
Christoph Strobl
2016-12-14 09:46:50 +01:00
parent 450549150d
commit 5cf8ec3e55
9 changed files with 84 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/Aggregation.java
View File

@@ -422,6 +422,7 @@ public class Aggregation {
*
* @param groupByField must not be {@literal null} or empty.
* @return
* @since 1.10
*/
public static BucketOperation bucket(String groupByField) {
return new BucketOperation(field(groupByField));
@@ -432,6 +433,7 @@ public class Aggregation {
*
* @param groupByExpression must not be {@literal null}.
* @return
* @since 1.10
*/
public static BucketOperation bucket(AggregationExpression groupByExpression) {
return new BucketOperation(groupByExpression);
@@ -443,6 +445,7 @@ public class Aggregation {
* @param groupByField must not be {@literal null} or empty.
* @param buckets number of buckets, must be a positive integer.
* @return
* @since 1.10
*/
public static BucketAutoOperation bucketAuto(String groupByField, int buckets) {
return new BucketAutoOperation(field(groupByField), buckets);
@@ -454,6 +457,7 @@ public class Aggregation {
* @param groupByExpression must not be {@literal null}.
* @param buckets number of buckets, must be a positive integer.
* @return
* @since 1.10
*/
public static BucketAutoOperation bucketAuto(AggregationExpression groupByExpression, int buckets) {
return new BucketAutoOperation(groupByExpression, buckets);
@@ -463,6 +467,7 @@ public class Aggregation {
* Creates a new {@link FacetOperation}.
*
* @return
* @since 1.10
*/
public static FacetOperation facet() {
return FacetOperation.EMPTY;
@@ -473,6 +478,7 @@ public class Aggregation {
*
* @param aggregationOperations the sub-pipeline, must not be {@literal null}.
* @return
* @since 1.10
*/
public static FacetOperationBuilder facet(AggregationOperation... aggregationOperations) {
return facet().and(aggregationOperations);

2
spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/AggregationOperationRenderer.java
View File

@@ -39,7 +39,7 @@ class AggregationOperationRenderer {
/**
* Render a {@link List} of {@link AggregationOperation} given {@link AggregationOperationContext} into their
* {@link Document} representation.
*
*
* @param operations must not be {@literal null}.
* @param context must not be {@literal null}.
* @return the {@link List} of {@link Document}.

39
spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/BucketAutoOperation.java
View File

@@ -22,18 +22,18 @@ import org.springframework.util.Assert;
import org.bson.Document;
/**
* Encapsulates the aggregation framework {@code $bucketAuto}-operation.
* <p>
* Encapsulates the aggregation framework {@code $bucketAuto}-operation. <br />
* Bucket stage is typically used with {@link Aggregation} and {@code $facet}. Categorizes incoming documents into a
* specific number of groups, called buckets, based on a specified expression. Bucket boundaries are automatically
* determined in an attempt to evenly distribute the documents into the specified number of buckets.
* <p>
* We recommend to use the static factory method {@link Aggregation#bucketAuto(String, int)} instead of creating instances of
* this class directly.
* determined in an attempt to evenly distribute the documents into the specified number of buckets. <br />
* We recommend to use the static factory method {@link Aggregation#bucketAuto(String, int)} instead of creating
* instances of this class directly.
*
* @see http://docs.mongodb.org/manual/reference/aggregation/bucketAuto/
* @see <a href=
* "http://docs.mongodb.org/manual/reference/aggregation/bucketAuto/">http://docs.mongodb.org/manual/reference/aggregation/bucketAuto/</a>
* @see BucketOperationSupport
* @author Mark Paluch
* @author Christoph Strobl
* @since 1.10
*/
public class BucketAutoOperation extends BucketOperationSupport<BucketAutoOperation, BucketAutoOperationOutputBuilder>
@@ -122,8 +122,10 @@ public class BucketAutoOperation extends BucketOperationSupport<BucketAutoOperat
}
/**
* Configures {@literal granularity} that specifies the preferred number series to use to ensure that the calculated
* boundary edges end on preferred round numbers or their powers of 10 and return a new {@link BucketAutoOperation}.
* Configures {@link Granularity granularity} that specifies the preferred number series to use to ensure that the
* calculated boundary edges end on preferred round numbers or their powers of 10 and return a new
* {@link BucketAutoOperation}. <br />
* Use either predefined {@link Granularities} or provide a own one.
*
* @param granularity must not be {@literal null}.
* @return
@@ -132,7 +134,7 @@ public class BucketAutoOperation extends BucketOperationSupport<BucketAutoOperat
Assert.notNull(granularity, "Granularity must not be null!");
return new BucketAutoOperation(this, buckets, granularity.toMongoGranularity());
return new BucketAutoOperation(this, buckets, granularity.getMongoRepresentation());
}
/* (non-Javadoc)
@@ -195,7 +197,7 @@ public class BucketAutoOperation extends BucketOperationSupport<BucketAutoOperat
/**
* {@link ExpressionBucketOperationBuilderSupport} implementation for {@link BucketAutoOperation} using SpEL
* expression based {@link Output}.
*
*
* @author Mark Paluch
*/
public static class ExpressionBucketAutoOperationBuilder
@@ -226,19 +228,20 @@ public class BucketAutoOperation extends BucketOperationSupport<BucketAutoOperat
/**
* @author Mark Paluch
*/
public static interface Granularity {
public interface Granularity {
/**
* @return a String that represents a MongoDB granularity to be used with {@link BucketAutoOperation}.
* @return a String that represents a MongoDB granularity to be used with {@link BucketAutoOperation}. Never
* {@literal null}.
*/
String toMongoGranularity();
String getMongoRepresentation();
}
/**
* Supported MongoDB granularities.
*
* @see https://en.wikipedia.org/wiki/Preferred_number
* @see https://docs.mongodb.com/manual/reference/operator/aggregation/bucketAuto/#granularity
* @see <a
* href="https://docs.mongodb.com/manual/reference/operator/aggregation/bucketAuto/#granularity>https://docs.mongodb.com/manual/reference/operator/aggregation/bucketAuto/#granularity</a>
* @author Mark Paluch
*/
public enum Granularities implements Granularity {
@@ -251,7 +254,7 @@ public class BucketAutoOperation extends BucketOperationSupport<BucketAutoOperat
POWERSOF2;
final String granularity;
private final String granularity;
Granularities() {
this.granularity = name();
@@ -265,7 +268,7 @@ public class BucketAutoOperation extends BucketOperationSupport<BucketAutoOperat
* @see org.springframework.data.mongodb.core.aggregation.GranularitytoMongoGranularity()
*/
@Override
public String toMongoGranularity() {
public String getMongoRepresentation() {
return granularity;
}
}

17
spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/BucketOperation.java
View File

@@ -26,15 +26,15 @@ import org.springframework.util.Assert;
import org.bson.Document;
/**
* Encapsulates the aggregation framework {@code $bucket}-operation.
* <p>
* Encapsulates the aggregation framework {@code $bucket}-operation. <br />
*
* Bucket stage is typically used with {@link Aggregation} and {@code $facet}. Categorizes incoming documents into
* groups, called buckets, based on a specified expression and bucket boundaries.
* <p>
* groups, called buckets, based on a specified expression and bucket boundaries. <br />
*
* We recommend to use the static factory method {@link Aggregation#bucket(String)} instead of creating instances of
* this class directly.
*
* @see http://docs.mongodb.org/manual/reference/aggregation/bucket/
* @see <a href="http://docs.mongodb.org/manual/reference/aggregation/bucket/">http://docs.mongodb.org/manual/reference/aggregation/bucket/</a>
* @see BucketOperationSupport
* @author Mark Paluch
* @since 1.10
@@ -108,7 +108,7 @@ public class BucketOperation extends BucketOperationSupport<BucketOperation, Buc
/**
* Configures a default bucket {@literal literal} and return a new {@link BucketOperation}.
*
*
* @param literal must not be {@literal null}.
* @return
*/
@@ -121,13 +121,14 @@ public class BucketOperation extends BucketOperationSupport<BucketOperation, Buc
/**
* Configures {@literal boundaries} and return a new {@link BucketOperation}. Existing {@literal boundaries} are
* preserved and the new {@literal boundaries} are appended.
*
*
* @param boundaries must not be {@literal null}.
* @return
*/
public BucketOperation withBoundaries(Object... boundaries) {
Assert.notNull(boundaries, "Boundaries must not be null!");
Assert.noNullElements(boundaries, "Boundaries must not contain null values!");
List<Object> newBoundaries = new ArrayList<Object>(this.boundaries.size() + boundaries.length);
newBoundaries.addAll(this.boundaries);
@@ -196,7 +197,7 @@ public class BucketOperation extends BucketOperationSupport<BucketOperation, Buc
/**
* {@link ExpressionBucketOperationBuilderSupport} implementation for {@link BucketOperation} using SpEL expression
* based {@link Output}.
*
*
* @author Mark Paluch
*/
public static class ExpressionBucketOperationBuilder

78
spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/BucketOperationSupport.java
View File

@@ -30,14 +30,12 @@ import org.springframework.util.Assert;
import org.bson.Document;
/**
* Base class for bucket operations that support output expressions the aggregation framework.
* <p>
* Bucket stages collect documents into buckets and can contribute output fields.
* <p>
* Base class for bucket operations that support output expressions the aggregation framework. <br />
* Bucket stages collect documents into buckets and can contribute output fields. <br />
* Implementing classes are required to provide an {@link OutputBuilder}.
*
* @see http://docs.mongodb.org/manual/reference/aggregation/bucket/
* @author Mark Paluch
* @author Christoph Strobl
* @since 1.10
*/
public abstract class BucketOperationSupport<T extends BucketOperationSupport<T, B>, B extends OutputBuilder<B, T>>
@@ -49,7 +47,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Creates a new {@link BucketOperationSupport} given a {@link Field group-by field}.
*
*
* @param groupByField must not be {@literal null}.
*/
protected BucketOperationSupport(Field groupByField) {
@@ -59,7 +57,6 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
this.groupByField = groupByField;
this.groupByExpression = null;
this.outputs = Outputs.EMPTY;
}
/**
@@ -78,7 +75,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Creates a copy of {@link BucketOperationSupport}.
*
*
* @param operationSupport must not be {@literal null}.
*/
protected BucketOperationSupport(BucketOperationSupport<?, ?> operationSupport) {
@@ -87,7 +84,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Creates a copy of {@link BucketOperationSupport} and applies the new {@link Outputs}.
*
*
* @param operationSupport must not be {@literal null}.
* @param outputs must not be {@literal null}.
*/
@@ -104,7 +101,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Creates a new {@link ExpressionBucketOperationBuilderSupport} given a SpEL {@literal expression} and optional
* {@literal params} to add an output field to the resulting bucket documents.
*
*
* @param expression the SpEL expression, must not be {@literal null} or empty.
* @param params must not be {@literal null}
* @return
@@ -185,7 +182,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Builder for SpEL expression-based {@link Output}.
*
*
* @author Mark Paluch
*/
public abstract static class ExpressionBucketOperationBuilderSupport<B extends OutputBuilder<B, T>, T extends BucketOperationSupport<T, B>>
@@ -231,11 +228,9 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
}
/**
* Generates a builder for a {@code $sum}-expression.
* <p>
* Generates a builder for a {@code $sum}-expression. <br />
* Count expressions are emulated via {@code $sum: 1}.
* <p>
*
*
* @return
*/
public B count() {
@@ -244,7 +239,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Generates a builder for a {@code $sum}-expression for the current value.
*
*
* @return
*/
public B sum() {
@@ -258,12 +253,12 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
* @return
*/
public B sum(Number value) {
return apply(new OperationOutput(Accumulators.SUM.toString(), Collections.singleton(value)));
return apply(new OperationOutput(Accumulators.SUM.getMongoOperator(), Collections.singleton(value)));
}
/**
* Generates a builder for an {@code $last}-expression for the current value..
*
*
* @return
*/
public B last() {
@@ -272,7 +267,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Generates a builder for a {@code $first}-expression the current value.
*
*
* @return
*/
public B first() {
@@ -281,7 +276,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Generates a builder for an {@code $avg}-expression for the current value.
*
*
* @param reference
* @return
*/
@@ -291,7 +286,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Generates a builder for an {@code $min}-expression for the current value.
*
*
* @return
*/
public B min() {
@@ -300,7 +295,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Generates a builder for an {@code $max}-expression for the current value.
*
*
* @return
*/
public B max() {
@@ -345,14 +340,14 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Apply an {@link OperationOutput} to this output.
*
*
* @param operationOutput must not be {@literal null}.
* @return
*/
protected abstract B apply(OperationOutput operationOutput);
private B apply(Accumulators operation) {
return this.apply(operation.toString());
return this.apply(operation.getMongoOperator());
}
/**
@@ -387,18 +382,14 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
this.mongoOperator = mongoOperator;
}
/* (non-Javadoc)
* @see java.lang.Enum#toString()
*/
@Override
public String toString() {
public String getMongoOperator() {
return mongoOperator;
}
}
/**
* Encapsulates {@link Output}s.
*
*
* @author Mark Paluch
*/
protected static class Outputs implements AggregationExpression {
@@ -416,7 +407,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Creates new {@link Outputs} containing all given {@link Output}s.
*
*
* @param current
* @param output
*/
@@ -448,7 +439,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Create a new {@link Outputs} that contains the new {@link Output}.
*
*
* @param output must not be {@literal null}.
* @return the new {@link Outputs} that contains the new {@link Output}
*/
@@ -483,11 +474,10 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
}
/**
* Encapsulates an output field in a bucket aggregation stage.
* <p>
* Encapsulates an output field in a bucket aggregation stage. <br />
* Output fields can be either top-level fields that define a valid field name or nested output fields using
* operators.
*
*
* @author Mark Paluch
*/
protected abstract static class Output implements AggregationExpression {
@@ -513,17 +503,10 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
protected ExposedField getExposedField() {
return field;
}
/* (non-Javadoc)
* @see org.springframework.data.mongodb.core.aggregation.AggregationExpression#toDocument(org.springframework.data.mongodb.core.aggregation.AggregationOperationContext)
*/
@Override
public abstract Document toDocument(AggregationOperationContext context);
}
/**
* Output field that uses a Mongo operation (expression object) to generate an output field value.
* <p>
* Output field that uses a Mongo operation (expression object) to generate an output field value. <br />
* {@link OperationOutput} is used either with a regular field name or an operation keyword (e.g.
* {@literal $sum, $count}).
*
@@ -623,7 +606,6 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
// We have to make sure that we use the arguments from the "previous" OperationOutput that we replace
// with this new instance.
return OperationOutput.this.getOperationArguments(context);
}
};
@@ -633,7 +615,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* A {@link Output} based on a SpEL expression.
*/
static class SpelExpressionOutput extends Output {
private static class SpelExpressionOutput extends Output {
private static final SpelExpressionTransformer TRANSFORMER = new SpelExpressionTransformer();
@@ -662,11 +644,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
*/
@Override
public Document toDocument(AggregationOperationContext context) {
return (Document) toMongoExpression(context, expression, params);
}
protected static Object toMongoExpression(AggregationOperationContext context, String expression, Object[] params) {
return TRANSFORMER.transform(expression, context, params);
return (Document) TRANSFORMER.transform(expression, context, params);
}
}

35
spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/aggregation/FacetOperation.java
View File

@@ -27,22 +27,20 @@ import org.springframework.util.Assert;
import org.bson.Document;
/**
* Encapsulates the aggregation framework {@code $facet}-operation.
* <p>
* Encapsulates the aggregation framework {@code $facet}-operation. <br />
* Facet of {@link AggregationOperation}s to be used in an {@link Aggregation}. Processes multiple
* {@link AggregationOperation} pipelines within a single stage on the same set of input documents. Each sub-pipeline
* has its own field in the output document where its results are stored as an array of documents.
* {@link FacetOperation} enables various aggregations on the same set of input documents, without needing to retrieve
* the input documents multiple times.
* <p>
* the input documents multiple times. <br />
* As of MongoDB 3.4, {@link FacetOperation} cannot be used with nested pipelines containing {@link GeoNearOperation},
* {@link OutOperation} and {@link FacetOperation}.
* <p>
* {@link OutOperation} and {@link FacetOperation}. <br />
* We recommend to use the static factory method {@link Aggregation#facet()} instead of creating instances of this class
* directly.
*
* @see http://docs.mongodb.org/manual/reference/aggregation/facet/
* @author Mark Paluch
* @author Christoph Strobl
* @since 1.10
*/
public class FacetOperation implements FieldsExposingAggregationOperation {
@@ -66,11 +64,10 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
}
/**
* Creates a new {@link FacetOperationBuilder} to append a new facet using {@literal operations}.
* <p>
* Creates a new {@link FacetOperationBuilder} to append a new facet using {@literal operations}. <br />
* {@link FacetOperationBuilder} takes a pipeline of {@link AggregationOperation} to categorize documents into a
* single facet.
*
*
* @param operations must not be {@literal null} or empty.
* @return
*/
@@ -117,7 +114,7 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
/**
* Creates a new {@link FacetOperation} that contains the configured pipeline of {@link AggregationOperation}
* exposed as {@literal fieldName} in the resulting facet document.
*
*
* @param fieldName must not be {@literal null} or empty.
* @return
*/
@@ -131,7 +128,7 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
/**
* Encapsulates multiple {@link Facet}s
*
*
* @author Mark Paluch
*/
private static class Facets {
@@ -142,7 +139,7 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
/**
* Creates a new {@link Facets} given {@link List} of {@link Facet}.
*
*
* @param facets
*/
private Facets(List<Facet> facets) {
@@ -152,7 +149,7 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
/**
* @return the {@link ExposedFields} derived from {@link Output}.
*/
protected ExposedFields asExposedFields() {
ExposedFields asExposedFields() {
ExposedFields fields = ExposedFields.from();
@@ -176,12 +173,12 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
/**
* Adds a facet to this {@link Facets}.
*
*
* @param fieldName must not be {@literal null}.
* @param operations must not be {@literal null}.
* @return the new {@link Facets}.
*/
public Facets and(String fieldName, List<AggregationOperation> operations) {
Facets and(String fieldName, List<AggregationOperation> operations) {
Assert.hasText(fieldName, "FieldName must not be null or empty!");
Assert.notNull(operations, "AggregationOperations must not be null!");
@@ -196,7 +193,7 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
/**
* A single facet with a {@link ExposedField} and its {@link AggregationOperation} pipeline.
*
*
* @author Mark Paluch
*/
private static class Facet {
@@ -206,11 +203,11 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
/**
* Creates a new {@link Facet} given {@link ExposedField} and {@link AggregationOperation} pipeline.
*
*
* @param exposedField must not be {@literal null}.
* @param operations must not be {@literal null}.
*/
protected Facet(ExposedField exposedField, List<AggregationOperation> operations) {
Facet(ExposedField exposedField, List<AggregationOperation> operations) {
Assert.notNull(exposedField, "ExposedField must not be null!");
Assert.notNull(operations, "AggregationOperations must not be null!");
@@ -219,7 +216,7 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
this.operations = operations;
}
protected ExposedField getExposedField() {
ExposedField getExposedField() {
return exposedField;
}

2
spring-data-mongodb/src/test/java/org/springframework/data/mongodb/core/aggregation/BucketAutoOperationUnitTests.java
View File

@@ -27,7 +27,7 @@ import org.bson.Document;
/**
* Unit tests for {@link BucketAutoOperation}.
*
*
* @author Mark Paluch
*/
public class BucketAutoOperationUnitTests {

2
spring-data-mongodb/src/test/java/org/springframework/data/mongodb/core/aggregation/BucketOperationUnitTests.java
View File

@@ -27,7 +27,7 @@ import org.bson.Document;
/**
* Unit tests for {@link BucketOperation}.
*
*
* @author Mark Paluch
*/
public class BucketOperationUnitTests {

2
spring-data-mongodb/src/test/java/org/springframework/data/mongodb/core/aggregation/FacetOperationUnitTests.java
View File

@@ -26,7 +26,7 @@ import org.bson.Document;
/**
* Unit tests for {@link FacetOperation}.
*
*
* @author Mark Paluch
* @soundtrack Stanley Foort - You Make Me Believe In Magic (Extended Mix)
*/