1 package eu.ehri.project.api;
2
3 import eu.ehri.project.models.EntityClass;
4 import eu.ehri.project.models.base.Entity;
5
6 import java.util.Collection;
7 import java.util.Iterator;
8
9
10 public interface QueryApi {
11 int DEFAULT_LIMIT = 20;
12
13 /**
14 * Set the offset of this query.
15 *
16 * @param offset the number of items to skip
17 * @return a new query
18 */
19 QueryApi setOffset(int offset);
20
21 /**
22 * Set the limit of this query.
23 *
24 * @param limit the limit of the number of items returned
25 * @return a new query
26 */
27 QueryApi setLimit(int limit);
28
29 /**
30 * Add a filter predicate.
31 *
32 * @param key a filter key
33 * @param predicate a predicate
34 * @param value the filter predicate
35 * @return a new query with the filter added
36 */
37 QueryApi filter(String key, FilterPredicate predicate, Object value);
38
39 /**
40 * Set all filters for this query, parsing the key/predicate/value
41 * from string values.
42 *
43 * @param filterSpecs a set of filter spec strings
44 * @return a new query with previous filters replaced
45 */
46 QueryApi filter(Collection<String> filterSpecs);
47
48 /**
49 * Set the query result order.
50 *
51 * @param key a order key
52 * @param order an order spec
53 * @return a new query with the ordering added
54 */
55 QueryApi orderBy(String key, Sort order);
56
57 /**
58 * Set all orderings for this query, parsing the key/spec
59 * from string values.
60 *
61 * @param orderSpecs a set of order spec strings
62 * @return a new query with previous filters replaced
63 */
64 QueryApi orderBy(Collection<String> orderSpecs);
65
66 /**
67 * Toggle streaming, which will disable paging totals,
68 * assuming an infinite collection.
69 *
70 * @param stream whether to assume streaming
71 * @return a new query with streaming enable/disabled
72 */
73 QueryApi setStream(boolean stream);
74
75 /**
76 * Return a Page instance containing a total of total items, and an iterable
77 * for the given page/count.
78 */
79 <E extends Entity> Page<E> page(Class<E> cls);
80
81 /**
82 * Return a Page instance containing a total of total items, and an iterable
83 * for the given page/count.
84 */
85 <E extends Entity> Page<E> page(EntityClass type, Class<E> cls);
86
87 /**
88 * Return a Page instance containing a total of total items, and an iterable
89 * for the given page/count.
90 */
91 <E extends Entity> Page<E> page(Iterable<? extends E> entities, Class<E> cls);
92
93 /**
94 * Return a Page instance containing a total of total items, and an iterable
95 * for the given page/count.
96 */
97 <E extends Entity> Page<E> page(String key, String query, Class<E> cls);
98
99 /**
100 * Count items accessible to a given user.
101 */
102 long count(Iterable<?> vertices);
103
104 /**
105 * Count all items of a given type.
106 * <p>
107 * NB: Count doesn't 'account' for ACL privileges!
108 */
109 long count(EntityClass type);
110
111 /**
112 * Directions for sort.
113 */
114 enum Sort {
115 ASC, DESC
116 }
117
118 /**
119 * Filter predicates
120 */
121 enum FilterPredicate {
122 EQUALS, IEQUALS, STARTSWITH, ENDSWITH, CONTAINS, ICONTAINS, MATCHES, GT, GTE, LT, LTE
123 }
124
125 /**
126 * Class representing a page of content.
127 *
128 * @param <T> the item type
129 */
130 class Page<T> implements Iterable<T> {
131 private final Iterable<T> iterable;
132 private final int offset;
133 private final int limit;
134 private final long total;
135
136 public Page(Iterable<T> iterable, int offset, int limit, long total) {
137 this.iterable = iterable;
138 this.total = total;
139 this.offset = offset;
140 this.limit = limit;
141 }
142
143 public Iterable<T> getIterable() {
144 return iterable;
145 }
146
147 public long getTotal() {
148 return total;
149 }
150
151 public Integer getOffset() {
152 return offset;
153 }
154
155 public Integer getLimit() {
156 return limit;
157 }
158
159 @Override
160 public Iterator<T> iterator() {
161 return iterable.iterator();
162 }
163
164 @Override
165 public String toString() {
166 return String.format("<Page[...] %d %d (%d)", offset, limit, total);
167 }
168 }
169 }