001    /*
002     * Copyright 2015-2016 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2015-2016 UnboundID Corp.
007     *
008     * This program is free software; you can redistribute it and/or modify
009     * it under the terms of the GNU General Public License (GPLv2 only)
010     * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011     * as published by the Free Software Foundation.
012     *
013     * This program is distributed in the hope that it will be useful,
014     * but WITHOUT ANY WARRANTY; without even the implied warranty of
015     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016     * GNU General Public License for more details.
017     *
018     * You should have received a copy of the GNU General Public License
019     * along with this program; if not, see <http://www.gnu.org/licenses>.
020     */
021    package com.unboundid.util.json;
022    
023    
024    
025    import java.io.Serializable;
026    
027    import com.unboundid.util.NotMutable;
028    import com.unboundid.util.ThreadSafety;
029    import com.unboundid.util.ThreadSafetyLevel;
030    import com.unboundid.util.Validator;
031    
032    
033    
034    /**
035     * This class provides a simple data structure that represents a field in a
036     * JSON object, containing a name and a value.  This is primarily intended as a
037     * convenience when programmatically constructing JSON objects.
038     */
039    @NotMutable()
040    @ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
041    public final class JSONField
042           implements Serializable
043    {
044      /**
045       * The serial version UID for this serializable class.
046       */
047      private static final long serialVersionUID = -1397826405959590851L;
048    
049    
050    
051      // The value for this field.
052      private final JSONValue value;
053    
054      // The name for this field.
055      private final String name;
056    
057    
058    
059      /**
060       * Creates a new JSON field with the specified name and value.
061       *
062       * @param name  The name for this field.  It must not be {@code null}.
063       * @param value The value for this field.  It must not be {@code null}
064       *              (although it may be a {@link JSONNull} instance).
065       */
066      public JSONField(final String name, final JSONValue value)
067      {
068        Validator.ensureNotNull(name);
069        Validator.ensureNotNull(value);
070    
071        this.name = name;
072        this.value = value;
073      }
074    
075    
076    
077      /**
078       * Creates a new JSON field with the specified name and a {@link JSONBoolean}
079       * value.
080       *
081       * @param name  The name for this field.  It must not be {@code null}.
082       * @param value The value for this field.  It must not be {@code null}.
083       */
084      public JSONField(final String name, final boolean value)
085      {
086        this(name, (value ? JSONBoolean.TRUE : JSONBoolean.FALSE));
087      }
088    
089    
090    
091      /**
092       * Creates a new JSON field with the specified name and a {@link JSONNumber}
093       * value.
094       *
095       * @param name  The name for this field.  It must not be {@code null}.
096       * @param value The value for this field.  It must not be {@code null}.
097       */
098      public JSONField(final String name, final long value)
099      {
100        this(name, new JSONNumber(value));
101      }
102    
103    
104    
105      /**
106       * Creates a new JSON field with the specified name and a {@link JSONNumber}
107       * value.
108       *
109       * @param name  The name for this field.  It must not be {@code null}.
110       * @param value The value for this field.  It must not be {@code null}.
111       */
112      public JSONField(final String name, final double value)
113      {
114        this(name, new JSONNumber(value));
115      }
116    
117    
118    
119      /**
120       * Creates a new JSON field with the specified name and a {@link JSONString}
121       * value.
122       *
123       * @param name  The name for this field.  It must not be {@code null}.
124       * @param value The value for this field.  It must not be {@code null}.
125       */
126      public JSONField(final String name, final String value)
127      {
128        this(name, new JSONString(value));
129      }
130    
131    
132    
133      /**
134       * Retrieves the name for this field.
135       *
136       * @return  The name for this field.
137       */
138      public String getName()
139      {
140        return name;
141      }
142    
143    
144    
145      /**
146       * Retrieves the value for this field.
147       *
148       * @return  The value for this field.
149       */
150      public JSONValue getValue()
151      {
152        return value;
153      }
154    
155    
156    
157      /**
158       * Retrieves a hash code for this JSON field.
159       *
160       * @return  A hash code for this JSON field.
161       */
162      @Override()
163      public int hashCode()
164      {
165        return name.hashCode() + value.hashCode();
166      }
167    
168    
169    
170      /**
171       * Indicates whether the provided object is considered equal to this JSON
172       * field.
173       *
174       * @param  o  The object for which to make the determination.
175       *
176       * @return  {@code true} if the provided object is a JSON field with the same
177       *          name and an equivalent value, or {@code false} if not.
178       */
179      @Override()
180      public boolean equals(final Object o)
181      {
182        if (o == this)
183        {
184          return true;
185        }
186    
187        if (o instanceof JSONField)
188        {
189          final JSONField f = (JSONField) o;
190          return (name.equals(f.name) && value.equals(f.value));
191        }
192    
193        return false;
194      }
195    
196    
197    
198      /**
199       * Retrieves a string representation of this field.
200       *
201       * @return  A string representation of this field.
202       */
203      @Override()
204      public String toString()
205      {
206        final StringBuilder buffer = new StringBuilder();
207        toString(buffer);
208        return buffer.toString();
209      }
210    
211    
212    
213      /**
214       * Appends a string representation of this field to the provided buffer.
215       *
216       * @param  buffer  The buffer to which the information should be appended.
217       */
218      public void toString(final StringBuilder buffer)
219      {
220        JSONString.encodeString(name, buffer);
221        buffer.append(':');
222        value.toString(buffer);
223      }
224    }