gson/com/google/gson/JsonObject.java

   1 /*
   2  * Copyright (C) 2008 Google Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package com.google.gson;
  18
  19 import com.google.gson.internal.LinkedTreeMap;
  20
  21 import java.util.Map;
  22 import java.util.Set;
  23
  24 /**
  25  * A class representing an object type in Json. An object consists of name-value pairs where names
  26  * are strings, and values are any other type of {@link JsonElement}. This allows for a creating a
  27  * tree of JsonElements. The member elements of this object are maintained in order they were added.
  28  *
  29  * @author Inderjeet Singh
  30  * @author Joel Leitch
  31  */
  32 public final class JsonObject extends JsonElement {
  33   private final LinkedTreeMap<String, JsonElement> members =
  34       new LinkedTreeMap<String, JsonElement>();
  35
  36   @Override
  37   JsonObject deepCopy() {
  38     JsonObject result = new JsonObject();
  39     for (Map.Entry<String, JsonElement> entry : members.entrySet()) {
  40       result.add(entry.getKey(), entry.getValue().deepCopy());
  41     }
  42     return result;
  43   }
  44
  45   /**
  46    * Adds a member, which is a name-value pair, to self. The name must be a String, but the value
  47    * can be an arbitrary JsonElement, thereby allowing you to build a full tree of JsonElements
  48    * rooted at this node.
  49    *
  50    * @param property name of the member.
  51    * @param value the member object.
  52    */
  53   public void add(String property, JsonElement value) {
  54     if (value == null) {
  55       value = JsonNull.INSTANCE;
  56     }
  57     members.put(property, value);
  58   }
  59
  60   /**
  61    * Removes the {@code property} from this {@link JsonObject}.
  62    *
  63    * @param property name of the member that should be removed.
  64    * @return the {@link JsonElement} object that is being removed.
  65    * @since 1.3
  66    */
  67   public JsonElement remove(String property) {
  68     return members.remove(property);
  69   }
  70
  71   /**
  72    * Convenience method to add a primitive member. The specified value is converted to a
  73    * JsonPrimitive of String.
  74    *
  75    * @param property name of the member.
  76    * @param value the string value associated with the member.
  77    */
  78   public void addProperty(String property, String value) {
  79     add(property, createJsonElement(value));
  80   }
  81
  82   /**
  83    * Convenience method to add a primitive member. The specified value is converted to a
  84    * JsonPrimitive of Number.
  85    *
  86    * @param property name of the member.
  87    * @param value the number value associated with the member.
  88    */
  89   public void addProperty(String property, Number value) {
  90     add(property, createJsonElement(value));
  91   }
  92
  93   /**
  94    * Convenience method to add a boolean member. The specified value is converted to a
  95    * JsonPrimitive of Boolean.
  96    *
  97    * @param property name of the member.
  98    * @param value the number value associated with the member.
  99    */
 100   public void addProperty(String property, Boolean value) {
 101     add(property, createJsonElement(value));
 102   }
 103
 104   /**
 105    * Convenience method to add a char member. The specified value is converted to a
 106    * JsonPrimitive of Character.
 107    *
 108    * @param property name of the member.
 109    * @param value the number value associated with the member.
 110    */
 111   public void addProperty(String property, Character value) {
 112     add(property, createJsonElement(value));
 113   }
 114
 115   /**
 116    * Creates the proper {@link JsonElement} object from the given {@code value} object.
 117    *
 118    * @param value the object to generate the {@link JsonElement} for
 119    * @return a {@link JsonPrimitive} if the {@code value} is not null, otherwise a {@link JsonNull}
 120    */
 121   private JsonElement createJsonElement(Object value) {
 122     return value == null ? JsonNull.INSTANCE : new JsonPrimitive(value);
 123   }
 124
 125   /**
 126    * Returns a set of members of this object. The set is ordered, and the order is in which the
 127    * elements were added.
 128    *
 129    * @return a set of members of this object.
 130    */
 131   public Set<Map.Entry<String, JsonElement>> entrySet() {
 132     return members.entrySet();
 133   }
 134
 135   /**
 136    * Convenience method to check if a member with the specified name is present in this object.
 137    *
 138    * @param memberName name of the member that is being checked for presence.
 139    * @return true if there is a member with the specified name, false otherwise.
 140    */
 141   public boolean has(String memberName) {
 142     return members.containsKey(memberName);
 143   }
 144
 145   /**
 146    * Returns the member with the specified name.
 147    *
 148    * @param memberName name of the member that is being requested.
 149    * @return the member matching the name. Null if no such member exists.
 150    */
 151   public JsonElement get(String memberName) {
 152     return members.get(memberName);
 153   }
 154
 155   /**
 156    * Convenience method to get the specified member as a JsonPrimitive element.
 157    *
 158    * @param memberName name of the member being requested.
 159    * @return the JsonPrimitive corresponding to the specified member.
 160    */
 161   public JsonPrimitive getAsJsonPrimitive(String memberName) {
 162     return (JsonPrimitive) members.get(memberName);
 163   }
 164
 165   /**
 166    * Convenience method to get the specified member as a JsonArray.
 167    *
 168    * @param memberName name of the member being requested.
 169    * @return the JsonArray corresponding to the specified member.
 170    */
 171   public JsonArray getAsJsonArray(String memberName) {
 172     return (JsonArray) members.get(memberName);
 173   }
 174
 175   /**
 176    * Convenience method to get the specified member as a JsonObject.
 177    *
 178    * @param memberName name of the member being requested.
 179    * @return the JsonObject corresponding to the specified member.
 180    */
 181   public JsonObject getAsJsonObject(String memberName) {
 182     return (JsonObject) members.get(memberName);
 183   }
 184
 185   @Override
 186   public boolean equals(Object o) {
 187     return (o == this) || (o instanceof JsonObject
 188         && ((JsonObject) o).members.equals(members));
 189   }
 190
 191   @Override
 192   public int hashCode() {
 193     return members.hashCode();
 194   }
 195 }