/*
 * Copyright (c) 2011-2017 Contributors to the Eclipse Foundation
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
 * which is available at https://www.apache.org/licenses/LICENSE-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 */

package io.vertx.core.json.pointer;

import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.GenIgnore;
import io.vertx.codegen.annotations.Nullable;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.json.pointer.impl.JsonPointerImpl;

import java.net.URI;
import java.util.List;
import java.util.function.Consumer;
import java.util.stream.Stream;

Implementation of RFC6901 Json Pointers.
Author:
Francesco Guardiani @slinkydeveloper/**
 * Implementation of <a href="https://tools.ietf.org/html/rfc6901">RFC6901 Json Pointers</a>.
 *
 * @author Francesco Guardiani <a href="https://slinkydeveloper.github.io/">@slinkydeveloper</a>
 */
@VertxGen
public interface JsonPointer {

  
Return true if the pointer is a root pointer /**
   * Return {@code true} if the pointer is a root pointer
   */
  boolean isRootPointer();

  
Return true if the pointer is local (URI with only fragment) /**
   * Return {@code true} if the pointer is local (URI with only fragment)
   */
  boolean isLocalPointer();

  
Return true if this pointer is a parent pointer of child. 
 For instance "/properties" pointer is parent pointer of "/properties/parent" 
Params:
child – /**
   * Return {@code true} if this pointer is a parent pointer of {@code child}.
   * <br/>
   * For instance {@code "/properties"} pointer is parent pointer of {@code "/properties/parent"}
   *
   * @param child
   */
  boolean isParent(JsonPointer child);

  
Build a string representation of the JSON Pointer
/**
   * Build a <a href="https://tools.ietf.org/html/rfc6901#section-5">string representation</a> of the JSON Pointer
   */
  @Override
  String toString();

  
Build a URI representation of the JSON Pointer
/**
   * Build a <a href="https://tools.ietf.org/html/rfc6901#section-6">URI representation</a> of the JSON Pointer
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  URI toURI();

  
Return the underlying URI without the fragment
/**
   * Return the underlying URI without the fragment
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  URI getURIWithoutFragment();

  
Append an unescaped token to this pointer 

Note: If you provide escaped path the behaviour is undefined
Params:
token – the unescaped reference token
Returns:
a reference to this, so the API can be used fluently/**
   * Append an unescaped {@code token} to this pointer <br/>
   * Note: If you provide escaped path the behaviour is undefined
   *
   * @param token the unescaped reference token
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  JsonPointer append(String token);

  
Append the index as reference token to JsonPointer 
Params:
index – 
Returns:
a reference to this, so the API can be used fluently/**
   * Append the {@code index} as reference token to JsonPointer
   *
   * @param index
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  JsonPointer append(int index);

  
Append an unescaped list of tokens to JsonPointer 

Note: If you provide escaped paths the behaviour is undefined
Params:
tokens – unescaped reference tokens
Returns:
a reference to this, so the API can be used fluently/**
   * Append an unescaped list of {@code tokens} to JsonPointer <br/>
   * Note: If you provide escaped paths the behaviour is undefined
   *
   * @param tokens unescaped reference tokens
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  JsonPointer append(List<String> tokens);

  
Append all tokens of pointer to this pointer 

Note: The base URI of this pointer will remain untouched
Params:
pointer – other pointer
Returns:
a reference to this, so the API can be used fluently/**
   * Append all tokens of {@code pointer} to this pointer <br/>
   * Note: The base URI of this pointer will remain untouched
   *
   * @param pointer other pointer
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  JsonPointer append(JsonPointer pointer);

  
Remove last reference token of this pointer
Returns:
a reference to this, so the API can be used fluently/**
   * Remove last reference token of this pointer
   *
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  JsonPointer parent();

  
Query objectToQuery using the provided JsonPointerIterator. 
 If you need to query Vert.x json data structures, use queryJson(Object)

Note: if this pointer is a root pointer, this function returns the provided object
Params:
objectToQuery – the object to query
iterator – the json pointer iterator that provides the logic to access to the objectToQuery
Returns:
null if pointer points to not existing value, otherwise the requested value/**
   * Query {@code objectToQuery} using the provided {@link JsonPointerIterator}. <br/>
   * If you need to query Vert.x json data structures, use {@link JsonPointer#queryJson(Object)}<br/>
   * Note: if this pointer is a root pointer, this function returns the provided object
   *
   * @param objectToQuery the object to query
   * @param iterator the json pointer iterator that provides the logic to access to the objectToQuery
   * @return null if pointer points to not existing value, otherwise the requested value
   */
  default @Nullable Object query(Object objectToQuery, JsonPointerIterator iterator) { return queryOrDefault(objectToQuery, iterator, null); }

  
Query objectToQuery using the provided JsonPointerIterator. If the query result is null, returns the default. 
 If you need to query Vert.x json data structures, use queryJsonOrDefault(Object, Object)

Note: if this pointer is a root pointer, this function returns the provided object
Params:
objectToQuery – the object to query
iterator – the json pointer iterator that provides the logic to access to the objectToQuery
defaultValue – default value if query result is null
Returns:
null if pointer points to not existing value, otherwise the requested value/**
   * Query {@code objectToQuery} using the provided {@link JsonPointerIterator}. If the query result is null, returns the default. <br/>
   * If you need to query Vert.x json data structures, use {@link JsonPointer#queryJsonOrDefault(Object, Object)}<br/>
   * Note: if this pointer is a root pointer, this function returns the provided object
   *
   * @param objectToQuery the object to query
   * @param iterator the json pointer iterator that provides the logic to access to the objectToQuery
   * @param defaultValue default value if query result is null
   * @return null if pointer points to not existing value, otherwise the requested value
   */
  Object queryOrDefault(Object objectToQuery, JsonPointerIterator iterator, Object defaultValue);

  
Query jsonElement. 

Note: if this pointer is a root pointer, this function returns the provided json element
Params:
jsonElement – the json element to query
Returns:
null if pointer points to not existing value, otherwise the requested value/**
   * Query {@code jsonElement}. <br/>
   * Note: if this pointer is a root pointer, this function returns the provided json element
   *
   * @param jsonElement the json element to query
   * @return null if pointer points to not existing value, otherwise the requested value
   */
  default @Nullable Object queryJson(Object jsonElement) {return query(jsonElement, JsonPointerIterator.JSON_ITERATOR); }

  
Query jsonElement. If the query result is null, returns the default.

Note: if this pointer is a root pointer, this function returns the provided object
Params:
jsonElement – the json element to query
defaultValue – default value if query result is null
Returns:
null if pointer points to not existing value, otherwise the requested value/**
   * Query {@code jsonElement}. If the query result is null, returns the default.<br/>
   * Note: if this pointer is a root pointer, this function returns the provided object
   *
   * @param jsonElement the json element to query
   * @param defaultValue default value if query result is null
   * @return null if pointer points to not existing value, otherwise the requested value
   */
  default @Nullable Object queryJsonOrDefault(Object jsonElement, Object defaultValue) {return queryOrDefault(jsonElement, JsonPointerIterator.JSON_ITERATOR, defaultValue); }

  
Query objectToQuery tracing each element walked during the query, including the first and the result (if any).

The first element of the list is objectToQuery and the last is the result, or the element before the first null was encountered
Params:
objectToQuery – the object to query
iterator – the json pointer iterator that provides the logic to access to the objectToQuery
Returns:
the stream of walked elements/**
   * Query {@code objectToQuery} tracing each element walked during the query, including the first and the result (if any).<br/>
   * The first element of the list is objectToQuery and the last is the result, or the element before the first null was encountered
   *
   * @param objectToQuery the object to query
   * @param iterator the json pointer iterator that provides the logic to access to the objectToQuery
   * @return the stream of walked elements
   */
  List<Object> tracedQuery(Object objectToQuery, JsonPointerIterator iterator);

  
Write newElement in objectToWrite using this pointer. The path token "-" is handled as append to end of array 
 If you need to write in Vert.x json data structures, use writeJson(Object, Object) (Object)}

