source: josm/trunk/src/javax/json/JsonArray.java@ 13611

Last change on this file since 13611 was 13231, checked in by Don-vip, 7 years ago

see #15682 - upgrade to JSR 374 (JSON Processing) API 1.1.2

File size: 12.3 KB
Line 
1/*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License("CDDL") (collectively, the "License"). You
9 * may not use this file except in compliance with the License. You can
10 * obtain a copy of the License at
11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
12 * or LICENSE.txt. See the License for the specific
13 * language governing permissions and limitations under the License.
14 *
15 * When distributing the software, include this License Header Notice in each
16 * file and include the License file at LICENSE.txt.
17 *
18 * GPL Classpath Exception:
19 * Oracle designates this particular file as subject to the "Classpath"
20 * exception as provided by Oracle in the GPL Version 2 section of the License
21 * file that accompanied this code.
22 *
23 * Modifications:
24 * If applicable, add the following below the License Header, with the fields
25 * enclosed by brackets [] replaced by your own identifying information:
26 * "Portions Copyright [year] [name of copyright owner]"
27 *
28 * Contributor(s):
29 * If you wish your version of this file to be governed by only the CDDL or
30 * only the GPL Version 2, indicate your decision by adding "[Contributor]
31 * elects to include this software in this distribution under the [CDDL or GPL
32 * Version 2] license." If you don't indicate a single choice of license, a
33 * recipient has the option to distribute your version of this file under
34 * either the CDDL, the GPL Version 2 or to extend the choice of license to
35 * its licensees as provided above. However, if you add GPL Version 2 code
36 * and therefore, elected the GPL Version 2 license, then the option applies
37 * only if the new code is made subject to such option by the copyright
38 * holder.
39 */
40
41package javax.json;
42
43import java.util.List;
44import java.util.function.Function;
45import java.util.stream.Collectors;
46import java.util.stream.Stream;
47
48/**
49 * {@code JsonArray} represents an immutable JSON array
50 * (an ordered sequence of zero or more values).
51 * It also provides an unmodifiable list view of the values in the array.
52 *
53 * <p>A {@code JsonArray} object can be created by reading JSON data from
54 * an input source or it can be built from scratch using an array builder
55 * object.
56 *
57 * <p>The following example demonstrates how to create a {@code JsonArray}
58 * object from an input source using the method {@link JsonReader#readArray()}:
59 * <pre><code>
60 * JsonReader jsonReader = Json.createReader(...);
61 * JsonArray array = jsonReader.readArray();
62 * jsonReader.close();
63 * </code></pre>
64 *
65 * <p>The following example demonstrates how to build an empty JSON array
66 * using the class {@link JsonArrayBuilder}:
67 * <pre><code>
68 * JsonArray array = Json.createArrayBuilder().build();
69 * </code></pre>
70 *
71 * <p>The example code below demonstrates how to create the following JSON array:
72 * <pre><code>
73 * [
74 * { "type": "home", "number": "212 555-1234" },
75 * { "type": "fax", "number": "646 555-4567" }
76 * ]
77 * </code></pre>
78 * <pre><code>
79 * JsonArray value = Json.createArrayBuilder()
80 * .add(Json.createObjectBuilder()
81 * .add("type", "home")
82 * .add("number", "212 555-1234"))
83 * .add(Json.createObjectBuilder()
84 * .add("type", "fax")
85 * .add("number", "646 555-4567"))
86 * .build();
87 * </code></pre>
88 *
89 * <p>The following example demonstrates how to write a {@code JsonArray} object
90 * as JSON data:
91 * <pre><code>
92 * JsonArray arr = ...;
93 * JsonWriter writer = Json.createWriter(...)
94 * writer.writeArray(arr);
95 * writer.close();
96 * </code></pre>
97 *
98 * <p>The values in a {@code JsonArray} can be of the following types:
99 * {@link JsonObject}, {@link JsonArray},
100 * {@link JsonString}, {@link JsonNumber}, {@link JsonValue#TRUE},
101 * {@link JsonValue#FALSE}, and {@link JsonValue#NULL}.
102 * {@code JsonArray} provides various accessor methods to access the values
103 * in an array.
104 *
105 * <p>The following example shows how to obtain the home phone number
106 * "212 555-1234" from the array built in the previous example:
107 * <pre><code>
108 * JsonObject home = array.getJsonObject(0);
109 * String number = home.getString("number");
110 * </code></pre>
111 *
112 * <p>{@code JsonArray} instances are list objects that provide read-only
113 * access to the values in the JSON array. Any attempt to modify the list,
114 * whether directly or using its collection views, results in an
115 * {@code UnsupportedOperationException}.
116 */
117public interface JsonArray extends JsonStructure, List<JsonValue> {
118
119 /**
120 * Returns the object value at the specified position in this array.
121 * This is a convenience method for {@code (JsonObject)get(index)}.
122 *
123 * @param index index of the value to be returned
124 * @return the value at the specified position in this array
125 * @throws IndexOutOfBoundsException if the index is out of range
126 * @throws ClassCastException if the value at the specified position is not
127 * assignable to the JsonObject type
128 */
129 JsonObject getJsonObject(int index);
130
131 /**
132 * Returns the array value at the specified position in this array.
133 * This is a convenience method for {@code (JsonArray)get(index)}.
134 *
135 * @param index index of the value to be returned
136 * @return the value at the specified position in this array
137 * @throws IndexOutOfBoundsException if the index is out of range
138 * @throws ClassCastException if the value at the specified position is not
139 * assignable to the JsonArray type
140 */
141 JsonArray getJsonArray(int index);
142
143 /**
144 * Returns the number value at the specified position in this array.
145 * This is a convenience method for {@code (JsonNumber)get(index)}.
146 *
147 * @param index index of the value to be returned
148 * @return the value at the specified position in this array
149 * @throws IndexOutOfBoundsException if the index is out of range
150 * @throws ClassCastException if the value at the specified position is not
151 * assignable to the JsonNumber type
152 */
153 JsonNumber getJsonNumber(int index);
154
155 /**
156 * Returns the string value at ths specified position in this array.
157 * This is a convenience method for {@code (JsonString)get(index)}.
158 *
159 * @param index index of the value to be returned
160 * @return the value at the specified position in this array
161 * @throws IndexOutOfBoundsException if the index is out of range
162 * @throws ClassCastException if the value at the specified position is not
163 * assignable to the JsonString type
164 */
165 JsonString getJsonString(int index);
166
167 /**
168 * Returns a list view of the specified type for the array. This method
169 * does not verify if there is a value of wrong type in the array. Providing
170 * this typesafe view dynamically may cause a program fail with a
171 * {@code ClassCastException}, if there is a value of wrong type in this
172 * array. Unfortunately, the exception can occur at any time after this
173 * method returns.
174 *
175 * @param <T> The type of the List for the array
176 * @param clazz a JsonValue type
177 * @return a list view of the specified type
178 */
179 <T extends JsonValue> List<T> getValuesAs(Class<T> clazz);
180
181 /**
182 * Returns a list view for the array. The value and the type of the elements
183 * in the list is specified by the {@code func} argument.
184 * <p>This method can be used to obtain a list of the unwrapped types, such as
185 * <pre>{@code
186 * List<String> strings = ary1.getValuesAs(JsonString::getString);
187 * List<Integer> ints = ary2.getValuesAs(JsonNumber::intValue);
188 * } </pre>
189 * or a list of simple projections, such as
190 * <pre> {@code
191 * List<Integer> stringsizes = ary1.getValueAs((JsonString v)->v.getString().length();
192 * } </pre>
193 * @param <K> The element type (must be a subtype of JsonValue) of this JsonArray.
194 * @param <T> The element type of the returned List
195 * @param func The function that maps the elements of this JsonArray to the target elements.
196 * @return A List of the specified values and type.
197 * @throws ClassCastException if the {@code JsonArray} contains a value of wrong type
198 *
199 * @since 1.1
200 */
201 default <T, K extends JsonValue> List<T> getValuesAs(Function<K, T> func) {
202 @SuppressWarnings("unchecked")
203 Stream<K> stream = (Stream<K>) stream();
204 return stream.map(func).collect(Collectors.toList());
205 }
206
207 /**
208 * A convenience method for
209 * {@code getJsonString(index).getString()}.
210 *
211 * @param index index of the {@code JsonString} value
212 * @return the String value at the specified position
213 * @throws IndexOutOfBoundsException if the index is out of range
214 * @throws ClassCastException if the value at the specified position is not
215 * assignable to {@code JsonString}
216 */
217 String getString(int index);
218
219 /**
220 * Returns the {@code String} value of {@code JsonString} at the specified
221 * position in this JSON array values. If {@code JsonString} is found,
222 * its {@link javax.json.JsonString#getString()} is returned. Otherwise,
223 * the specified default value is returned.
224 *
225 * @param index index of the {@code JsonString} value
226 * @param defaultValue the String to return if the {@code JsonValue} at the
227 * specified position is not a {@code JsonString}
228 * @return the String value at the specified position in this array,
229 * or the specified default value
230 */
231 String getString(int index, String defaultValue);
232
233 /**
234 * A convenience method for
235 * {@code getJsonNumber(index).intValue()}.
236 *
237 * @param index index of the {@code JsonNumber} value
238 * @return the int value at the specified position
239 * @throws IndexOutOfBoundsException if the index is out of range
240 * @throws ClassCastException if the value at the specified position is not
241 * assignable to {@code JsonNumber}
242 */
243 int getInt(int index);
244
245 /**
246 * Returns the int value of the {@code JsonNumber} at the specified position.
247 * If the value at that position is a {@code JsonNumber},
248 * this method returns {@link javax.json.JsonNumber#intValue()}. Otherwise
249 * this method returns the specified default value.
250 *
251 * @param index index of the {@code JsonNumber} value
252 * @param defaultValue the int value to return if the {@code JsonValue} at
253 * the specified position is not a {@code JsonNumber}
254 * @return the int value at the specified position in this array,
255 * or the specified default value
256 */
257 int getInt(int index, int defaultValue);
258
259 /**
260 * Returns the boolean value at the specified position.
261 * If the value at the specified position is {@code JsonValue.TRUE}
262 * this method returns {@code true}. If the value at the specified position
263 * is {@code JsonValue.FALSE} this method returns {@code false}.
264 *
265 * @param index index of the JSON boolean value
266 * @return the boolean value at the specified position
267 * @throws IndexOutOfBoundsException if the index is out of range
268 * @throws ClassCastException if the value at the specified position is not
269 * assignable to {@code JsonValue.TRUE} or {@code JsonValue.FALSE}
270 */
271 boolean getBoolean(int index);
272
273 /**
274 * Returns the boolean value at the specified position.
275 * If the value at the specified position is {@code JsonValue.TRUE}
276 * this method returns {@code true}. If the value at the specified position
277 * is {@code JsonValue.FALSE} this method returns {@code false}.
278 * Otherwise this method returns the specified default value.
279 *
280 * @param index index of the JSON boolean value
281 * @param defaultValue the boolean value to return if the {@code JsonValue}
282 * at the specified position is neither TRUE nor FALSE
283 * @return the boolean value at the specified position,
284 * or the specified default value
285 */
286 boolean getBoolean(int index, boolean defaultValue);
287
288 /**
289 * Returns {@code true} if the value at the specified location in this
290 * array is {@code JsonValue.NULL}.
291 *
292 * @param index index of the JSON null value
293 * @return return true if the value at the specified location is
294 * {@code JsonValue.NULL}, otherwise false
295 * @throws IndexOutOfBoundsException if the index is out of range
296 */
297 boolean isNull(int index);
298}
Note: See TracBrowser for help on using the repository browser.