// Licensed to the Software Freedom Conservancy (SFC) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The SFC 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 org.openqa.selenium.json;

import java.io.IOException;
import java.io.Reader;
import java.io.StringReader;
import java.io.StringWriter;
import java.io.UncheckedIOException;
import java.io.Writer;
import java.lang.reflect.Type;
import java.util.List;
import java.util.Map;
import org.jspecify.annotations.Nullable;
import org.openqa.selenium.internal.Require;

/**
 * The <b>Json</b> class is the entrypoint for the JSON processing features of the Selenium API.
 * These features include:
 *
 * <ul>
 *   <li>Built-in JSON deserialization to primitives and collections from the standard types shown
 *       below.
 *   <li>Facilities to deserialize JSON to custom data types:
 *       <ul>
 *         <li>Classes that declare a {@code fromJson(T)} static method, where <b>T</b> is any of
 *             the standard types shown below.
 *         <li>Classes that declare a {@code fromJson(JsonInput)} static method.<br>
 *             <b>NOTE</b>: Objects deserialized via a {@code fromJson} static method can be
 *             immutable.
 *         <li>Classes that declare a constructor whose parameter names are available at runtime.
 *             <br>
 *             <b>NOTE</b>: Constructor parameter names are only available if they are present in
 *             the class file, such as when the class is compiled with {@code javac -parameters}.
 *             Constructor parameter names must match the corresponding JSON field names. Parameters
 *             of type {@link java.util.Optional Optional} are not required.
 *         <li>Classes that declare setter methods adhering to the <a
 *             href="https://docs.oracle.com/javase/tutorial/javabeans/writing/index.html">JavaBean</a>
 *             specification.<br>
 *             <b>NOTE</b>: Deserialized {@code JavaBean} objects are mutable, which may be
 *             undesirable.
 *       </ul>
 *   <li>Built-in JSON serialization from primitives and collections from the standard types shown
 *       below.
 *   <li>Facilities to serialize custom data types to JSON:
 *       <ul>
 *         <li>Classes that declare a {@code toJson()} method returning a primitive or collection
 *             from the standard types shown below.
 *         <li>Classes that declare getter methods adhering to the {@code JavaBean} specification.
 *       </ul>
 * </ul>
 *
 * The standard types supported by built-in processing:
 *
 * <ul>
 *   <li><b>Numeric Types</b>:<br>
 *       {@link java.lang.Byte Byte}, {@link java.lang.Double Double}, {@link java.lang.Float
 *       Float}, {@link java.lang.Integer Integer}, {@link java.lang.Long Long}, {@link
 *       java.lang.Short Short}
 *   <li><b>Collection Types</b>:<br>
 *       {@link java.util.Collection Collection}, {@link java.util.List List}, {@link java.util.Set
 *       Set}
 *   <li><b>Standard Java Types</b>:<br>
 *       {@link java.util.Map Map}, {@link java.lang.Boolean Boolean}, {@link java.lang.String
 *       String}, {@link java.lang.Enum Enum}, {@link java.net.URI URI}, {@link java.net.URL URL},
 *       {@link java.util.UUID UUID}, {@link java.time.Instant Instant}, {@link java.util.Optional
 *       Optional}, {@link java.lang.Object Object}
 * </ul>
 *
 * You can serialize objects for which no explicit coercer has been specified, and the <b>Json</b>
 * API will use a generic process to provide best-effort JSON output. For the most predictable
 * results, though, it's best to provide a {@code toJson()} method for the <b>Json</b> API to use
 * for serialization. This is especially beneficial for objects that contain transient properties
 * that should be omitted from the JSON output.
 *
 * <p>You can deserialize objects for which no explicit handling has been defined. Note that the
 * data type of the result will be {@code Map<String,?>}, which means that you'll need to perform
 * type checking and casting every time you extract an entry value from the result. For this reason,
 * it's best to declare either a type-specific {@code fromJson()} method or a constructor with
 * runtime-visible parameter names in every type you need to deserialize.
 *
 * @see JsonTypeCoercer
 * @see JsonInput
 * @see JsonOutput
 */
public class Json {
  /**
   * The value of {@code Content-Type} headers for HTTP requests and responses with JSON entities
   */
  public static final String JSON_UTF_8 = "application/json; charset=utf-8";

  /** Specifier for {@code List<Map<String, Object>} input/output type */
  public static final Type LIST_OF_MAPS_TYPE =
      new TypeToken<List<Map<String, Object>>>() {}.getType();

  /** Specifier for {@code Map<String, Object>} input/output type */
  public static final Type MAP_TYPE = new TypeToken<Map<String, Object>>() {}.getType();

  /** Specifier for {@code Object} input/output type */
  public static final Type OBJECT_TYPE = new TypeToken<Object>() {}.getType();

  private final JsonTypeCoercer fromJson = new JsonTypeCoercer();

