View Javadoc
1   /*
2    * #%L
3    * AggregationProjectFields.java - mongodb-async-driver - Allanbank Consulting, Inc.
4    * %%
5    * Copyright (C) 2011 - 2014 Allanbank Consulting, Inc.
6    * %%
7    * Licensed under the Apache License, Version 2.0 (the "License");
8    * you may not use this file except in compliance with the License.
9    * You may obtain a copy of the License at
10   * 
11   *      http://www.apache.org/licenses/LICENSE-2.0
12   * 
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   * #L%
19   */
20  
21  package com.allanbank.mongodb.builder;
22  
23  import java.util.ArrayList;
24  import java.util.Collections;
25  import java.util.List;
26  
27  import com.allanbank.mongodb.bson.element.IntegerElement;
28  
29  /**
30   * AggregationProjectFields holds the information for the fields to copy from
31   * the input documents when using the aggregate command's
32   * {@link Aggregate.Builder#project $project} pipeline operator.
33   * 
34   * @see <a href=
35   *      "http://docs.mongodb.org/manual/reference/aggregation/#_S_project">MongoDB
36   *      Aggregate Command $project Operator</a>
37   * 
38   * @api.yes This class is part of the driver's API. Public and protected members
39   *          will be deprecated for at least 1 non-bugfix release (version
40   *          numbers are &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;) before being
41   *          removed or modified.
42   * @copyright 2012-2013, Allanbank Consulting, Inc., All Rights Reserved
43   */
44  public class AggregationProjectFields {
45      /**
46       * Helper method to create a {@link AggregationProjectFields} that
47       * implicitly includes the _id field.
48       * 
49       * @param fields
50       *            The fields to be included.
51       * @return The {@link AggregationProjectFields}.
52       */
53      public static AggregationProjectFields include(final String... fields) {
54          return new AggregationProjectFields(fields);
55  
56      }
57  
58      /**
59       * Helper method to create a {@link AggregationProjectFields} that does not
60       * include the _id field.
61       * 
62       * @param fields
63       *            The fields to be included.
64       * @return The {@link AggregationProjectFields}.
65       */
66      public static AggregationProjectFields includeWithoutId(
67              final String... fields) {
68          return new AggregationProjectFields(false, fields);
69      }
70  
71      /**
72       * The elements describing the fields to be included (and if the _id should
73       * be excluded).
74       */
75      private final List<IntegerElement> myElements;
76  
77      /**
78       * Creates a new AggregationProjectFields.
79       * 
80       * @param includeId
81       *            If false then the _id field will be excluded from the fields
82       *            in the results of the <tt>$project</tt> operation.
83       * @param fields
84       *            The fields to include in the results of the <tt>$project</tt>
85       *            operation.
86       */
87      public AggregationProjectFields(final boolean includeId,
88              final String... fields) {
89          final List<IntegerElement> elements = new ArrayList<IntegerElement>(
90                  fields.length + 1);
91          if (!includeId) {
92              elements.add(new IntegerElement("_id", 0));
93          }
94          for (final String field : fields) {
95              elements.add(new IntegerElement(field, 1));
96          }
97  
98          myElements = Collections.unmodifiableList(elements);
99      }
100 
101     /**
102      * Creates a new AggregationProjectFields.
103      * 
104      * @param fields
105      *            The fields to include in the results of the <tt>$project</tt>
106      *            operation.
107      */
108     public AggregationProjectFields(final String... fields) {
109         this(true, fields);
110     }
111 
112     /**
113      * Returns the elements describing the fields to be included (and if the _id
114      * should be excluded).
115      * 
116      * @return The elements describing the fields to be included (and if the _id
117      *         should be excluded).
118      */
119     public List<IntegerElement> toElements() {
120         return myElements;
121     }
122 }