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 d250f88c38
commit c9c5fe62ca
9 changed files with 88 additions and 104 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

@@ -424,6 +424,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));
@@ -434,6 +435,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);
@@ -445,6 +447,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);
@@ -456,6 +459,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);
@@ -465,6 +469,7 @@ public class Aggregation {
* Creates a new {@link FacetOperation}.
*
* @return
* @since 1.10
*/
public static FacetOperation facet() {
return FacetOperation.EMPTY;
@@ -475,6 +480,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);

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

@@ -28,7 +28,7 @@ import com.mongodb.DBObject;
/**
* Rendering support for {@link AggregationOperation} into a {@link List} of {@link com.mongodb.DBObject}.
*
*
* @author Mark Paluch
* @author Christoph Strobl
* @since 1.10
@@ -40,7 +40,7 @@ class AggregationOperationRenderer {
/**
* Render a {@link List} of {@link AggregationOperation} given {@link AggregationOperationContext} into their
* {@link DBObject} representation.
*
*
* @param operations must not be {@literal null}.
* @param context must not be {@literal null}.
* @return the {@link List} of {@link DBObject}.

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

@@ -23,18 +23,18 @@ import com.mongodb.BasicDBObject;
import com.mongodb.DBObject;
/**
* 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>
@@ -100,13 +100,12 @@ public class BucketAutoOperation extends BucketOperationSupport<BucketAutoOperat
DBObject options = new BasicDBObject();
options.put("buckets", buckets);
options.putAll(super.toDBObject(context));
if (granularity != null) {
options.put("granularity", granularity);
}
options.putAll(super.toDBObject(context));
return new BasicDBObject("$bucketAuto", options);
}
@@ -123,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
@@ -133,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)
@@ -196,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
@@ -227,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 {
@@ -252,7 +254,7 @@ public class BucketAutoOperation extends BucketOperationSupport<BucketAutoOperat
POWERSOF2;
final String granularity;
private final String granularity;
Granularities() {
this.granularity = name();
@@ -266,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

@@ -27,15 +27,15 @@ import com.mongodb.BasicDBObject;
import com.mongodb.DBObject;
/**
* 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
@@ -109,7 +109,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
*/
@@ -122,13 +122,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);
@@ -197,7 +198,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

@@ -31,14 +31,12 @@ import com.mongodb.BasicDBObject;
import com.mongodb.DBObject;
/**
* 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>>
@@ -50,7 +48,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) {
@@ -60,7 +58,6 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
this.groupByField = groupByField;
this.groupByExpression = null;
this.outputs = Outputs.EMPTY;
}
/**
@@ -79,7 +76,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) {
@@ -88,7 +85,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}.
*/
@@ -105,7 +102,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
@@ -186,7 +183,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>>
@@ -232,11 +229,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() {
@@ -245,7 +240,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() {
@@ -259,12 +254,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() {
@@ -273,7 +268,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Generates a builder for a {@code $first}-expression the current value.
*
*
* @return
*/
public B first() {
@@ -282,7 +277,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Generates a builder for an {@code $avg}-expression for the current value.
*
*
* @param reference
* @return
*/
@@ -292,7 +287,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() {
@@ -301,7 +296,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() {
@@ -346,14 +341,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());
}
/**
@@ -388,18 +383,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 {
@@ -417,7 +408,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
/**
* Creates new {@link Outputs} containing all given {@link Output}s.
*
*
* @param current
* @param output
*/
@@ -449,7 +440,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}
*/
@@ -484,11 +475,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 {
@@ -514,17 +504,10 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
protected ExposedField getExposedField() {
return field;
}
/* (non-Javadoc)
* @see org.springframework.data.mongodb.core.aggregation.AggregationExpression#toDbObject(org.springframework.data.mongodb.core.aggregation.AggregationOperationContext)
*/
@Override
public abstract DBObject toDbObject(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}).
*
@@ -624,7 +607,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);
}
};
@@ -634,7 +616,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();
@@ -663,11 +645,7 @@ public abstract class BucketOperationSupport<T extends BucketOperationSupport<T,
*/
@Override
public DBObject toDbObject(AggregationOperationContext context) {
return (DBObject) toMongoExpression(context, expression, params);
}
protected static Object toMongoExpression(AggregationOperationContext context, String expression, Object[] params) {
return TRANSFORMER.transform(expression, context, params);
return (DBObject) TRANSFORMER.transform(expression, context, params);
}
}

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

@@ -28,22 +28,20 @@ import com.mongodb.BasicDBObject;
import com.mongodb.DBObject;
/**
* 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 {
@@ -67,11 +65,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
*/
@@ -118,7 +115,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
*/
@@ -132,7 +129,7 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
/**
* Encapsulates multiple {@link Facet}s
*
*
* @author Mark Paluch
*/
private static class Facets {
@@ -143,7 +140,7 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
/**
* Creates a new {@link Facets} given {@link List} of {@link Facet}.
*
*
* @param facets
*/
private Facets(List<Facet> facets) {
@@ -153,7 +150,7 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
/**
* @return the {@link ExposedFields} derived from {@link Output}.
*/
protected ExposedFields asExposedFields() {
ExposedFields asExposedFields() {
ExposedFields fields = ExposedFields.from();
@@ -164,7 +161,7 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
return fields;
}
protected DBObject toDBObject(AggregationOperationContext context) {
DBObject toDBObject(AggregationOperationContext context) {
DBObject dbObject = new BasicDBObject(facets.size());
@@ -177,12 +174,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!");
@@ -197,7 +194,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 {
@@ -207,11 +204,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!");
@@ -220,11 +217,11 @@ public class FacetOperation implements FieldsExposingAggregationOperation {
this.operations = operations;
}
protected ExposedField getExposedField() {
ExposedField getExposedField() {
return exposedField;
}
protected List<DBObject> toDBObjects(AggregationOperationContext context) {
List<DBObject> toDBObjects(AggregationOperationContext context) {
return AggregationOperationRenderer.toDBObject(operations, context);
}
}

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

@@ -28,7 +28,7 @@ import com.mongodb.util.JSON;
/**
* 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

@@ -29,7 +29,7 @@ import com.mongodb.util.JSON;
/**
* 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

@@ -27,7 +27,7 @@ import com.mongodb.util.JSON;
/**
* Unit tests for {@link FacetOperation}.
*
*
* @author Mark Paluch
* @soundtrack Stanley Foort - You Make Me Believe In Magic (Extended Mix)
*/