/*
 * 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 org.apache.juneau.marshall.objecttools;

import static java.net.HttpURLConnection.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.StringUtils.*;

import java.lang.reflect.*;
import java.util.*;

import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.collections.*;
import org.apache.juneau.marshall.parser.*;

/**
 * Traversal engine for performing standard REST operations (GET, PUT, POST, DELETE) against nodes in a POJO model.
 *
 * <p>
 * <b>Internal API:</b> This class is the relocated traversal engine behind the {@code Marshalled*} path-addressing
 * methods and the Swagger/OpenApi {@code $ref} resolver. It is public only for cross-module access and is <b>not</b> a
 * supported public API &mdash; do not use it directly.
 *
 * <p>
 * Nodes in the POJO model are addressed using URLs.
 *
 * <p>
 * A POJO model is defined as a tree model where nodes consist of consisting of the following:
 * <ul class='spaced-list'>
 *    <li>
 *       {@link Map Maps} and Java beans representing JSON objects.
 *    <li>
 *       {@link Collection Collections} and arrays representing JSON arrays.
 *    <li>
 *       Java beans.
 * </ul>
 *
 * <p>
 * Leaves of the tree can be any type of object.
 *
 * <p>
 * Use {@link #get(String) get()} to retrieve an element from a JSON tree.
 * <br>Use {@link #put(String,Object) put()} to create (or overwrite) an element in a JSON tree.
 * <br>Use {@link #post(String,Object) post()} to add an element to a list in a JSON tree.
 * <br>Use {@link #delete(String) delete()} to remove an element from a JSON tree.
 *
 * <p>
 * Leading slashes in URLs are ignored.
 * So <js>"/xxx/yyy/zzz"</js> and <js>"xxx/yyy/zzz"</js> are considered identical.
 *
 * <h5 class='section'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Construct an unstructured POJO model</jc>
 *    JsonMap <jv>map</jv> = JsonMap.<jsm>ofText</jsm>(<js>""</js>
 *       + <js>"{"</js>
 *       + <js>"  name:'John Smith', "</js>
 *       + <js>"  address:{ "</js>
 *       + <js>"     streetAddress:'21 2nd Street', "</js>
 *       + <js>"     city:'New York', "</js>
 *       + <js>"     state:'NY', "</js>
 *       + <js>"     postalCode:10021 "</js>
 *       + <js>"  }, "</js>
 *       + <js>"  phoneNumbers:[ "</js>
 *       + <js>"     '212 555-1111', "</js>
 *       + <js>"     '212 555-2222' "</js>
 *       + <js>"  ], "</js>
 *       + <js>"  additionalInfo:null, "</js>
 *       + <js>"  remote:false, "</js>
 *       + <js>"  height:62.4, "</js>
 *       + <js>"  'fico score':' &gt; 640' "</js>
 *       + <js>"} "</js>
 *    );
 *
 *    <jc>// Wrap Map inside a PathTraversal object</jc>
 *    PathTraversal <jv>johnSmith</jv> = PathTraversal.<jsm>create</jsm>(<jv>map</jv>);
 *
 *    <jc>// Get a simple value at the top level</jc>
 *    <jc>// "John Smith"</jc>
 *    String <jv>name</jv> = <jv>johnSmith</jv>.getString(<js>"name"</js>);
 *
 *    <jc>// Change a simple value at the top level</jc>
 *    <jv>johnSmith</jv>.put(<js>"name"</js>, <js>"The late John Smith"</js>);
 *
 *    <jc>// Get a simple value at a deep level</jc>
 *    <jc>// "21 2nd Street"</jc>
 *    String <jv>streetAddress</jv> = <jv>johnSmith</jv>.getString(<js>"address/streetAddress"</js>);
 *
 *    <jc>// Set a simple value at a deep level</jc>
 *    <jv>johnSmith</jv>.put(<js>"address/streetAddress"</js>, <js>"101 Cemetery Way"</js>);
 *
 *    <jc>// Get entries in a list</jc>
 *    <jc>// "212 555-1111"</jc>
 *    String <jv>firstPhoneNumber</jv> = <jv>johnSmith</jv>.getString(<js>"phoneNumbers/0"</js>);
 *
 *    <jc>// Add entries to a list</jc>
 *    <jv>johnSmith</jv>.post(<js>"phoneNumbers"</js>, <js>"212 555-3333"</js>);
 *
 *    <jc>// Delete entries from a model</jc>
 *    <jv>johnSmith</jv>.delete(<js>"fico score"</js>);
 *
 *    <jc>// Add entirely new structures to the tree</jc>
 *    JsonMap <jv>medicalInfo</jv> = JsonMap.<jsm>ofText</jsm>(<js>""</js>
 *       + <js>"{"</js>
 *       + <js>"  currentStatus: 'deceased',"</js>
 *       + <js>"  health: 'non-existent',"</js>
 *       + <js>"  creditWorthiness: 'not good'"</js>
 *       + <js>"}"</js>
 *    );
 *    <jv>johnSmith</jv>.put(<js>"additionalInfo/medicalInfo"</js>, <jv>medicalInfo</jv>);
 * </p>
 *
 * <p>
 * In the special case of collections/arrays of maps/beans, a special XPath-like selector notation can be used in lieu
 * of index numbers on GET requests to return a map/bean with a specified attribute value.
 * <br>The syntax is {@code @attr=val}, where attr is the attribute name on the child map, and val is the matching value.
 *
 * <h5 class='section'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Get map/bean with name attribute value of 'foo' from a list of items</jc>
 *    Map <jv>map</jv> = <jv>pathTraversal</jv>.getMap(<js>"/items/@name=foo"</js>);
 * </p>
 */
