001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.revetsec.json; 018 019import com.revetsec.internal.json.JsonWriter; 020import org.jspecify.annotations.NonNull; 021import org.jspecify.annotations.Nullable; 022 023import javax.annotation.concurrent.Immutable; 024import java.util.List; 025 026import static java.util.Objects.requireNonNull; 027 028/** 029 * A JSON array: an ordered, unmodifiable list of values. Two arrays are equal when they hold equal elements in the 030 * same order. 031 * <p> 032 * There is no array builder: assemble a {@link List} and pass it to {@link #fromElements(List)}. 033 * 034 * @author <a href="https://www.revetkn.com">Mark Allen</a> 035 * @since 1.0.0 036 */ 037@Immutable 038public final class JsonArray implements JsonValue { 039 @NonNull 040 private static final JsonArray EMPTY = new JsonArray(List.of(), 1, List.of().hashCode()); 041 042 @NonNull 043 private final List<@NonNull JsonValue> elements; 044 private final int depth; 045 private final int hashCode; 046 047 /** 048 * Returns the empty JSON array. 049 * 050 * @return the shared empty array 051 * @since 1.0.0 052 */ 053 @NonNull 054 public static JsonArray emptyInstance() { 055 return EMPTY; 056 } 057 058 /** 059 * Returns a JSON array holding a snapshot of {@code elements}, in order. 060 * 061 * @param elements the elements; later changes to the list do not affect the array 062 * @return the JSON array 063 * @throws NullPointerException if {@code elements} or any element is {@code null} 064 * @throws IllegalArgumentException if the array would nest more than 64 deep 065 * @since 1.0.0 066 */ 067 @NonNull 068 public static JsonArray fromElements(@NonNull List<? extends @NonNull JsonValue> elements) { 069 requireNonNull(elements); 070 List<@NonNull JsonValue> snapshot = List.copyOf(elements); 071 072 if (snapshot.isEmpty()) 073 return EMPTY; 074 075 int deepestChild = 0; 076 077 for (JsonValue element : snapshot) 078 deepestChild = Math.max(deepestChild, JsonInvariants.depthOf(element)); 079 080 return new JsonArray(snapshot, JsonInvariants.requireContainerDepth(deepestChild), snapshot.hashCode()); 081 } 082 083 private JsonArray(@NonNull List<@NonNull JsonValue> elements, int depth, int hashCode) { 084 // Already an unmodifiable copy, which List.copyOf returns as it is; copying here documents that the field is 085 // immutable. 086 this.elements = List.copyOf(elements); 087 this.depth = depth; 088 this.hashCode = hashCode; 089 } 090 091 /** 092 * Returns this array's elements, in order. 093 * 094 * @return an unmodifiable list 095 * @since 1.0.0 096 */ 097 @NonNull 098 public List<@NonNull JsonValue> getElements() { 099 return this.elements; 100 } 101 102 /** 103 * The G7-6 depth: 1 if empty, otherwise 1 more than the deepest element. 104 */ 105 int getDepth() { 106 return this.depth; 107 } 108 109 @Override 110 @NonNull 111 public String toJson() { 112 return JsonWriter.toJson(this); 113 } 114 115 @Override 116 public boolean equals(@Nullable Object other) { 117 return this == other || (other instanceof JsonArray array && this.hashCode == array.hashCode 118 && this.elements.equals(array.elements)); 119 } 120 121 @Override 122 public int hashCode() { 123 return this.hashCode; 124 } 125 126 @Override 127 @NonNull 128 public String toString() { 129 return "JsonArray{elements=<redacted>}"; 130 } 131}