Params:
objectToWrite – object to write
iterator – the json pointer iterator that provides the logic to access to the objectToMutate
newElement –  object to insert
createOnMissing – create objects when missing a object key or an array index
Returns:
a reference to objectToWrite if the write was completed, a reference to newElement if the pointer is a root pointer, null if the write failed/**
   * Write {@code newElement} in {@code objectToWrite} using this pointer. The path token "-" is handled as append to end of array <br/>
   * If you need to write in Vert.x json data structures, use {@link JsonPointer#writeJson(Object, Object)} (Object)}<br/>
   *
   * @param objectToWrite object to write
   * @param iterator the json pointer iterator that provides the logic to access to the objectToMutate
   * @param newElement  object to insert
   * @param createOnMissing create objects when missing a object key or an array index
   * @return a reference to objectToWrite if the write was completed, a reference to newElement if the pointer is a root pointer, null if the write failed
   */
  Object write(Object objectToWrite, JsonPointerIterator iterator, Object newElement, boolean createOnMissing);

  
Write newElement in jsonElement using this pointer. The path token "-" is handled as append to end of array. 
Params:
jsonElement – json element to query and write
newElement – json to insert
Returns:
a reference to json if the write was completed, a reference to newElement if the pointer is a root pointer, null if the write failed/**
   * Write {@code newElement} in {@code jsonElement} using this pointer. The path token "-" is handled as append to end of array.
   *
   * @param jsonElement json element to query and write
   * @param newElement json to insert
   * @return a reference to json if the write was completed, a reference to newElement if the pointer is a root pointer, null if the write failed
   */
  default Object writeJson(Object jsonElement, Object newElement) { return writeJson(jsonElement, newElement, false); }

  