@SuppressWarnings({
   "java:S1452", // getList and getMap return List<?>/Map<?,?> because the element types are unknown until the caller converts them
   "java:S3776", // service() walks the URL path across maps, lists and arrays for every GET/PUT/POST/DELETE case
   "rawtypes", // Raw types necessary for generic type handling
   "unchecked" // Type erasure requires unchecked operations for generic collections
})
public class PathTraversal {
   // Internal traversal node — never serialized; 'parent' is an upward tree pointer used only to walk back up the model during PUT/POST/DELETE rewrites.
   class JsonNode {
      Object o;
      ClassMeta cm;
      JsonNode parent;
      String keyName;

      JsonNode(JsonNode parent, String keyName, Object o, ClassMeta cm) {
         this.o = o;
         this.keyName = keyName;
         this.parent = parent;
         if (cm == null || cm.isObject()) {
            if (o == null)
               cm = session.object();
            else
               cm = session.getClassMetaForObject(o);
         }
         this.cm = cm;
      }
   }

   /** The list of possible request types. */
   private static final int GET = 1;
   private static final int PUT = 2;
   private static final int POST = 3;
   private static final int DELETE = 4;

   /**
    * Static creator.
    * @param o The object being wrapped.
    * @return A new {@link PathTraversal} object.
    */
   public static PathTraversal create(Object o) {
      return new PathTraversal(o);
   }

   /**
    * Static creator.
    * @param o The object being wrapped.
    * @param parser The parser to use for parsing arguments and converting objects to the correct data type.
    * @return A new {@link PathTraversal} object.
    */
   public static PathTraversal create(Object o, ReaderParser parser) {
      return new PathTraversal(o, parser);
   }

   /** Handle nulls and strip off leading '/' char. */
   private static String normalizeUrl(String url) {

      // Interpret nulls and blanks the same (i.e. as addressing the root itself)
      if (url == null)
         url = "";

      // Strip off leading slash if present.
      if (ine(url) && url.charAt(0) == '/')
         url = url.substring(1);

      return url;
   }

   private static int parseInt(String key) {
      try {
         return Integer.parseInt(key);
      } catch (@SuppressWarnings("unused") NumberFormatException e) {
         throw new PathTraversalException(HTTP_BAD_REQUEST, "Cannot address an item in an array with a non-integer key '%s'", key);
      }
   }

   private static Object[] removeArrayEntry(Object o, int index) {
      var a = (Object[])o;
      // Shrink the array.
      var a2 = (Object[])Array.newInstance(a.getClass().getComponentType(), a.length - 1);
      System.arraycopy(a, 0, a2, 0, index);
      System.arraycopy(a, index + 1, a2, index, a.length - index - 1);
      return a2;
   }

   final MarshallingSession session;

   /** If true, the root cannot be overwritten */
   private boolean rootLocked;

   /** The root of the model. */
   private JsonNode root;