  /**
   * Serialize the specified object to JSON string representation.<br>
   * <b>NOTE</b>: This method limits traversal of nested objects to the default {@link
   * JsonOutput#MAX_DEPTH maximum depth}.
   *
   * @param toConvert the object to be serialized
   * @return JSON string representing the specified object
   */
  public String toJson(@Nullable Object toConvert) {
    return toJson(toConvert, JsonOutput.MAX_DEPTH);
  }

  /**
   * Serialize the specified object to JSON string representation.
   *
   * @param toConvert the object to be serialized
   * @param maxDepth maximum depth of nested object traversal
   * @return JSON string representing the specified object
   * @throws JsonException if an I/O exception is encountered
   */
  public String toJson(@Nullable Object toConvert, int maxDepth) {
    try (Writer writer = new StringWriter();
        JsonOutput jsonOutput = newOutput(writer)) {
      jsonOutput.write(toConvert, maxDepth);
      return writer.toString();
    } catch (IOException e) {
      throw new JsonException("Cannot convert " + toConvert + " to json", e);
    }
  }

  /**
   * Deserialize the specified JSON string into an object of the specified type.<br>
   * <b>NOTE</b>: This method uses the {@link PropertySetting#BY_NAME BY_NAME} strategy to assign
   * values to properties in the deserialized object.
   *
   * @param source serialized source as JSON string
   * @param typeOfT data type for deserialization (class or {@link TypeToken})
   * @return object of the specified type deserialized from [source]
   * @param <T> result type (as specified by [typeOfT])
   * @throws JsonException if an I/O exception is encountered
   */
  public <T> T toType(String source, Type typeOfT) {
    return toType(source, typeOfT, PropertySetting.BY_NAME);
  }

  /**
   * Deserialize the specified JSON string into an object of the specified type.
   *
   * @param source serialized source as JSON string
   * @param typeOfT data type for deserialization (class or {@link TypeToken})
   * @param setter strategy used to assign values during deserialization
   * @return object of the specified type deserialized from [source]
   * @param <T> result type (as specified by [typeOfT])
   * @throws JsonException if an I/O exception is encountered
   */
  public <T> T toType(String source, Type typeOfT, PropertySetting setter) {
    try (StringReader reader = new StringReader(source)) {
      return toType(reader, typeOfT, setter);
    } catch (JsonException e) {
      throw new JsonException("Unable to parse: " + source, e);
    }
  }

  /**
   * Deserialize the JSON string supplied by the specified {@code Reader} into an object of the
   * specified type.<br>
   * <b>NOTE</b>: This method uses the {@link PropertySetting#BY_NAME BY_NAME} strategy to assign
   * values to properties in the deserialized object.
   *
   * @param source {@link Reader} that supplies a serialized JSON string
   * @param typeOfT data type for deserialization (class or {@link TypeToken})
   * @return object of the specified type deserialized from [source]
   * @param <T> result type (as specified by [typeOfT])
   * @throws JsonException if an I/O exception is encountered
   */
  public <T> T toType(Reader source, Type typeOfT) {
    return toType(source, typeOfT, PropertySetting.BY_NAME);
  }

  /**
   * Deserialize the JSON string supplied by the specified {@code Reader} into an object of the
   * specified type.
   *
   * @param source {@link Reader} that supplies a serialized JSON string
   * @param typeOfT data type for deserialization (class or {@link TypeToken})
   * @param setter strategy used to assign values during deserialization
   * @return object of the specified type deserialized from [source]
   * @param <T> result type (as specified by [typeOfT])
   * @throws JsonException if an I/O exception is encountered
   */
  public <T> T toType(Reader source, Type typeOfT, PropertySetting setter) {
    Require.nonNull("Mechanism for setting properties", setter);

    try (JsonInput json = newInput(source)) {
      return fromJson.coerce(json, typeOfT, setter);
    }
  }

  /**
   * Create a new {@code JsonInput} object to traverse the JSON string supplied the specified {@code
   * Reader}.<br>
   * <b>NOTE</b>: The {@code JsonInput} object returned by this method uses the {@link
   * PropertySetting#BY_NAME BY_NAME} strategy to assign values to properties objects it
   * deserializes.
   *
   * @param from {@link Reader} that supplies a serialized JSON string
   * @return {@link JsonInput} object to traverse the JSON string supplied by [from]
   * @throws UncheckedIOException if an I/O exception occurs
   */
  public JsonInput newInput(Reader from) throws UncheckedIOException {
    return new JsonInput(from, fromJson, PropertySetting.BY_NAME);
  }

  /**
   * Create a new {@code JsonOutput} object to produce a serialized JSON string in the specified
   * {@code Appendable}.
   *
   * @param to {@link Appendable} that consumes a serialized JSON string
   * @return {@link JsonOutput} object to product a JSON string in [to]
   * @throws UncheckedIOException if an I/O exception occurs
   */
  public JsonOutput newOutput(Appendable to) throws UncheckedIOException {
    return new JsonOutput(to);
  }
}