javax.json.JsonArray Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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 javax.json;
import java.util.List;
import java.util.function.Function;
import java.util.stream.Collectors;
import java.util.stream.Stream;
/**
* A JsonArray e.g.
*
* [1,5,8]
*
* or
*
* [
* {"name":"karl", "age": 38},
* {"name":"sue", "age": 42},
* ]
*
*
*
*/
public interface JsonArray extends JsonStructure, List {
/**
* @return the JsonObject at the given position
* @throws IndexOutOfBoundsException if the index is out of range
* @throws ClassCastException if the value at the specified position is not
* assignable to the JsonObject
*/
JsonObject getJsonObject(int index);
/**
* @return the JsonArray at the given position
* @throws IndexOutOfBoundsException if the index is out of range
* @throws ClassCastException if the value at the specified position is not
* assignable to the JsonArray
*/
JsonArray getJsonArray(int index);
/**
* @return the JsonNumber at the given position
* @throws IndexOutOfBoundsException if the index is out of range
* @throws ClassCastException if the value at the specified position is not
* assignable to the JsonNumber
*/
JsonNumber getJsonNumber(int index);
/**
* @return the JsonString at the given position
* @throws IndexOutOfBoundsException if the index is out of range
* @throws ClassCastException if the value at the specified position is not
* assignable to the JsonString
*/
JsonString getJsonString(int index);
/**
* @return the respective JsonValue at the given position
* @throws IndexOutOfBoundsException if the index is out of range
* @throws ClassCastException if the value at the specified position is not
* assignable to the given slazz
*/
List getValuesAs(Class clazz);
/**
* Returns a list for the array. The value and the type of the elements
* in the list is specified by the {@code func} argument.
* This method can be used to obtain a list of the unwrapped types, such as
*
{@code
* List strings = ary1.getValuesAs(JsonString::getString);
* List ints = ary2.getValuesAs(JsonNumber::intValue);
* }
* It can also be used to obtain a list of simple projections, such as
* {@code
* Lsit stringsizes = arr.getValueAs((JsonString v) -> v.getString().length();
* }
* @param The element type (must be a subtype of JsonValue) of this JsonArray.
* @param The element type of the returned List
* @param func The function that maps the elements of this JsonArray to the target elements.
* @return A List of the specified values and type.
* @throws ClassCastException if the {@code JsonArray} contains a value of wrong type
*/
default List getValuesAs(Function func) {
Stream stream = (Stream) stream();
return stream.map(func).collect(Collectors.toList());
}
/**
* @return the native String at the given position
* @throws IndexOutOfBoundsException if the index is out of range
* @throws ClassCastException if the value at the specified position is not
* assignable to a String
*/
String getString(int index);
/**
* @return the native String at the given position or the defaultValue if null
* @throws IndexOutOfBoundsException if the index is out of range
* @throws ClassCastException if the value at the specified position is not
* assignable to a String
*/
String getString(int index, String defaultValue);
/**
* @return the native int value at the given position
* @throws IndexOutOfBoundsException if the index is out of range
* @throws ClassCastException if the value at the specified position is not
* assignable to an int
* @throws NullPointerException if an object with the given name doesn't exist
*/
int getInt(int index);
/**
* @return the native int value at the given position or the defaultValue if null
* @throws IndexOutOfBoundsException if the index is out of range
* @throws ClassCastException if the value at the specified position is not
* assignable to an int
*/
int getInt(int index, int defaultValue);
/**
* @return the native boolean value at the given position
* @throws IndexOutOfBoundsException if the index is out of range
* @throws ClassCastException if the value at the specified position is not
* assignable to a boolean
* @throws NullPointerException if an object with the given name doesn't exist
*/
boolean getBoolean(int index);
/**
* @return the native boolean value at the given position or the defaultValue if null
* @throws IndexOutOfBoundsException if the index is out of range
* @throws ClassCastException if the value at the specified position is not
* assignable to a boolean
*/
boolean getBoolean(int index, boolean defaultValue);
/**
* @return whether the value at the given position is {@link JsonValue#NULL}.
* @throws IndexOutOfBoundsException if the index is out of range
*/
boolean isNull(int index);
}