   /**
    * Create a new instance of a REST interface over the specified object.
    *
    * <p>
    * Uses {@link MarshallingContext#DEFAULT} for working with Java beans.
    *
    * @param o The object to be wrapped.
    */
   public PathTraversal(Object o) {
      this(o, null);
   }

   /**
    * Create a new instance of a REST interface over the specified object.
    *
    * <p>
    * The parser is used as the bean context.
    *
    * @param o The object to be wrapped.
    * @param parser The parser to use for parsing arguments and converting objects to the correct data type.
    */
   public PathTraversal(Object o, ReaderParser parser) {
      this.session = parser == null ? MarshallingContext.DEFAULT_SESSION : parser.getMarshallingContext().getSession();
      this.root = new JsonNode(null, null, o, session.object());
   }

   /**
    * Remove an element from a POJO model.
    *
    * <p>
    * If the element does not exist, no action is taken.
    *
    * @param url
    *    The URL of the element being deleted.
    *    If <jk>null</jk> or blank, the root itself is deleted.
    * @return The removed element, or null if that element does not exist.
    */
   public Object delete(String url) {
      return service(DELETE, url, null);
   }

   /**
    * Retrieves the element addressed by the URL.
    *
    * @param url
    *    The URL of the element to retrieve.
    *    <br>If <jk>null</jk> or blank, returns the root.
    * @return The addressed element, or <jk>null</jk> if that element does not exist in the tree.
    */
   public Object get(String url) {
      return getWithDefault(url, null);
   }

   /**
    * Retrieves the element addressed by the URL as the specified object type.
    *
    * <p>
    * Will convert object to the specified type per {@link MarshallingSession#convertToType(Object, Class)}.
    *
    * <h5 class='section'>Examples:</h5>
    * <p class='bjava'>
    *    PathTraversal <jv>pathTraversal</jv> = <jk>new</jk> PathTraversal(<jv>object</jv>);
    *
    *    <jc>// Value converted to a string.</jc>
    *    String <jv>string</jv> = <jv>pathTraversal</jv>.get(<js>"path/to/string"</js>, String.<jk>class</jk>);
    *
    *    <jc>// Value converted to a bean.</jc>
    *    MyBean <jv>bean</jv> = <jv>pathTraversal</jv>.get(<js>"path/to/bean"</js>, MyBean.<jk>class</jk>);
    *
    *    <jc>// Value converted to a bean array.</jc>
    *    MyBean[] <jv>beanArray</jv> = <jv>pathTraversal</jv>.get(<js>"path/to/beanarray"</js>, MyBean[].<jk>class</jk>);
    *
    *    <jc>// Value converted to a linked-list of objects.</jc>
    *    List <jv>list</jv> = <jv>pathTraversal</jv>.get(<js>"path/to/list"</js>, LinkedList.<jk>class</jk>);
    *
    *    <jc>// Value converted to a map of object keys/values.</jc>
    *    Map <jv>map</jv> = <jv>pathTraversal</jv>.get(<js>"path/to/map"</js>, TreeMap.<jk>class</jk>);
    * </p>
    *
    * @param url
    *    The URL of the element to retrieve.
    *    If <jk>null</jk> or blank, returns the root.
    * @param type The specified object type.
    *
    * @param <T> The specified object type.
    * @return The addressed element, or null if that element does not exist in the tree.
    */
   public <T> T get(String url, Class<T> type) {
      return getWithDefault(url, null, type);
   }

