001/*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
005 *
006 * The contents of this file are subject to the terms of either the GNU
007 * General Public License Version 2 only ("GPL") or the Common Development
008 * and Distribution License("CDDL") (collectively, the "License").  You
009 * may not use this file except in compliance with the License.  You can
010 * obtain a copy of the License at
011 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
012 * or LICENSE.txt.  See the License for the specific
013 * language governing permissions and limitations under the License.
014 *
015 * When distributing the software, include this License Header Notice in each
016 * file and include the License file at LICENSE.txt.
017 *
018 * GPL Classpath Exception:
019 * Oracle designates this particular file as subject to the "Classpath"
020 * exception as provided by Oracle in the GPL Version 2 section of the License
021 * file that accompanied this code.
022 *
023 * Modifications:
024 * If applicable, add the following below the License Header, with the fields
025 * enclosed by brackets [] replaced by your own identifying information:
026 * "Portions Copyright [year] [name of copyright owner]"
027 *
028 * Contributor(s):
029 * If you wish your version of this file to be governed by only the CDDL or
030 * only the GPL Version 2, indicate your decision by adding "[Contributor]
031 * elects to include this software in this distribution under the [CDDL or GPL
032 * Version 2] license."  If you don't indicate a single choice of license, a
033 * recipient has the option to distribute your version of this file under
034 * either the CDDL, the GPL Version 2 or to extend the choice of license to
035 * its licensees as provided above.  However, if you add GPL Version 2 code
036 * and therefore, elected the GPL Version 2 license, then the option applies
037 * only if the new code is made subject to such option by the copyright
038 * holder.
039 */
040
041package javax.json;
042
043import java.util.Map;
044
045/**
046 * {@code JsonObject} class represents an immutable JSON object value
047 * (an unordered collection of zero or more name/value pairs).
048 * It also provides unmodifiable map view to the JSON object
049 * name/value mappings.
050 *
051 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonObject>
052 * 
053 * <BR /><BR />A JsonObject instance can be created from an input source using
054 * {@link JsonReader#readObject()}. For example:
055 * 
056 * <BR /><DIV CLASS=SNIP>{@code
057 * JsonReader jsonReader    = Json.createReader(...);
058 * JsonObject object        = jsonReader.readObject();
059 * 
060 * jsonReader.close();
061 * }</DIV>
062 *
063 * <BR /><BR />It can also be built from scratch using a {@link JsonObjectBuilder}.
064 *
065 * <BR /><BR /><B STYLE='color:red'>EXAMPLE 1:</B> An empty JSON object can be built as follows:
066 * 
067 * <BR /><DIV CLASS=SNIP>{@code
068 * JsonObject object = Json.createObjectBuilder().build();
069 * }</DIV>
070 *
071 * <BR /><BR /><B STYLE='color:red'>EXAMPLE 2:</B> The following JSON
072 * 
073 * <DIV CLASS=JSON>{@code
074 * {
075 *     "firstName": "John", "lastName": "Smith", "age": 25,
076 *     "address" : {
077 *         "streetAddress": "21 2nd Street",
078 *         "city": "New York",
079 *         "state": "NY",
080 *         "postalCode": "10021"
081 *     },
082 *     "phoneNumber": [
083 *         { "type": "home", "number": "212 555-1234" },
084 *         { "type": "fax", "number": "646 555-4567" }
085 *     ]
086 * }
087 * }</DIV>
088 * 
089 * <BR />Can be built using :
090 * 
091 * <DIV CLASS=EXAMPLE>{@code
092 * JsonObject value = Json
093 *      .createObjectBuilder()
094 *      .add("firstName", "John")
095 *      .add("lastName", "Smith")
096 *      .add("age", 25)
097 *      .add("address", Json.createObjectBuilder()
098 *          .add("streetAddress", "21 2nd Street")
099 *          .add("city", "New York")
100 *          .add("state", "NY")
101 *          .add("postalCode", "10021"))
102 *      .add("phoneNumber", Json.createArrayBuilder()
103 *          .add(Json.createObjectBuilder()
104 *              .add("type", "home")
105 *              .add("number", "212 555-1234"))
106 *          .add(Json.createObjectBuilder()
107 *              .add("type", "fax")
108 *              .add("number", "646 555-4567")))
109 *      .build();
110 * }</DIV>
111 *
112 * <BR /><BR />{@code JsonObject} can be written to JSON as follows:
113 * 
114 * <BR /><DIV CLASS=SNIP>{@code
115 * JsonWriter writer    = ...
116 * JsonObject obj       = ...;
117 * 
118 * writer.writeObject(obj);
119 * }</DIV>
120 *
121 * <BR /><BR />
122 * {@code JsonObject} values can be {@link JsonObject}, {@link JsonArray},
123 * {@link JsonString}, {@link JsonNumber}, {@link JsonValue#TRUE},
124 * {@link JsonValue#FALSE}, {@link JsonValue#NULL}. These values can be
125 * accessed using various accessor methods.
126 * 
127 * <BR /><BR />In the above example 2, "John" can be got using
128 * 
129 * <BR /><DIV CLASS=SNIP>{@code
130 * String firstName = object.getString("firstName");
131 * }</DIV>
132 *
133 * <BR /><BR />This map object provides read-only access to the JSON object data,
134 * and attempts to modify the map, whether direct or via its collection
135 * views, result in an {@code UnsupportedOperationException}.
136 *
137 * <BR /><BR />The map object's iteration ordering is based on the order in which
138 * name/value pairs are added to the corresponding builder or the order
139 * in which name/value pairs appear in the corresponding stream.
140 */
141public interface JsonObject extends JsonStructure, Map<String, JsonValue> {
142
143    /**
144     * Returns the array value to which the specified name is mapped.
145     * This is a convenience method for {@code (JsonArray)get(name)} to
146     * get the value.
147     *
148     * @param name the name whose associated value is to be returned
149     * @return the array 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 JsonArray type
153     */
154    JsonArray getJsonArray(String name);
155
156    /**
157     * Returns the object value to which the specified name is mapped.
158     * This is a convenience method for {@code (JsonObject)get(name)} to
159     * get the value.
160     *
161     * @param name the name whose associated value is to be returned
162     * @return the object 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 JsonObject type
166     */
167    JsonObject getJsonObject(String name);
168
169    /**
170     * Returns the number value to which the specified name is mapped.
171     * This is a convenience method for {@code (JsonNumber)get(name)} to
172     * get the value.
173     *
174     * @param name the name whose associated value is to be returned
175     * @return the number 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 JsonNumber type
179     */
180    JsonNumber getJsonNumber(String name);
181
182    /**
183     * Returns the string value to which the specified name is mapped.
184     * This is a convenience method for {@code (JsonString)get(name)} to
185     * get the value.
186     *
187     * @param name the name whose associated value is to be returned
188     * @return the string value to which the specified name is mapped, or
189     *         {@code null} if this object contains no mapping for the name
190     * @throws ClassCastException if the value to which the specified name
191     * is mapped is not assignable to JsonString type
192     */
193    JsonString getJsonString(String name);
194
195    /**
196     * A convenience method for
197     * {@code getJsonString(name).getString()}
198     *
199     * @param name whose associated value is to be returned as String
200     * @return the String value to which the specified name is mapped
201     * @throws NullPointerException if the specified name doesn't have any
202     * mapping
203     * @throws ClassCastException if the value for specified name mapping
204     * is not assignable to JsonString
205     */
206    String getString(String name);
207
208    /**
209     * Returns the string value of the associated {@code JsonString} mapping
210     * for the specified name. If {@code JsonString} is found, then its
211     * {@link javax.json.JsonString#getString()} is returned. Otherwise,
212     * the specified default value is returned.
213     *
214     * @param name whose associated value is to be returned as String
215     * @param defaultValue a default value to be returned
216     * @return the string value of the associated mapping for the name,
217     * or the default value
218     */
219    String getString(String name, String defaultValue);
220
221    /**
222     * A convenience method for
223     * {@code getJsonNumber(name).intValue()}
224     *
225     * @param name whose associated value is to be returned as int
226     * @return the int value to which the specified name is mapped
227     * @throws NullPointerException if the specified name doesn't have any
228     * mapping
229     * @throws ClassCastException if the value for specified name mapping
230     * is not assignable to JsonNumber
231     */
232    int getInt(String name);
233
234    /**
235     * Returns the int value of the associated {@code JsonNumber} mapping
236     * for the specified name. If {@code JsonNumber} is found, then its
237     * {@link javax.json.JsonNumber#intValue()} is returned. Otherwise,
238     * the specified default value is returned.
239     *
240     * @param name whose associated value is to be returned as int
241     * @param defaultValue a default value to be returned
242     * @return the int value of the associated mapping for the name,
243     * or the default value
244     */
245    int getInt(String name, int defaultValue);
246
247    /**
248     * Returns the boolean value of the associated mapping for the specified
249     * name. If the associated mapping is JsonValue.TRUE, then returns true.
250     * If the associated mapping is JsonValue.FALSE, then returns false.
251     *
252     * @param name whose associated value is to be returned as boolean
253     * @return the boolean value to which the specified name is mapped
254     * @throws NullPointerException if the specified name doesn't have any
255     * mapping
256     * @throws ClassCastException if the value for specified name mapping
257     * is not assignable to JsonValue.TRUE or JsonValue.FALSE
258     */
259    boolean getBoolean(String name);
260
261    /**
262     * Returns the boolean value of the associated mapping for the specified
263     * name. If the associated mapping is JsonValue.TRUE, then returns true.
264     * If the associated mapping is JsonValue.FALSE, then returns false.
265     * Otherwise, the specified default value is returned.
266     *
267     * @param name whose associated value is to be returned as int
268     * @param defaultValue a default value to be returned
269     * @return the boolean value of the associated mapping for the name,
270     * or the default value
271     */
272    boolean getBoolean(String name, boolean defaultValue);
273
274    /**
275     * Returns {@code true} if the associated value for the specified name is
276     * {@code JsonValue.NULL}.
277     *
278     * @param name name whose associated value is checked
279     * @return return true if the associated value is {@code JsonValue.NULL},
280     * otherwise false
281     * @throws NullPointerException if the specified name doesn't have any
282     * mapping
283     */
284    boolean isNull(String name);
285
286}