/*
    * Portions of this software was developed by employees of the National Institute
    * of Standards and Technology (NIST), an agency of the Federal Government and is
    * being made available as a public service. Pursuant to title 17 United States
    * Code Section 105, works of NIST employees are not subject to copyright
    * protection in the United States. This software may be subject to foreign
    * copyright. Permission in the United States and in foreign countries, to the
    * extent that NIST may hold copyright, to use, copy, modify, create derivative
    * works, and distribute this software and its documentation without fee is hereby
   * granted on a non-exclusive basis, provided that this notice and disclaimer
   * of warranty appears in all copies.
   *
   * THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, EITHER
   * EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY
   * THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF
   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND FREEDOM FROM
   * INFRINGEMENT, AND ANY WARRANTY THAT THE DOCUMENTATION WILL CONFORM TO THE
   * SOFTWARE, OR ANY WARRANTY THAT THE SOFTWARE WILL BE ERROR FREE.  IN NO EVENT
   * SHALL NIST BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT,
   * INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM,
   * OR IN ANY WAY CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY,
   * CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR
   * PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT
   * OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SERVICES PROVIDED HEREUNDER.
   */
  
  package gov.nist.secauto.metaschema.core.metapath.function;
  
  import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
  import gov.nist.secauto.metaschema.core.metapath.ISequence;
  import gov.nist.secauto.metaschema.core.metapath.MetapathException;
  import gov.nist.secauto.metaschema.core.metapath.item.IItem;
  import gov.nist.secauto.metaschema.core.util.ObjectUtils;
  
  import java.net.URI;
  import java.util.ArrayList;
  import java.util.EnumSet;
  import java.util.LinkedList;
  import java.util.List;
  import java.util.Objects;
  import java.util.Set;
  
  import javax.xml.namespace.QName;
  
  import edu.umd.cs.findbugs.annotations.NonNull;
  
  public interface IFunction {
    enum FunctionProperty {
      /**
       * Indicates that the function will produce identical results for the same
       * arguments (see XPath 3.1 <a href=
       * "https://www.w3.org/TR/xpath-functions-31/#dt-deterministic">deterministic</a>).
       * If not assigned to a function definition, a function call with the same
       * arguments is not guaranteed to produce the same results in the same order for
       * subsequent calls within the same execution context.
       */
      DETERMINISTIC,
      /**
       * Indicates that the result of the function depends on property values within
       * the static or dynamic context and the provided arguments (see XPath 3.1
       * <a href=
       * "https://www.w3.org/TR/xpath-functions-31/#dt-context-dependent">context-dependent</a>).
       * If not assigned to a function definition, a call will not be affected by the
       * property values within the static or dynamic context and will not have any
       * arguments.
       */
      CONTEXT_DEPENDENT,
      /**
       * Indicates that the result of the function depends on the current focus (see
       * XPath 3.1 <a href=
       * "https://www.w3.org/TR/xpath-functions-31/#dt-focus-independent">focus-dependent</a>).
       * If not assigned to a function definition, a call will not be affected by the
       * current focus.
       */
      FOCUS_DEPENDENT,
      /**
       * The function allows the last argument to be repeated any number of times.
       */
      UNBOUNDED_ARITY;
    }
  
    /**
     * Retrieve the name of the function.
     *
     * @return the function's name
     */
    @NonNull
    String getName();
  
    /**
     * Retrieve the namespace of the function.
     *
     * @return the function's namespace
     */
    @NonNull
    String getNamespace();
  
    /**
     * Retrieve the namespace qualified name of the function.
    *
    * @return the namespace qualified name
    */
   @NonNull
   default QName getQName() {
     return new QName(getNamespace(), getName());
   }
 
   /**
    * Retrieve the set of assigned function properties.
    *
    * @return the set of properties or an empty set
    */
   @NonNull
   Set<FunctionProperty> getProperties();
 
   /**
    * Retrieve the list of function arguments.
    *
    * @return the function arguments or an empty list if there are none
    */
   @NonNull
   List<IArgument> getArguments();
 
   /**
    * Determine the number of arguments the function has.
    *
    * @return the number of function arguments
    */
   int arity();
 
   /**
    * Determines if the result of the function call will produce identical results
    * when provided the same implicit or explicit arguments.
    *
    * @return {@code true} if function is deterministic or {@code false} otherwise
    * @see FunctionProperty#DETERMINISTIC
    */
   default boolean isDeterministic() {
     return getProperties().contains(FunctionProperty.DETERMINISTIC);
   }
 
   /**
    * Determines if the result of the function call depends on property values
    * within the static or dynamic context and the provided arguments.
    *
    * @return {@code true} if function is context dependent or {@code false}
    *         otherwise
    * @see FunctionProperty#CONTEXT_DEPENDENT
    */
   default boolean isContextDepenent() {
     return getProperties().contains(FunctionProperty.CONTEXT_DEPENDENT);
   }
 
   /**
    * Determines if the result of the function call depends on the current focus.
    *
    * @return {@code true} if function is focus dependent or {@code false}
    *         otherwise
    * @see FunctionProperty#FOCUS_DEPENDENT
    */
   default boolean isFocusDepenent() {
     return getProperties().contains(FunctionProperty.FOCUS_DEPENDENT);
   }
 
   /**
    * Determines if the final argument can be repeated.
    *
    * @return {@code true} if the final argument can be repeated or {@code false}
    *         otherwise
    * @see FunctionProperty#UNBOUNDED_ARITY
    */
   default boolean isArityUnbounded() {
     return getProperties().contains(FunctionProperty.UNBOUNDED_ARITY);
   }
 
   /**
    * Retrieve the function result sequence type.
    *
    * @return the function result sequence type
    */
   @NonNull
   ISequenceType getResult();
 
   // /**
   // * Determines by static analysis if the function supports the expression
   // arguments provided.
   // *
   // * @param arguments
   // * the expression arguments to evaluate
   // * @return {@code true} if the arguments are supported or {@code false}
   // otherwise
   // */
   // boolean isSupported(List<IExpression<?>> arguments);
 
   @NonNull
   ISequence<?> execute(
       @NonNull List<ISequence<?>> arguments,
       @NonNull DynamicContext dynamicContext,
       @NonNull ISequence<?> focus) throws MetapathException;
 
   /**
    * Get the signature of the function as a string.
    *
    * @return the signature
    */
   String toSignature();
 
   @NonNull
   static Builder builder() {
     return new Builder();
   }
 
   @SuppressWarnings("PMD.LooseCoupling")
   class Builder {
     private String name;
     private String namespace;
     @SuppressWarnings("null")
     @NonNull
     private final EnumSet<FunctionProperty> properties = EnumSet.noneOf(FunctionProperty.class);
     @NonNull
     private final List<IArgument> arguments = new LinkedList<>();
     private Class<? extends IItem> returnType = IItem.class;
     private Occurrence returnOccurrence = Occurrence.ONE;
     private IFunctionExecutor functionHandler;
 
     @NonNull
     public Builder name(@NonNull String name) {
       Objects.requireNonNull(name, "name");
       if (name.isBlank()) {
         throw new IllegalArgumentException("the name must be non-blank");
       }
       this.name = name.trim();
       return this;
     }
 
     @NonNull
     public Builder namespace(@NonNull URI uri) {
       return namespace(ObjectUtils.notNull(uri.toASCIIString()));
     }
 
     @NonNull
     public Builder namespace(@NonNull String name) {
       Objects.requireNonNull(name, "name");
       if (name.isBlank()) {
         throw new IllegalArgumentException("the name must be non-blank");
       }
       this.namespace = name.trim();
       return this;
     }
 
     @NonNull
     public Builder deterministic() {
       properties.add(FunctionProperty.DETERMINISTIC);
       return this;
     }
 
     @NonNull
     public Builder nonDeterministic() {
       properties.remove(FunctionProperty.DETERMINISTIC);
       return this;
     }
 
     @NonNull
     public Builder contextDependent() {
       properties.add(FunctionProperty.CONTEXT_DEPENDENT);
       return this;
     }
 
     @NonNull
     public Builder contextIndependent() {
       properties.remove(FunctionProperty.CONTEXT_DEPENDENT);
       return this;
     }
 
     @NonNull
     public Builder focusDependent() {
       properties.add(FunctionProperty.FOCUS_DEPENDENT);
       return this;
     }
 
     @NonNull
     public Builder focusIndependent() {
       properties.remove(FunctionProperty.FOCUS_DEPENDENT);
       return this;
     }
 
     @NonNull
     public Builder allowUnboundedArity(boolean allow) {
       if (allow) {
         properties.add(FunctionProperty.UNBOUNDED_ARITY);
       } else {
         properties.remove(FunctionProperty.UNBOUNDED_ARITY);
       }
       return this;
     }
 
     @NonNull
     public Builder returnType(@NonNull Class<? extends IItem> type) {
       Objects.requireNonNull(type, "type");
       this.returnType = type;
       return this;
     }
 
     @NonNull
     public Builder returnZeroOrOne() {
       return returnOccurrence(Occurrence.ZERO_OR_ONE);
     }
 
     @NonNull
     public Builder returnOne() {
       return returnOccurrence(Occurrence.ONE);
     }
 
     @NonNull
     public Builder returnZeroOrMore() {
       return returnOccurrence(Occurrence.ZERO_OR_MORE);
     }
 
     @NonNull
     public Builder returnOneOrMore() {
       return returnOccurrence(Occurrence.ONE_OR_MORE);
     }
 
     @NonNull
     public Builder returnOccurrence(@NonNull Occurrence occurrence) {
       Objects.requireNonNull(occurrence, "occurrence");
       this.returnOccurrence = occurrence;
       return this;
     }
 
     @NonNull
     public Builder argument(@NonNull IArgument.Builder builder) {
       return argument(builder.build());
     }
 
     @NonNull
     public Builder argument(@NonNull IArgument argument) {
       Objects.requireNonNull(argument, "argument");
       this.arguments.add(argument);
       return this;
     }
 
     @NonNull
     public Builder functionHandler(@NonNull IFunctionExecutor handler) {
       Objects.requireNonNull(handler, "handler");
       this.functionHandler = handler;
       return this;
     }
 
     @NonNull
     public IFunction build() {
       ISequenceType sequenceType;
       if (returnType == null) {
         sequenceType = ISequenceType.EMPTY;
       } else {
         sequenceType = new SequenceTypeImpl(
             returnType,
             ObjectUtils.requireNonNull(returnOccurrence, "the return occurrence must not be null"));
       }
 
       if (properties.contains(FunctionProperty.UNBOUNDED_ARITY) && arguments.isEmpty()) {
         throw new IllegalStateException("to allow unbounded arity, at least one argument must be provided");
       }
 
       return new DefaultFunction(
           ObjectUtils.requireNonNull(name, "the name must not be null"),
           ObjectUtils.requireNonNull(namespace, "the namespace must not be null"),
           properties,
           new ArrayList<>(arguments),
           sequenceType,
           ObjectUtils.requireNonNull(functionHandler, "the function handler must not be null"));
     }
   }
 }