   /**
    * Retrieves the element addressed by the URL as the specified object type.
    *
    * <p>
    * Will convert object to the specified type per {@link MarshallingSession#convertToType(Object, Class)}.
    *
    * <p>
    * The type can be a simple type (e.g. beans, strings, numbers) or parameterized type (collections/maps).
    *
    * <h5 class='section'>Examples:</h5>
    * <p class='bjava'>
    *    PathTraversal <jv>pathTraversal</jv> = <jk>new</jk> PathTraversal(<jv>object</jv>);
    *
    *    <jc>// Value converted to a linked-list of strings.</jc>
    *    List&lt;String&gt; <jv>list1</jv> = <jv>pathTraversal</jv>.get(<js>"path/to/list1"</js>, LinkedList.<jk>class</jk>, String.<jk>class</jk>);
    *
    *    <jc>// Value converted to a linked-list of beans.</jc>
    *    List&lt;MyBean&gt; <jv>list2</jv> = <jv>pathTraversal</jv>.get(<js>"path/to/list2"</js>, LinkedList.<jk>class</jk>, MyBean.<jk>class</jk>);
    *
    *    <jc>// Value converted to a linked-list of linked-lists of strings.</jc>
    *    List&lt;List&lt;String&gt;&gt; <jv>list3</jv> = <jv>pathTraversal</jv>.get(<js>"path/to/list3"</js>, LinkedList.<jk>class</jk>, LinkedList.<jk>class</jk>, String.<jk>class</jk>);
    *
    *    <jc>// Value converted to a map of string keys/values.</jc>
    *    Map&lt;String,String&gt; <jv>map1</jv> = <jv>pathTraversal</jv>.get(<js>"path/to/map1"</js>, TreeMap.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>);
    *
    *    <jc>// Value converted to a map containing string keys and values of lists containing beans.</jc>
    *    Map&lt;String,List&lt;MyBean&gt;&gt; <jv>map2</jv> = <jv>pathTraversal</jv>.get(<js>"path/to/map2"</js>, TreeMap.<jk>class</jk>, String.<jk>class</jk>, List.<jk>class</jk>, MyBean.<jk>class</jk>);
    * </p>
    *
    * <p>
    * <c>Collection</c> classes are assumed to be followed by zero or one objects indicating the element type.
    *
    * <p>
    * <c>Map</c> classes are assumed to be followed by zero or two meta objects indicating the key and value types.
    *
    * <p>
    * The array can be arbitrarily long to indicate arbitrarily complex data structures.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       Use the {@link #get(String, Class)} method instead if you don't need a parameterized map/collection.
    * </ul>
    *
    * @param url
    *    The URL of the element to retrieve.
    *    If <jk>null</jk> or blank, returns the root.
    * @param type The specified object type.
    * @param args The specified object parameter types.
    *
    * @param <T> The specified object type.
    * @return The addressed element, or null if that element does not exist in the tree.
    */
   public <T> T get(String url, Type type, Type...args) {
      return getWithDefault(url, null, type, args);
   }

   /**
    * Returns the specified entry value converted to a {@link Boolean}.
    *
    * <p>
    * Shortcut for <code>get(Boolean.<jk>class</jk>, key)</code>.
    *
    * @param url The key.
    * @return The converted value, or <jk>null</jk> if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public Boolean getBoolean(String url) {
      return get(url, Boolean.class);
   }

   /**
    * Returns the specified entry value converted to a {@link Boolean}.
    *
    * <p>
    * Shortcut for <code>get(Boolean.<jk>class</jk>, key, defVal)</code>.
    *
    * @param url The key.
    * @param defVal The default value if the map doesn't contain the specified mapping.
    * @return The converted value, or the default value if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public Boolean getBoolean(String url, Boolean defVal) {
      return getWithDefault(url, defVal, Boolean.class);
   }

   /**
    * Returns the class type of the object at the specified URL.
    *
    * @param url The URL.
    * @return The class type, or <jk>null</jk> if the addressed element does not exist in the tree.
    */
   public ClassMeta getClassMeta(String url) {
      var n = getNode(normalizeUrl(url), root);
      if (n == null)
         return null;
      return n.cm;
   }

