source: josm/trunk/src/javax/json/JsonObject.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: 10.8 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.Map;
44
45/**
46 * {@code JsonObject} class represents an immutable JSON object value
47 * (an unordered collection of zero or more name/value pairs).
48 * It also provides unmodifiable map view to the JSON object
49 * name/value mappings.
50 *
51 * <p>A JsonObject instance can be created from an input source using
52 * {@link JsonReader#readObject()}. For example:
53 * <pre><code>
54 * JsonReader jsonReader = Json.createReader(...);
55 * JsonObject object = jsonReader.readObject();
56 * jsonReader.close();
57 * </code></pre>
58 *
59 * It can also be built from scratch using a {@link JsonObjectBuilder}.
60 *
61 * <p>For example 1: An empty JSON object can be built as follows:
62 * <pre><code>
63 * JsonObject object = Json.createObjectBuilder().build();
64 * </code></pre>
65 *
66 * For example 2: The following JSON
67 * <pre><code>
68 * {
69 * "firstName": "John", "lastName": "Smith", "age": 25,
70 * "address" : {
71 * "streetAddress": "21 2nd Street",
72 * "city": "New York",
73 * "state": "NY",
74 * "postalCode": "10021"
75 * },
76 * "phoneNumber": [
77 * { "type": "home", "number": "212 555-1234" },
78 * { "type": "fax", "number": "646 555-4567" }
79 * ]
80 * }
81 * </code></pre>
82 * can be built using :
83 * <pre><code>
84 * JsonObject value = Json.createObjectBuilder()
85 * .add("firstName", "John")
86 * .add("lastName", "Smith")
87 * .add("age", 25)
88 * .add("address", Json.createObjectBuilder()
89 * .add("streetAddress", "21 2nd Street")
90 * .add("city", "New York")
91 * .add("state", "NY")
92 * .add("postalCode", "10021"))
93 * .add("phoneNumber", Json.createArrayBuilder()
94 * .add(Json.createObjectBuilder()
95 * .add("type", "home")
96 * .add("number", "212 555-1234"))
97 * .add(Json.createObjectBuilder()
98 * .add("type", "fax")
99 * .add("number", "646 555-4567")))
100 * .build();
101 * </code></pre>
102 *
103 * {@code JsonObject} can be written to JSON as follows:
104 * <pre><code>
105 * JsonWriter writer = ...
106 * JsonObject obj = ...;
107 * writer.writeObject(obj);
108 * </code></pre>
109 *
110 * {@code JsonObject} values can be {@link JsonObject}, {@link JsonArray},
111 * {@link JsonString}, {@link JsonNumber}, {@link JsonValue#TRUE},
112 * {@link JsonValue#FALSE}, {@link JsonValue#NULL}. These values can be
113 * accessed using various accessor methods.
114 *
115 * <p>In the above example 2, "John" can be got using
116 * <pre><code>
117 * String firstName = object.getString("firstName");
118 * </code></pre>
119 *
120 * This map object provides read-only access to the JSON object data,
121 * and attempts to modify the map, whether direct or via its collection
122 * views, result in an {@code UnsupportedOperationException}.
123 *
124 * <p>The map object's iteration ordering is based on the order in which
125 * name/value pairs are added to the corresponding builder or the order
126 * in which name/value pairs appear in the corresponding stream.
127 */
128public interface JsonObject extends JsonStructure, Map<String, JsonValue> {
129
130 /**
131 * Returns the array value to which the specified name is mapped.
132 * This is a convenience method for {@code (JsonArray)get(name)} to
133 * get the value.
134 *
135 * @param name the name whose associated value is to be returned
136 * @return the array value to which the specified name is mapped, or
137 * {@code null} if this object contains no mapping for the name
138 * @throws ClassCastException if the value to which the specified name
139 * is mapped is not assignable to JsonArray type
140 */
141 JsonArray getJsonArray(String name);
142
143 /**
144 * Returns the object value to which the specified name is mapped.
145 * This is a convenience method for {@code (JsonObject)get(name)} to
146 * get the value.
147 *
148 * @param name the name whose associated value is to be returned
149 * @return the object value to which the specified name is mapped, or
150 * {@code null} if this object contains no mapping for the name
151 * @throws ClassCastException if the value to which the specified name
152 * is mapped is not assignable to JsonObject type
153 */
154 JsonObject getJsonObject(String name);
155
156 /**
157 * Returns the number value to which the specified name is mapped.
158 * This is a convenience method for {@code (JsonNumber)get(name)} to
159 * get the value.
160 *
161 * @param name the name whose associated value is to be returned
162 * @return the number value to which the specified name is mapped, or
163 * {@code null} if this object contains no mapping for the name
164 * @throws ClassCastException if the value to which the specified name
165 * is mapped is not assignable to JsonNumber type
166 */
167 JsonNumber getJsonNumber(String name);
168
169 /**
170 * Returns the string value to which the specified name is mapped.
171 * This is a convenience method for {@code (JsonString)get(name)} to
172 * get the value.
173 *
174 * @param name the name whose associated value is to be returned
175 * @return the string value to which the specified name is mapped, or
176 * {@code null} if this object contains no mapping for the name
177 * @throws ClassCastException if the value to which the specified name
178 * is mapped is not assignable to JsonString type
179 */
180 JsonString getJsonString(String name);
181
182 /**
183 * A convenience method for
184 * {@code getJsonString(name).getString()}
185 *
186 * @param name whose associated value is to be returned as String
187 * @return the String value to which the specified name is mapped
188 * @throws NullPointerException if the specified name doesn't have any
189 * mapping
190 * @throws ClassCastException if the value for specified name mapping
191 * is not assignable to JsonString
192 */
193 String getString(String name);
194
195 /**
196 * Returns the string value of the associated {@code JsonString} mapping
197 * for the specified name. If {@code JsonString} is found, then its
198 * {@link javax.json.JsonString#getString()} is returned. Otherwise,
199 * the specified default value is returned.
200 *
201 * @param name whose associated value is to be returned as String
202 * @param defaultValue a default value to be returned
203 * @return the string value of the associated mapping for the name,
204 * or the default value
205 */
206 String getString(String name, String defaultValue);
207
208 /**
209 * A convenience method for
210 * {@code getJsonNumber(name).intValue()}
211 *
212 * @param name whose associated value is to be returned as int
213 * @return the int value to which the specified name is mapped
214 * @throws NullPointerException if the specified name doesn't have any
215 * mapping
216 * @throws ClassCastException if the value for specified name mapping
217 * is not assignable to JsonNumber
218 */
219 int getInt(String name);
220
221 /**
222 * Returns the int value of the associated {@code JsonNumber} mapping
223 * for the specified name. If {@code JsonNumber} is found, then its
224 * {@link javax.json.JsonNumber#intValue()} is returned. Otherwise,
225 * the specified default value is returned.
226 *
227 * @param name whose associated value is to be returned as int
228 * @param defaultValue a default value to be returned
229 * @return the int value of the associated mapping for the name,
230 * or the default value
231 */
232 int getInt(String name, int defaultValue);
233
234 /**
235 * Returns the boolean value of the associated mapping for the specified
236 * name. If the associated mapping is JsonValue.TRUE, then returns true.
237 * If the associated mapping is JsonValue.FALSE, then returns false.
238 *
239 * @param name whose associated value is to be returned as boolean
240 * @return the boolean value to which the specified name is mapped
241 * @throws NullPointerException if the specified name doesn't have any
242 * mapping
243 * @throws ClassCastException if the value for specified name mapping
244 * is not assignable to JsonValue.TRUE or JsonValue.FALSE
245 */
246 boolean getBoolean(String name);
247
248 /**
249 * Returns the boolean value of the associated mapping for the specified
250 * name. If the associated mapping is JsonValue.TRUE, then returns true.
251 * If the associated mapping is JsonValue.FALSE, then returns false.
252 * Otherwise, the specified default value is returned.
253 *
254 * @param name whose associated value is to be returned as int
255 * @param defaultValue a default value to be returned
256 * @return the boolean value of the associated mapping for the name,
257 * or the default value
258 */
259 boolean getBoolean(String name, boolean defaultValue);
260
261 /**
262 * Returns {@code true} if the associated value for the specified name is
263 * {@code JsonValue.NULL}.
264 *
265 * @param name name whose associated value is checked
266 * @return return true if the associated value is {@code JsonValue.NULL},
267 * otherwise false
268 * @throws NullPointerException if the specified name doesn't have any
269 * mapping
270 */
271 boolean isNull(String name);
272
273}
Note: See TracBrowser for help on using the repository browser.