Skip to content

Commit 4e44ed1

Browse files
trnltrnl
committed
docs(driver) add documentation to map/reduce classes
1 parent 852dd59 commit 4e44ed1

3 files changed

Lines changed: 154 additions & 4 deletions

File tree

‎driver/src/main/org/mongodb/command/MapReduceCommandResult.java‎

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,50 @@
33
import org.mongodb.Document;
44
import org.mongodb.operation.CommandResult;
55

6+
/**
7+
* A class that represents a result of map/reduce operation.
8+
*/
69
public class MapReduceCommandResult<T> extends CommandResult {
710

11+
/**
12+
* Constructs a new instance of {@code MapReduceCommandResult} from a {@code CommandResult}
13+
*
14+
* @param baseResult result of a command to use as a base
15+
*/
816
public MapReduceCommandResult(final CommandResult baseResult) {
917
super(baseResult);
1018
}
1119

20+
/**
21+
* Check if the resulting documents of map/reduce operation is inlined.
22+
*
23+
* @return true if map/reduce operation performed with {'inline':1} argument, false otherwise.
24+
*/
1225
public boolean isInline() {
1326
return getResponse().containsKey("results");
1427
}
1528

29+
/**
30+
* Extract the resulting documents of map/reduce operation if is inlined.
31+
*
32+
* @return collection of documents to be iterated through
33+
* @throws IllegalAccessError if resulting documents are not inlined.
34+
*/
1635
@SuppressWarnings("unchecked")
1736
public Iterable<T> getValue() {
18-
return (Iterable<T>) getResponse().get("results");
37+
if (isInline()) {
38+
return (Iterable<T>) getResponse().get("results");
39+
} else {
40+
throw new IllegalAccessError("Map/reduce operation is done without 'inline' flag");
41+
}
1942
}
2043

44+
/**
45+
* Get a name of the collection that was used by map/reduce operation to write its output.
46+
*
47+
* @return a collection name
48+
* @throws IllegalAccessError if resulting documents are inlined.
49+
*/
2150
public String getTargetCollectionName() {
2251
final Object target = getTarget();
2352
if (target instanceof String) {
@@ -27,6 +56,12 @@ public String getTargetCollectionName() {
2756
}
2857
}
2958

59+
/**
60+
* Get a name of the database that was used by map/reduce operation to write its output.
61+
*
62+
* @return a database name
63+
* @throws IllegalAccessError if resulting documents are inlined.
64+
*/
3065
public String getTargetDatabaseName() {
3166
final Object target = getTarget();
3267
if (target instanceof String) {
@@ -38,7 +73,7 @@ public String getTargetDatabaseName() {
3873

3974
private Object getTarget() {
4075
if (isInline()) {
41-
throw new IllegalAccessError("Map-reduce is done with 'inline' flag");
76+
throw new IllegalAccessError("Map/reduce operation is done with 'inline' flag");
4277
}
4378
return getResponse().get("result");
4479
}

‎driver/src/main/org/mongodb/operation/MapReduce.java‎

Lines changed: 63 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
import org.bson.types.Code;
44
import org.mongodb.Document;
55

6+
/**
7+
* A class that groups arguments for a map/reduce operation.
8+
*/
69
public class MapReduce {
710
private final Code mapFunction;
811
private final Code reduceFunction;
@@ -16,13 +19,26 @@ public class MapReduce {
1619
private boolean jsMode;
1720
private boolean verbose;
1821

22+
/**
23+
* Constructs a new instance of the {@code MapReduce} with output to a another collection.
24+
*
25+
* @param mapFunction a JavaScript function that associates or “maps” a value with a key and emits the key and value pair.
26+
* @param reduceFunction a JavaScript function that “reduces” to a single object all the values associated with a particular key.
27+
* @param output specifies the location of the result of the map-reduce operation.
28+
*/
1929
public MapReduce(final Code mapFunction, final Code reduceFunction, final MapReduceOutput output) {
2030
this.mapFunction = mapFunction;
2131
this.reduceFunction = reduceFunction;
2232
this.output = output;
2333
this.inline = false;
2434
}
2535

36+
/**
37+
* Constructs a new instance of the {@code MapReduce} with result to be inlined into response.
38+
*
39+
* @param mapFunction a JavaScript function that associates or “maps” a value with a key and emits the key and value pair.
40+
* @param reduceFunction a JavaScript function that “reduces” to a single object all the values associated with a particular key.
41+
*/
2642
public MapReduce(final Code mapFunction, final Code reduceFunction) {
2743
this.mapFunction = mapFunction;
2844
this.reduceFunction = reduceFunction;
@@ -31,38 +47,84 @@ public MapReduce(final Code mapFunction, final Code reduceFunction) {
3147
this.output = null;
3248
}
3349

50+
/**
51+
* Add a 'finalize' argument to the command.
52+
*
53+
* @param finalize a JavaScript function that follows the reduce method and modifies the output.
54+
* @return the same {@code MapReduce} instance as used for the method invocation for chaining
55+
*/
3456
public MapReduce finalize(final Code finalize) {
3557
this.finalizeFunction = finalize;
3658
return this;
3759
}
3860

39-
//CHECKSTYLE:OFF TODO: http://checkstyle.sourceforge.net/config_coding.html#HiddenField needs to be supressed?
61+
//CHECKSTYLE:OFF
62+
63+
/**
64+
* Add a 'query' argument to the command.
65+
*
66+
* @param filter the selection criteria using query operators for determining the documents input to the map function.
67+
* @return the same {@code MapReduce} instance as used for the method invocation for chaining
68+
*/
4069
public MapReduce filter(final Document filter) {
4170
this.filter = filter;
4271
return this;
4372
}
4473

74+
/**
75+
* Add a 'sort' argument to the command.
76+
*
77+
* @param sortCriteria sorts the input documents. This option is useful for optimization.
78+
* @return the same {@code MapReduce} instance as used for the method invocation for chaining
79+
*/
4580
public MapReduce sort(final Document sortCriteria) {
4681
this.sortCriteria = sortCriteria;
4782
return this;
4883
}
4984

85+
/**
86+
* Add a 'scope' argument to the command.
87+
*
88+
* @param scope specifies global variables that are accessible in the map , reduce and the finalize functions
89+
* @return the same {@code MapReduce} instance as used for the method invocation for chaining
90+
*/
5091
public MapReduce scope(final Document scope) {
5192
this.scope = scope;
5293
return this;
5394
}
5495

96+
/**
97+
* Add a 'limit' argument to the command.
98+
*
99+
* @param limit specifies a maximum number of documents to return from the collection.
100+
* @return the same {@code MapReduce} instance as used for the method invocation for chaining
101+
*/
55102
public MapReduce limit(final int limit) {
56103
this.limit = limit;
57104
return this;
58105
}
59106
//CHECKSTYLE:ON
60107

108+
/**
109+
* Add a 'jsMode' flag to the command.
110+
* <p/>
111+
* This flag specifies whether to convert intermediate data into BSON format
112+
* between the execution of the map and reduce functions
113+
*
114+
* @return the same {@code MapReduce} instance as used for the method invocation for chaining
115+
*/
61116
public MapReduce jsMode() {
62117
this.jsMode = true;
63118
return this;
64119
}
65120

121+
/**
122+
* Add a 'verbose' flag to the command.
123+
* <p/>
124+
* This flag specifies whether to include the timing information in the result information.
125+
*
126+
* @return the same {@code MapReduce} instance as used for the method invocation for chaining
127+
*/
66128
public MapReduce verbose() {
67129
this.verbose = true;
68130
return this;

‎driver/src/main/org/mongodb/operation/MapReduceOutput.java‎

Lines changed: 54 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
package org.mongodb.operation;
22

3+
/**
4+
* A class that represents 'out' argument for a map/reduce operation.
5+
*/
36
public class MapReduceOutput {
47

58
private String collectionName;
@@ -9,28 +12,64 @@ public class MapReduceOutput {
912
private boolean nonAtomic;
1013

1114

15+
/**
16+
* Constructs a new instance of the {@code MapReduceOutput}.
17+
*
18+
* @param collectionName the name of the collection that you want the map-reduce operation to write its output.
19+
*/
1220
public MapReduceOutput(final String collectionName) {
1321
this.collectionName = collectionName;
1422
this.action = Action.REPLACE;
1523
}
1624

17-
//CHECKSTYLE:OFF TODO: http://checkstyle.sourceforge.net/config_coding.html#HiddenField needs to be supressed?
25+
//CHECKSTYLE:OFF
26+
27+
/**
28+
* Specify the name of the database that you want the map-reduce operation to write its output.
29+
*
30+
* @param databaseName the name of the database.
31+
* @return the same {@code MapReduceOutput} instance as used for the method invocation for chaining
32+
*/
1833
public MapReduceOutput database(final String databaseName) {
1934
this.databaseName = databaseName;
2035
return this;
2136
}
2237

38+
/**
39+
* Specify the {@code Action} to be used when writing to a collection that already exists.
40+
*
41+
* @param action
42+
* @return the same {@code MapReduceOutput} instance as used for the method invocation for chaining
43+
*/
2344
public MapReduceOutput action(final Action action) {
2445
this.action = action;
2546
return this;
2647
}
2748
//CHECKSTYLE:ON
2849

50+
/**
51+
* Add a 'sharded' flag.
52+
* <p/>
53+
* If speficied and you have enabled sharding on output database, the map-reduce operation will
54+
* shard the output collection using the _id field as the shard key.
55+
*
56+
* @return the same {@code MapReduceOutput} instance as used for the method invocation for chaining
57+
*/
2958
public MapReduceOutput sharded() {
3059
this.sharded = true;
3160
return this;
3261
}
3362

63+
64+
/**
65+
* Add a 'nonAtomic' flag. Valid only together with {@code Action.MERGE} and {@code Action.REDUCE}
66+
* <p/>
67+
* If specified the post-processing step will prevent MongoDB from locking the database;
68+
* however, other clients will be able to read intermediate states of the output collection.
69+
* Otherwise the map reduce operation must lock the database during post-processing.
70+
*
71+
* @return the same {@code MapReduceOutput} instance as used for the method invocation for chaining
72+
*/
3473
public MapReduceOutput nonAtomic() {
3574
this.nonAtomic = true;
3675
return this;
@@ -57,8 +96,22 @@ public boolean isNonAtomic() {
5796
}
5897

5998
public static enum Action {
99+
/**
100+
* Replace the contents of the <collectionName> if the collection with the <collectionName> exists.
101+
*/
60102
REPLACE("replace"),
103+
104+
/**
105+
* Merge the new result with the existing result if the output collection already exists.
106+
* If an existing document has the same key as the new result, overwrite that existing document.
107+
*/
61108
MERGE("merge"),
109+
110+
/**
111+
* Merge the new result with the existing result if the output collection already exists.
112+
* If an existing document has the same key as the new result, apply the reduce function
113+
* to both the new and the existing documents and overwrite the existing document with the result.
114+
*/
62115
REDUCE("reduce");
63116

64117
private String value;

0 commit comments

Comments
 (0)