   /**
    * Returns the specified entry value converted to an {@link Integer}.
    *
    * <p>
    * Shortcut for <code>get(Integer.<jk>class</jk>, key)</code>.
    *
    * @param url The key.
    * @return The converted value, or <jk>null</jk> if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public Integer getInt(String url) {
      return get(url, Integer.class);
   }

   /**
    * Returns the specified entry value converted to an {@link Integer}.
    *
    * <p>
    * Shortcut for <code>get(Integer.<jk>class</jk>, key, defVal)</code>.
    *
    * @param url The key.
    * @param defVal The default value if the map doesn't contain the specified mapping.
    * @return The converted value, or the default value if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public Integer getInt(String url, Integer defVal) {
      return getWithDefault(url, defVal, Integer.class);
   }

   /**
    * Returns the specified entry value converted to a {@link JsonList}.
    *
    * <p>
    * Shortcut for <code>get(JsonList.<jk>class</jk>, key)</code>.
    *
    * @param url The key.
    * @return The converted value, or <jk>null</jk> if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public JsonList getJsonList(String url) {
      return get(url, JsonList.class);
   }

   /**
    * Returns the specified entry value converted to a {@link JsonList}.
    *
    * <p>
    * Shortcut for <code>get(JsonList.<jk>class</jk>, key, defVal)</code>.
    *
    * @param url The key.
    * @param defVal The default value if the map doesn't contain the specified mapping.
    * @return The converted value, or the default value if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public JsonList getJsonList(String url, JsonList defVal) {
      return getWithDefault(url, defVal, JsonList.class);
   }

   /**
    * Returns the specified entry value converted to a {@link Map}.
    *
    * <p>
    * Shortcut for <code>get(JsonMap.<jk>class</jk>, key)</code>.
    *
    * @param url The key.
    * @return The converted value, or <jk>null</jk> if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public JsonMap getJsonMap(String url) {
      return get(url, JsonMap.class);
   }

   /**
    * Returns the specified entry value converted to a {@link JsonMap}.
    *
    * <p>
    * Shortcut for <code>get(JsonMap.<jk>class</jk>, key, defVal)</code>.
    *
    * @param url The key.
    * @param defVal The default value if the map doesn't contain the specified mapping.
    * @return The converted value, or the default value if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public JsonMap getJsonMap(String url, JsonMap defVal) {
      return getWithDefault(url, defVal, JsonMap.class);
   }

   /**
    * Returns the specified entry value converted to a {@link List}.
    *
    * <p>
    * Shortcut for <code>get(List.<jk>class</jk>, key)</code>.
    *
    * @param url The key.
    * @return The converted value, or <jk>null</jk> if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public List<?> getList(String url) {
      return get(url, List.class);
   }

   /**
    * Returns the specified entry value converted to a {@link List}.
    *
    * <p>
    * Shortcut for <code>get(List.<jk>class</jk>, key, defVal)</code>.
    *
    * @param url The key.
    * @param defVal The default value if the map doesn't contain the specified mapping.
    * @return The converted value, or the default value if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public List<?> getList(String url, List<?> defVal) {
      return getWithDefault(url, defVal, List.class);
   }

   /**
    * Returns the specified entry value converted to a {@link Long}.
    *
    * <p>
    * Shortcut for <code>get(Long.<jk>class</jk>, key)</code>.
    *
    * @param url The key.
    * @return The converted value, or <jk>null</jk> if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public Long getLong(String url) {
      return get(url, Long.class);
   }

   /**
    * Returns the specified entry value converted to a {@link Long}.
    *
    * <p>
    * Shortcut for <code>get(Long.<jk>class</jk>, key, defVal)</code>.
    *
    * @param url The key.
    * @param defVal The default value if the map doesn't contain the specified mapping.
    * @return The converted value, or the default value if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public Long getLong(String url, Long defVal) {
      return getWithDefault(url, defVal, Long.class);
   }

   /**
    * Returns the specified entry value converted to a {@link Map}.
    *
    * <p>
    * Shortcut for <code>get(Map.<jk>class</jk>, key)</code>.
    *
    * @param url The key.
    * @return The converted value, or <jk>null</jk> if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public Map<?,?> getMap(String url) {
      return get(url, Map.class);
   }

   /**
    * Returns the specified entry value converted to a {@link Map}.
    *
    * <p>
    * Shortcut for <code>get(Map.<jk>class</jk>, key, defVal)</code>.
    *
    * @param url The key.
    * @param defVal The default value if the map doesn't contain the specified mapping.
    * @return The converted value, or the default value if the map contains no mapping for this key.
    * @throws InvalidDataConversionException If value cannot be converted.
    */
   public Map<?,?> getMap(String url, Map<?,?> defVal) {
      return getWithDefault(url, defVal, Map.class);
   }

   /**
    * The root object that was passed into the constructor of this method.
    *
    * @return The root object.
    */
   public Object getRootObject() { return root.o; }

   /**
    * Returns the specified entry value converted to a {@link String}.
    *
    * <p>
    * Shortcut for <code>get(String.<jk>class</jk>, key)</code>.
    *
    * @param url The key.
    * @return The converted value, or <jk>null</jk> if the map contains no mapping for this key.
    */
   public String getString(String url) {
      return get(url, String.class);
   }