Write newElement in jsonElement using this pointer. The path token "-" is handled as append to end of array. 
Params:
jsonElement – json to query and write
newElement – json to insert
createOnMissing – create JsonObject when missing a object key or an array index
Returns:
a reference to json if the write was completed, a reference to newElement if the pointer is a root pointer, null if the write failed/**
   * Write {@code newElement} in {@code jsonElement} using this pointer. The path token "-" is handled as append to end of array.
   *
   * @param jsonElement json to query and write
   * @param newElement json to insert
   * @param createOnMissing create JsonObject when missing a object key or an array index
   * @return a reference to json if the write was completed, a reference to newElement if the pointer is a root pointer, null if the write failed
   */
  default Object writeJson(Object jsonElement, Object newElement, boolean createOnMissing) {
    return write(jsonElement, JsonPointerIterator.JSON_ITERATOR, newElement, createOnMissing);
  }

  
Copy a JsonPointer
Returns:
a copy of this pointer/**
   * Copy a JsonPointer
   *
   * @return a copy of this pointer
   */
  JsonPointer copy();

  
Build an empty JsonPointer
Returns:
a new empty JsonPointer/**
   * Build an empty JsonPointer
   *
   * @return a new empty JsonPointer
   */
  static JsonPointer create() {
    return new JsonPointerImpl();
  }

  
Build a JsonPointer from a json pointer string
Params:
pointer – the string representing a pointer
Throws:
IllegalArgumentException – if the pointer provided is not valid
Returns:
new instance of JsonPointer/**
   * Build a JsonPointer from a json pointer string
   *
   * @param pointer the string representing a pointer
   * @return new instance of JsonPointer
   * @throws IllegalArgumentException if the pointer provided is not valid
   */
  static JsonPointer from(String pointer) {
    return new JsonPointerImpl(pointer);
  }

  
Build a JsonPointer from a URI.
Params:
uri – uri representing a json pointer
Throws:
IllegalArgumentException – if the pointer provided is not valid
Returns:
new instance of JsonPointer/**
   * Build a JsonPointer from a URI.
   *
   * @param uri uri representing a json pointer
   * @return new instance of JsonPointer
   * @throws IllegalArgumentException if the pointer provided is not valid
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  static JsonPointer fromURI(URI uri) {
    return new JsonPointerImpl(uri);
  }

}