![[Jenkins]](/ci/static/9dfc6a38/images/svgs/logo.svg){kind=logo}
Package: Finder$SortDirection
Finder$SortDirection
| name | instruction | branch | complexity | line | method | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Finder.SortDirection(String, int, int) |
|
|
|
|
|
||||||||||||||||||||
| intValue() |
|
|
|
|
|
||||||||||||||||||||
| static {...} |
|
|
|
|
|
||||||||||||||||||||
Coverage
1: /*
2: * #%L
3: * *********************************************************************************************************************
4: *
5: * These Foolish Things - Miscellaneous utilities
6: * http://thesefoolishthings.tidalwave.it - git clone git@bitbucket.org:tidalwave/thesefoolishthings-src.git
7: * %%
8: * Copyright (C) 2009 - 2018 Tidalwave s.a.s. (http://tidalwave.it)
9: * %%
10: * *********************************************************************************************************************
11: *
12: * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
13: * the License. You may obtain a copy of the License at
14: *
15: * http://www.apache.org/licenses/LICENSE-2.0
16: *
17: * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
18: * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
19: * specific language governing permissions and limitations under the License.
20: *
21: * *********************************************************************************************************************
22: *
23: * $Id$
24: *
25: * *********************************************************************************************************************
26: * #L%
27: */
28: package it.tidalwave.util;
29:
30: import javax.annotation.Nonnegative;
31: import javax.annotation.Nonnull;
32: import java.util.List;
33: import java.io.Serializable;
34:
35: /***********************************************************************************************************************
36: *
37: * A factory for providing results of a search. {@code Finder} implementations must be <em>immutable</em>.
38: *
39: * @author Fabrizio Giudici
40: * @version $Id$
41: * @it.tidalwave.javadoc.draft
42: *
43: **********************************************************************************************************************/
44: public interface Finder<TYPE> extends Cloneable, Serializable
45: {
46: /*******************************************************************************************************************
47: *
48: * A tag interface to mark objects which are meaningful sort criteria that can be passed to
49: * {@link Finder#sort(it.tidalwave.util.Finder.SortCriterion)}. In general, a {@code SortCriterion} is just a
50: * behaviourless and methodless object, that should be specifically handled by concrete implementations of
51: * {@link Finder}. The only exceptions are {@link FilterSortCriterion} objects.
52: *
53: ******************************************************************************************************************/
54: public static interface SortCriterion
55: {
56: //@bluebook-ignore-begin
57: public static final Class<SortCriterion> SortCriterion = SortCriterion.class;
58:
59: /** A special {@link SortCriterion} which indicates that no sort has been performed. */
60: public static final SortCriterion UNSORTED = new FilterSortCriterion<Object>()
61: {
62: public void sort (final @Nonnull List<?> results, final @Nonnull SortDirection sortDirection)
63: {
64: }
65: };
66:
67: public static final SortCriterion DEFAULT = UNSORTED;
68: //@bluebook-ignore-end
69: }
70:
71: /*******************************************************************************************************************
72: *
73: * An interface that should be implemented by specific {@link SortCriterion} objects which are capable to implement
74: * by themselves the sorting of objects, by post-processing an existing collection of objects. While this is often
75: * convenient, it is possible for it to be inefficient in cases in which the original source of objects is capable
76: * to perform the sort in an optimized way (e.g. a SQL database by means of {@code ORDER BY}}. The facility class
77: * {@link FinderSupport} supports {@code FilterSortCriterion} objects out of the box. A convenient partial
78: * implementation of {@code FilterSortCriterion} is {@link DefaultFilterSortCriterion}.
79: *
80: ******************************************************************************************************************/
81: public static interface FilterSortCriterion<TYPE> extends SortCriterion
82: {
83: /***************************************************************************************************************
84: *
85: * Performs the sort of results.
86: *
87: * @param results the list of objects to be sorted in place
88: * @param sortDirection the sort direction
89: *
90: **************************************************************************************************************/
91: @Nonnull
92: public void sort (@Nonnull List<? extends TYPE> results, @Nonnull SortDirection sortDirection);
93: }
94:
95: /*******************************************************************************************************************
96: *
97: * An enumeration to define the direction of a sort (ascending or descending).
98: *
99: * @it.tidalwave.javadoc.stable
100: *
101: ******************************************************************************************************************/
102: public static enum SortDirection
103: {
104: ASCENDING(+1), DESCENDING(-1);
105: //@bluebook-ignore-begin
106:
107: private final int intValue;
108:
109: private SortDirection (final int intValue)
110: {
111: this.intValue = intValue;
112: }
113:
114: /** @return +1 for ascending direction, -1 for descending */
115: public int intValue()
116: {
117: return intValue;
118: }
119: //@bluebook-ignore-end
120: }
121:
122: /*******************************************************************************************************************
123: *
124: * Tells the {@code Finder} that only a subset of found items will be returned, starting from the given position.
125: *
126: * @param firstResult the index of the first result to return
127: * @return the {@code Finder}
128: *
129: ******************************************************************************************************************/
130: @Nonnull
131: public Finder<TYPE> from (@Nonnegative int firstResult);
132:
133: /*******************************************************************************************************************
134: *
135: * Tells the {@code Finder} that only a maximum number of found items will be returned.
136: *
137: * @param maxResults the max number of results to return
138: * @return the {@code Finder}
139: *
140: ******************************************************************************************************************/
141: @Nonnull
142: public Finder<TYPE> max (@Nonnegative int maxResults);
143:
144: /*******************************************************************************************************************
145: *
146: * Tells the {@code Finder} that results should be created with the given context. This method can be called
147: * multiple times; contexts are accumulated.
148: *
149: * @param context the context
150: * @return the {@code Finder}
151: *
152: ******************************************************************************************************************/
153: @Nonnull
154: public Finder<TYPE> withContext (@Nonnull Object context);
155:
156: /*******************************************************************************************************************
157: *
158: * Tells the {@code Finder} that the specified type of results is expected.
159: *
160: * @param type the expected type of results
161: * @return the {@code Finder}
162: *
163: ******************************************************************************************************************/
164: @Nonnull
165: public <AnotherType> Finder<AnotherType> ofType (@Nonnull Class<AnotherType> type);
166:
167: /*******************************************************************************************************************
168: *
169: * Tells the {@code Finder} that results will be sorted according to the given criterion, in ascending direction.
170: *
171: * @param criterion the sort criterion
172: * @return the {@code Finder}
173: *
174: ******************************************************************************************************************/
175: @Nonnull
176: public Finder<TYPE> sort (@Nonnull SortCriterion criterion);
177:
178: /*******************************************************************************************************************
179: *
180: * Tells the {@code Finder} that results will be sorted according to the given criterion and direction.
181: *
182: * @param criterion the sort criterion
183: * @param direction the sort direction
184: * @return the {@code Finder}
185: *
186: ******************************************************************************************************************/
187: @Nonnull
188: public Finder<TYPE> sort (@Nonnull SortCriterion criterion, @Nonnull SortDirection direction);
189:
190: /*******************************************************************************************************************
191: *
192: * Performs the search assuming that it will return a single item and returns it. This method fails if the search
193: * returns more than one single item.
194: *
195: * @return the found item
196: * @throws NotFoundException if the search didn't find anything
197: * @throws RuntimeException if the search returned more than one single item
198: *
199: ******************************************************************************************************************/
200: @Nonnull
201: public TYPE result()
202: throws NotFoundException, RuntimeException;
203:
204: /*******************************************************************************************************************
205: *
206: * Performs the search and returns only the first found item.
207: *
208: * @return the first found item
209: * @throws NotFoundException if the search didn't find anything
210: *
211: ******************************************************************************************************************/
212: @Nonnull
213: public TYPE firstResult()
214: throws NotFoundException;
215:
216: /*******************************************************************************************************************
217: *
218: * Performs the search and returns the found items.
219: *
220: * @return the searched items
221: *
222: ******************************************************************************************************************/
223: @Nonnull
224: public List<? extends TYPE> results();
225:
226: /*******************************************************************************************************************
227: *
228: * Performs the search and returns the count of found items.
229: *
230: * @return the count of found items
231: *
232: ******************************************************************************************************************/
233: @Nonnegative
234: public int count();
235: }