   /**
    * Returns the specified entry value converted to a {@link String}.
    *
    * <p>
    * Shortcut for <code>get(String.<jk>class</jk>, key, defVal)</code>.
    *
    * @param url The key.
    * @param defVal The default value if the map doesn't contain the specified mapping.
    * @return The converted value, or the default value if the map contains no mapping for this key.
    */
   public String getString(String url, String defVal) {
      return getWithDefault(url, defVal, String.class);
   }

   /**
    * Retrieves the element addressed by the URL.
    *
    * @param url
    *    The URL of the element to retrieve.
    *    <br>If <jk>null</jk> or blank, returns the root.
    * @param defVal The default value if the map doesn't contain the specified mapping.
    * @return The addressed element, or null if that element does not exist in the tree.
    */
   public Object getWithDefault(String url, Object defVal) {
      var o = service(GET, url, null);
      return o == null ? defVal : o;
   }

   /**
    * Same as {@link #get(String, Class)} but returns a default value if the addressed element is null or non-existent.
    *
    * @param url
    *    The URL of the element to retrieve.
    *    If <jk>null</jk> or blank, returns the root.
    * @param def The default value if addressed item does not exist.
    * @param type The specified object type.
    *
    * @param <T> The specified object type.
    * @return The addressed element, or null if that element does not exist in the tree.
    */
   public <T> T getWithDefault(String url, T def, Class<T> type) {
      var o = service(GET, url, null);
      if (o == null)
         return def;
      return session.convertToType(o, type);
   }

   /**
    * Same as {@link #get(String,Type,Type[])} but returns a default value if the addressed element is null or non-existent.
    *
    * @param url
    *    The URL of the element to retrieve.
    *    If <jk>null</jk> or blank, returns the root.
    * @param def The default value if addressed item does not exist.
    * @param type The specified object type.
    * @param args The specified object parameter types.
    *
    * @param <T> The specified object type.
    * @return The addressed element, or null if that element does not exist in the tree.
    */
   public <T> T getWithDefault(String url, T def, Type type, Type...args) {
      var o = service(GET, url, null);
      if (o == null)
         return def;
      return session.convertToType(o, type, args);
   }

   /**
    * Adds a value to a list element in a POJO model.
    *
    * <p>
    * The URL is the address of the list being added to.
    *
    * <p>
    * If the list does not already exist, it will be created.
    *
    * <p>
    * This method expands the POJO model as necessary to create the new element.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       You can only post to three types of nodes:
    *       <ul>
    *          <li>{@link List Lists}
    *          <li>{@link Map Maps} containing integers as keys (i.e sparse arrays)
    *          <li>arrays
    *       </ul>
    * </ul>
    *
    * @param url
    *    The URL of the element being added to.
    *    If <jk>null</jk> or blank, the root itself (assuming it's one of the types specified above) is added to.
    * @param val The value being added.
    * @return The URL of the element that was added, or <jk>null</jk> if the value was added to a non-indexable (non-{@link List}) collection.
    */
   public String post(String url, Object val) {
      return (String)service(POST, url, val);
   }

   /**
    * Sets/replaces the element addressed by the URL.
    *
    * <p>
    * This method expands the POJO model as necessary to create the new element.
    *
    * @param url
    *    The URL of the element to create.
    *    If <jk>null</jk> or blank, the root itself is replaced with the specified value.
    * @param val The value being set.  Value can be of any type.
    * @return The previously addressed element, or <jk>null</jk> if the element did not previously exist.
    */
   public Object put(String url, Object val) {
      return service(PUT, url, val);
   }

   /**
    * Call this method to prevent the root object from being overwritten on <c>put("", xxx);</c> calls.
    *
    * @return This object.
    */
   public PathTraversal setRootLocked() {
      this.rootLocked = true;
      return this;
   }

   @Override /* Overridden from Object */
   public String toString() {
      return String.valueOf(root.o);
   }

   private Object[] addArrayEntry(Object o, Object val, ClassMeta componentType) {
      var a = (Object[])o;
      // Expand out the array.
      var a2 = (Object[])Array.newInstance(a.getClass().getComponentType(), a.length + 1);
      System.arraycopy(a, 0, a2, 0, a.length);
      a2[a.length] = convert(val, componentType);
      return a2;
   }

   private Object convert(Object in, ClassMeta cm) {
      if (cm == null)
         return in;
      if (cm.isBean() && in instanceof Map in2)
         return session.convertToType(in2, cm);
      return in;
   }

