IFunction.java
/*
* 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"));
}
}
}