Package: StorableListResult

StorableListResult

Coverage

1: /*******************************************************************************
2: * Copyright (c) 2016, 2022 Eurotech and/or its affiliates and others
3: *
4: * This program and the accompanying materials are made
5: * available under the terms of the Eclipse Public License 2.0
6: * which is available at https://www.eclipse.org/legal/epl-2.0/
7: *
8: * SPDX-License-Identifier: EPL-2.0
9: *
10: * Contributors:
11: * Eurotech - initial API and implementation
12: *******************************************************************************/
13: package org.eclipse.kapua.service.storable.model;
14:
15: import org.eclipse.kapua.KapuaSerializable;
16: import org.eclipse.kapua.model.query.KapuaQuery;
17: import org.eclipse.kapua.service.storable.model.query.StorableQuery;
18:
19: import javax.validation.constraints.NotNull;
20: import javax.xml.bind.annotation.XmlAccessType;
21: import javax.xml.bind.annotation.XmlAccessorType;
22: import javax.xml.bind.annotation.XmlElement;
23: import javax.xml.bind.annotation.XmlElementWrapper;
24: import javax.xml.bind.annotation.XmlRootElement;
25: import javax.xml.bind.annotation.XmlType;
26: import java.util.Collection;
27: import java.util.List;
28:
29: /**
30: * {@link StorableListResult} definition.
31: * <p>
32: * It is the base {@code interface} for all list of {@link Storable}s
33: *
34: * @param <E> The {@link Storable} for which this is a {@link StorableListResult} for.
35: * @since 1.0.0
36: */
37: @XmlRootElement(name = "result")
38: @XmlAccessorType(XmlAccessType.PROPERTY)
39: @XmlType(propOrder = {"limitExceeded", "size", "items", "nextKey", "totalCount"})
40: public interface StorableListResult<E extends Storable> extends KapuaSerializable {
41:
42: /**
43: * Gets whether or not the {@link StorableQuery#getLimit()} has been exceeded.
44: * <p>
45: * When {@code true} it means that there are more {@link Storable}s to fetch.
46: *
47: * @return {@code true} if the {@link StorableQuery#getLimit()} has been exceeded, {@code false} otherwise.
48: * @since 1.0.0
49: */
50: @XmlElement(name = "limitExceeded")
51: boolean isLimitExceeded();
52:
53: /**
54: * Sets whether or not the {@link StorableQuery#getLimit()} has been exceeded.
55: *
56: * @param limitExceeded {@code true} if the {@link StorableQuery#getLimit()} has been exceeded, {@code false} otherwise.
57: * @since 1.0.0
58: */
59: void setLimitExceeded(boolean limitExceeded);
60:
61: /**
62: * Gets the {@link Storable}s
63: *
64: * @return The {@link Storable}s
65: * @since 1.0.0
66: */
67: @XmlElementWrapper(name = "items")
68: @XmlElement(name = "item")
69: List<E> getItems();
70:
71: /**
72: * Gets the {@link Storable} at the given position in the {@link StorableListResult}.
73: *
74: * @param i The position in the {@link StorableListResult}
75: * @return The {@link Storable} at the position
76: * @throws IndexOutOfBoundsException If position is not available.
77: * @see List#get(int)
78: * @since 1.0.0
79: */
80: E getItem(int i);
81:
82: /**
83: * Returns the first element in the {@link StorableListResult}.
84: * <p>
85: * It returns {@code null} if first element does not exist.
86: *
87: * @return The first element in the {@link Storable} or {@code null} if not present.
88: * @since 1.0.0
89: */
90: E getFirstItem();
91:
92: /**
93: * Gets the result {@link StorableListResult} size.
94: *
95: * @return The result list size.
96: * @see List#size()
97: * @since 1.0.0
98: */
99: @XmlElement(name = "size")
100: int getSize();
101:
102: /**
103: * Checks if the result {@link StorableListResult} is empty.
104: *
105: * @return {@code true} if the result list is empty, {@code false} otherwise.
106: * @see List#isEmpty()
107: * @since 1.0.0
108: */
109: boolean isEmpty();
110:
111: /**
112: * Adds {@link Storable}s to the result {@link StorableListResult}
113: *
114: * @param items The {@link Storable}s to add.
115: * @see List#addAll(Collection)
116: * @since 1.0.0
117: */
118: void addItems(Collection<? extends E> items);
119:
120: /**
121: * Adds a {@link Storable} to the {@link StorableListResult}.
122: *
123: * @param item The {@link Storable} to add.
124: * @since 1.3.0
125: */
126: void addItem(@NotNull E item);
127:
128: /**
129: * Clears {@link Storable} result {@link StorableListResult}
130: *
131: * @see List#clear()
132: * @since 1.0.0
133: */
134: void clearItems();
135:
136: /**
137: * Get the next key.
138: * <p>
139: * If a limit is set into the query parameters (limit) and the messages count matching the query is higher than the limit, so the next key is the key of the first next object not included in the
140: * result set.
141: *
142: * @return The next key.
143: * @since 1.0.0
144: */
145: @XmlElement(name = "nextKey")
146: Object getNextKey();
147:
148: /**
149: * Gets the total count of {@link Storable}s that match the {@link StorableQuery#getPredicate()}s regardless of {@link StorableQuery#getLimit()} and {@link StorableQuery#getOffset()}
150: *
151: * @return The total count
152: * @since 1.0.0
153: */
154: Long getTotalCount();
155:
156: /**
157: * Sets the total count of {@link Storable}s that match the {@link KapuaQuery#getPredicate()}s regardless of {@code limit} and {@code offset}
158: *
159: * @param totalCount
160: * @since 1.0.0
161: */
162: @XmlElement(name = "totalCount")
163: void setTotalCount(Long totalCount);
164:
165: }