   /*
    * Workhorse method.
    */
   @SuppressWarnings({
      "java:S6541" // Cognitive complexity acceptable for REST operation routing logic
   })
   private Object service(int method, String url, Object val) throws PathTraversalException {

      url = normalizeUrl(url);

      if (method == GET) {
         var p = getNode(url, root);
         return p == null ? null : p.o;
      }

      // Get the url of the parent and the property name of the addressed object.
      var i = url.lastIndexOf('/');
      var parentUrl = (i == -1 ? null : url.substring(0, i));
      var childKey = (i == -1 ? url : url.substring(i + 1));

      if (method == PUT) {
         if (url.isEmpty()) {
            if (rootLocked)
               throw new PathTraversalException(HTTP_FORBIDDEN, "Cannot overwrite root object");
            var o = root.o;
            root = new JsonNode(null, null, val, session.object());
            return o;
         }
         var n = (parentUrl == null ? root : getNode(parentUrl, root));
         if (n == null)
            throw new PathTraversalException(HTTP_NOT_FOUND, "Node at URL '%s' not found.", parentUrl);
         if (n.o == null && n.cm.isObject())
            throw new PathTraversalException(HTTP_NOT_FOUND, "Node at URL '%s' not found.", parentUrl);
         var cm = n.cm;
         var o = n.o;
         if (cm.isMap())
            return ((Map)o).put(childKey, convert(val, cm.getValueType()));
         if (cm.isCollection() && o instanceof List o2)
            return o2.set(parseInt(childKey), convert(val, cm.getElementType()));
         if (cm.isCollection())
            throw new PathTraversalException(HTTP_BAD_REQUEST, "Cannot PUT to indexed position in non-List collection '%s' of type '%s'", url, cm);
         if (cm.isArray()) {
            o = setArrayEntry(n.o, parseInt(childKey), val, cm.getElementType());
            var pct = n.parent.cm;
            var po = n.parent.o;
            if (pct.isMap()) {
               ((Map)po).put(n.keyName, o);
               return url;
            }
            if (pct.isBean()) {
               var m = session.toBeanMap(po);
               m.put(n.keyName, o);
               return url;
            }
            throw new PathTraversalException(HTTP_BAD_REQUEST, "Cannot perform PUT on '%s' with parent node type '%s'", url, pct);
         }
         if (cm.isBean())
            return session.toBeanMap(o).put(childKey, val);
         throw new PathTraversalException(HTTP_BAD_REQUEST, "Cannot perform PUT on '%s' whose parent is of type '%s'", url, cm);
      }

      if (method == POST) {
         // Handle POST to root special
         if (url.isEmpty()) {
            var cm = root.cm;
            var o = root.o;
            if (cm.isCollection()) {
               var c = (Collection)o;
               c.add(convert(val, cm.getElementType()));
               return (c instanceof List c2 ? url + "/" + (c2.size() - 1) : null);
            }
            if (cm.isArray()) {
               var o2 = addArrayEntry(o, val, cm.getElementType());
               root = new JsonNode(null, null, o2, null);
               return url + "/" + (o2.length - 1);
            }
            throw new PathTraversalException(HTTP_BAD_REQUEST, "Cannot perform POST on '%s' of type '%s'", url, cm);
         }
         var n = getNode(url, root);
         if (n == null)
            throw new PathTraversalException(HTTP_NOT_FOUND, "Node at URL '%s' not found.", url);
         if (n.o == null && n.cm.isObject())
            throw new PathTraversalException(HTTP_NOT_FOUND, "Node at URL '%s' not found.", url);
         var cm = n.cm;
         var o = n.o;
         if (cm.isArray()) {
            var o2 = addArrayEntry(o, val, cm.getElementType());
            var pct = n.parent.cm;
            var po = n.parent.o;
            if (pct.isMap()) {
               ((Map)po).put(childKey, o2);
               return url + "/" + (o2.length - 1);
            }
            if (pct.isBean()) {
               var m = session.toBeanMap(po);
               m.put(childKey, o2);
               return url + "/" + (o2.length - 1);
            }
            throw new PathTraversalException(HTTP_BAD_REQUEST, "Cannot perform POST on '%s' with parent node type '%s'", url, pct);
         }
         if (cm.isCollection()) {
            var c = (Collection)o;
            c.add(convert(val, cm.getElementType()));
            return (c instanceof List c2 ? url + "/" + (c2.size() - 1) : null);
         }
         throw new PathTraversalException(HTTP_BAD_REQUEST, "Cannot perform POST on '%s' of type '%s'", url, cm);
      }

      if (method == DELETE) {
         if (url.isEmpty()) {
            if (rootLocked)
               throw new PathTraversalException(HTTP_FORBIDDEN, "Cannot overwrite root object");
            var o = root.o;
            root = new JsonNode(null, null, null, session.object());
            return o;
         }
         var n = (parentUrl == null ? root : getNode(parentUrl, root));
         if (n == null)
            throw new PathTraversalException(HTTP_NOT_FOUND, "Node at URL '%s' not found.", parentUrl);
         if (n.o == null && n.cm.isObject())
            throw new PathTraversalException(HTTP_NOT_FOUND, "Node at URL '%s' not found.", parentUrl);
         var cm = n.cm;
         var o = n.o;
         if (cm.isMap())
            return ((Map)o).remove(childKey);
         if (cm.isCollection() && o instanceof List o2)
            return o2.remove(parseInt(childKey));
         if (cm.isCollection())
            throw new PathTraversalException(HTTP_BAD_REQUEST, "Cannot DELETE indexed position in non-List collection '%s' of type '%s'", url, cm);
         if (cm.isArray()) {
            int index = parseInt(childKey);
            var old = ((Object[])o)[index];
            var o2 = removeArrayEntry(o, index);
            var pct = n.parent.cm;
            var po = n.parent.o;
            if (pct.isMap()) {
               ((Map)po).put(n.keyName, o2);
               return old;
            }
            if (pct.isBean()) {
               var m = session.toBeanMap(po);
               m.put(n.keyName, o2);
               return old;
            }
            throw new PathTraversalException(HTTP_BAD_REQUEST, "Cannot perform POST on '%s' with parent node type '%s'", url, pct);
         }
         if (cm.isBean())
            return session.toBeanMap(o).put(childKey, null);
         throw new PathTraversalException(HTTP_BAD_REQUEST, "Cannot perform PUT on '%s' whose parent is of type '%s'", url, cm);
      }

      return null;   // Never gets here.
   }

