com.helger.json.IJsonObject Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of ph-json Show documentation
Show all versions of ph-json Show documentation
JSON reader and writer libary
The newest version!
/**
* Copyright (C) 2014-2021 Philip Helger (www.helger.com)
* philip[at]helger[dot]com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.helger.json;
import java.util.Map;
import java.util.function.BiConsumer;
import java.util.function.Function;
import java.util.function.Predicate;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import com.helger.commons.annotation.ReturnsMutableCopy;
import com.helger.commons.collection.impl.ICommonsIterable;
import com.helger.commons.collection.impl.ICommonsList;
import com.helger.commons.collection.impl.ICommonsMap;
import com.helger.commons.collection.impl.ICommonsOrderedMap;
import com.helger.commons.collection.impl.ICommonsOrderedSet;
import com.helger.commons.state.EChange;
import com.helger.commons.traits.IGetterByKeyTrait;
import com.helger.json.convert.JsonConverter;
/**
* Base interface for a JSON object that is a map from String to IJson
*
* @author Philip Helger
*/
public interface IJsonObject extends IJsonCollection, ICommonsIterable >, IGetterByKeyTrait
{
/**
* Add a new child JSON with the given name to this object.
*
* @param sName
* The name of the field. May not be null.
* @param aValue
* The JSON object to be added. May not be null.
* @return this for chaining
* @deprecated Since 9.4.3; Use {@link #addJson(String, IJson)} instead. It
* was renamed because all other "add" methods allow for
* "nullable" parameters whereas this method requires a
* non-null value. By renaming the method the
* non-nullness became more explicit.
*/
@Nonnull
@Deprecated
IJsonObject add (@Nonnull String sName, @Nonnull IJson aValue);
/**
* Add a new child JSON with the given name to this object.
*
* @param sName
* The name of the field. May not be null.
* @param aValue
* The JSON object to be added. May not be null.
* @return this for chaining
*/
@Nonnull
IJsonObject addJson (@Nonnull String sName, @Nonnull IJson aValue);
@Nonnull
default IJsonObject addIf (@Nonnull final String sName, @Nonnull final IJson aValue, @Nonnull final Predicate aFilter)
{
if (aFilter.test (aValue))
addJson (sName, aValue);
return this;
}
/**
* Add at the specified value using the JSON converter
*
* @param sName
* The name of the item. May not be null.
* @param aValue
* The value to be added. May be null.
* @return this
*/
@Nonnull
default IJsonObject add (@Nonnull final String sName, @Nullable final Object aValue)
{
final IJson aJson = JsonConverter.convertToJson (aValue);
return addJson (sName, aJson);
}
@Nonnull
default IJsonObject addIfNotNull (@Nonnull final String sName, @Nullable final Object aValue)
{
if (aValue != null)
add (sName, aValue);
return this;
}
@Nonnull
default IJsonObject addIf (@Nonnull final String sName, @Nullable final Object aValue, @Nonnull final Predicate aFilter)
{
if (aFilter.test (aValue))
add (sName, aValue);
return this;
}
@Nonnull
default IJsonObject add (@Nonnull final Map.Entry aEntry)
{
return add (aEntry.getKey (), aEntry.getValue ());
}
@Nonnull
default IJsonObject add (@Nonnull final String sName, final boolean bValue)
{
return addJson (sName, JsonValue.create (bValue));
}
@Nonnull
default IJsonObject add (@Nonnull final String sName, final char cValue)
{
return addJson (sName, JsonValue.create (cValue));
}
@Nonnull
default IJsonObject add (@Nonnull final String sName, final double dValue)
{
return addJson (sName, JsonValue.create (dValue));
}
@Nonnull
default IJsonObject add (@Nonnull final String sName, final int nValue)
{
return addJson (sName, JsonValue.create (nValue));
}
@Nonnull
default IJsonObject add (@Nonnull final String sName, final long nValue)
{
return addJson (sName, JsonValue.create (nValue));
}
@Nonnull
default IJsonObject addAll (@Nullable final Map aMap)
{
if (aMap != null)
for (final Map.Entry aEntry : aMap.entrySet ())
add (aEntry);
return this;
}
/**
* Add all entries of the passed object to this object. So this is a
* "flattening add all".
*
* @param aObject
* The object to add from. May be null.
* @return this for chaining
*/
@Nonnull
default IJsonObject addAll (@Nullable final IJsonObject aObject)
{
if (aObject != null)
for (final Map.Entry aEntry : aObject)
add (aEntry);
return this;
}
@Nonnull
default IJsonObject addAllMapped (@Nullable final Map aMap,
@Nonnull final Function aValueMapper)
{
if (aMap != null)
for (final Map.Entry aEntry : aMap.entrySet ())
addJson (aEntry.getKey (), aValueMapper.apply (aEntry.getValue ()));
return this;
}
@Nonnull
default IJsonObject addAllMapped (@Nullable final Map aMap,
@Nonnull final Function aKeyMapper,
@Nonnull final Function aValueMapper)
{
if (aMap != null)
for (final Map.Entry aEntry : aMap.entrySet ())
addJson (aKeyMapper.apply (aEntry.getKey ()), aValueMapper.apply (aEntry.getValue ()));
return this;
}
@Nullable
IJson removeKeyAndReturnValue (@Nullable String sName);
@Nonnull
EChange removeKey (@Nullable String sName);
boolean containsKey (@Nullable String sName);
@Nonnull
@ReturnsMutableCopy
ICommonsOrderedSet keySet ();
@Nonnull
@ReturnsMutableCopy
ICommonsList values ();
/**
* Get the element with the specified key.
*
* @param sName
* The name of the value to retrieve. May be null.
* @return null if no value for the name exists.
*/
@Nullable
IJson get (@Nullable String sName);
/**
* Get the element with the specified key. This is the {@link IJsonValue}
* specific version of {@link #get(String)}.
*
* @param sName
* The name of the value to retrieve. May be null.
* @return null if no value for the name exists or if the value
* is not a {@link IJsonValue}.
*/
@Nullable
default Object getValue (@Nullable final String sName)
{
final IJson aJson = get (sName);
if (aJson != null)
{
final IJsonValue aValue = aJson.getAsValue ();
if (aValue != null)
return aValue.getValue ();
}
return null;
}
/**
* Get the element with the specified key. This is the {@link IJsonValue}
* specific version of {@link #get(String)}.
*
* @param sName
* The name of the value to retrieve. May be null.
* @return null if no value for the name exists or if the value
* is not a {@link IJsonValue}.
*/
@Nullable
default IJsonValue getAsValue (@Nullable final String sName)
{
final IJson aJson = get (sName);
return aJson != null ? aJson.getAsValue () : null;
}
/**
* Get the element with the specified key. This is the {@link IJsonArray}
* specific version of {@link #get(String)}.
*
* @param sName
* The name of the value to retrieve. May be null.
* @return null if no value for the name exists or if the value
* is not a {@link IJsonArray}.
*/
@Nullable
default IJsonArray getAsArray (@Nullable final String sName)
{
final IJson aJson = get (sName);
return aJson != null ? aJson.getAsArray () : null;
}
/**
* Get the element with the specified key. This is the {@link IJsonObject}
* specific version of {@link #get(String)}.
*
* @param sName
* The name of the value to retrieve. May be null.
* @return null if no value for the name exists or if the value
* is not a {@link IJsonObject}.
*/
@Nullable
default IJsonObject getAsObject (@Nullable final String sName)
{
final IJson aJson = get (sName);
return aJson != null ? aJson.getAsObject () : null;
}
/**
* @return A copy of all contained items. Never null but maybe
* empty.
*/
@Nonnull
@ReturnsMutableCopy
ICommonsMap getAll ();
/**
* Invoke the passed consumer on all entries of this object.
*
* @param aConsumer
* Consumer with the first param being the key and second param being
* the value.
*/
void forEach (@Nonnull BiConsumer aConsumer);
/**
* Check if the passed value is directly contained in the object or not.
*
* @param aValue
* The value to be checked for containment. May be null.
* @return true if the value is contained, false if
* not.
*/
boolean containsValue (@Nullable IJson aValue);
/**
* Check if the passed value is directly contained in the object or not.
*
* @param aValue
* The value to be checked for containment. May be null.
* @return true if the value is contained, false if
* not.
*/
default boolean containsValue (@Nullable final Object aValue)
{
return containsValue (JsonValue.create (aValue));
}
/**
* Check if the passed value is directly contained in the object or not.
*
* @param bValue
* The value to be checked for containment.
* @return true if the value is contained, false if
* not.
*/
default boolean containsValue (final boolean bValue)
{
return containsValue (JsonValue.create (bValue));
}
/**
* Check if the passed value is directly contained in the object or not.
*
* @param cValue
* The value to be checked for containment.
* @return true if the value is contained, false if
* not.
*/
default boolean containsValue (final char cValue)
{
return containsValue (JsonValue.create (cValue));
}
/**
* Check if the passed value is directly contained in the object or not.
*
* @param dValue
* The value to be checked for containment.
* @return true if the value is contained, false if
* not.
*/
default boolean containsValue (final double dValue)
{
return containsValue (JsonValue.create (dValue));
}
/**
* Check if the passed value is directly contained in the object or not.
*
* @param nValue
* The value to be checked for containment.
* @return true if the value is contained, false if
* not.
*/
default boolean containsValue (final int nValue)
{
return containsValue (JsonValue.create (nValue));
}
/**
* Check if the passed value is directly contained in the object or not.
*
* @param nValue
* The value to be checked for containment.
* @return true if the value is contained, false if
* not.
*/
default boolean containsValue (final long nValue)
{
return containsValue (JsonValue.create (nValue));
}
/**
* Compute a JSON value if it is not present.
*
* @param sName
* The name of the property. May not be null.
* @param aValueProvider
* The value provider of the property. May not be null. Is
* only invoked, if the property is not present.
* @return Either the existing property value, or the newly calculated
* property value.
* @since 8.6.4
*/
@Nullable
default IJson computeIfAbsent (@Nonnull final String sName, @Nonnull final Function aValueProvider)
{
IJson ret = get (sName);
if (ret == null)
{
ret = aValueProvider.apply (sName);
if (ret != null)
addJson (sName, ret);
}
return ret;
}
/**
* @return A map of all cloned values contained in this object in the same
* order. Never null.
*/
@Nonnull
@ReturnsMutableCopy
ICommonsOrderedMap getClonedValues ();
@Nonnull
IJsonObject getClone ();
}