   private Object[] setArrayEntry(Object o, int index, Object val, ClassMeta componentType) {
      var a = (Object[])o;
      if (a.length <= index) {
         // Expand out the array.
         var a2 = (Object[])Array.newInstance(a.getClass().getComponentType(), index + 1);
         System.arraycopy(a, 0, a2, 0, a.length);
         a = a2;
      }
      a[index] = convert(val, componentType);
      return a;
   }

   JsonNode getNode(String url, JsonNode n) {
      if (isEmpty(url))
         return n;
      int i = url.indexOf('/');
      String parentKey;
      String childUrl = null;
      if (i == -1) {
         parentKey = url;
      } else {
         parentKey = url.substring(0, i);
         childUrl = url.substring(i + 1);
      }

      var o = n.o;
      Object o2 = null;
      var cm = n.cm;
      ClassMeta ct2 = null;
      if (o == null)
         return null;
      if (cm.isMap()) {
         o2 = ((Map)o).get(parentKey);
         ct2 = cm.getValueType();
      } else if (cm.isCollection() && o instanceof List o3) {
         var key = parseInt(parentKey);
         if (o3.size() <= key)
            return null;
         o2 = o3.get(key);
         ct2 = cm.getElementType();
      } else if (cm.isArray()) {
         var key = parseInt(parentKey);
         var a = ((Object[])o);
         if (a.length <= key)
            return null;
         o2 = a[key];
         ct2 = cm.getElementType();
      } else if (cm.isBean()) {
         var m = session.toBeanMap(o);
         o2 = m.get(parentKey);
         var pMeta = m.getPropertyMeta(parentKey);
         if (pMeta == null)
            throw new PathTraversalException(HTTP_BAD_REQUEST, "Unknown property '%s' encountered while trying to parse into class '%s'", parentKey, m.getBeanInfo());
         ct2 = (ClassMeta) pMeta.getBeanInfo();
      }

      if (childUrl == null)
         return new JsonNode(n, parentKey, o2, ct2);

      return getNode(childUrl, new JsonNode(n, parentKey, o2, ct2));
   }
}