001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.commons.svl; 018 019import java.util.*; 020 021/** 022 * SPI for SVL {@code #{...}} script-evaluation functions. 023 * 024 * <p> 025 * A {@code VarFunction} is invoked when an SVL template contains a 026 * <c>#{name(arg1, arg2, ...)}</c> reference — distinct from {@code ${X:...}} variables. Functions 027 * compose freely with {@code ${...}} lookups and other {@code #{...}} calls; arguments are 028 * pre-resolved by the runtime before {@link #invoke(VarResolverSession, List) invoke} is called. 029 * 030 * <h2 class='section'>Naming note:</h2> 031 * <p> 032 * Named {@code VarFunction} rather than the shorter {@code Function} because Juneau's 033 * serializer/parser/test code makes heavy use of {@link java.util.function.Function} and 034 * routinely co-imports {@code org.apache.juneau.commons.svl.*}; a bare {@code Function} type in 035 * this package would trigger ambiguous-reference errors across many callers. The chosen name 036 * also matches the existing {@code Var}/{@code VarResolver}/{@code VarTemplate}/{@code VarResolverSession} 037 * naming family. 038 * 039 * <p> 040 * Implementations can register through any of four discovery channels (later wins on name 041 * collision, except that {@code ServiceLoader} entries never replace an existing function): 042 * <ol> 043 * <li>The built-in catalog auto-registered by {@link VarResolver#DEFAULT}. 044 * <li>{@code META-INF/services/org.apache.juneau.commons.svl.VarFunction} (Java {@link ServiceLoader}), 045 * only when the resolver is built with {@code VarResolver.Builder.loadServices()}. 046 * <li>{@code BeanStore.getBeans(VarFunction.class)} on the resolver's bean store. 047 * <li>Explicit registrations via {@code VarResolver.Builder.functions(...)}. 048 * </ol> 049 * 050 * <p> 051 * For typed reflection-based dispatch (the recommended path), extend 052 * {@link TypedFunction} — it derives {@link #minArity()}, {@link #maxArity()}, and per-arg 053 * coercion automatically from the subclass's {@code invoke(...)} method signature, eliminating 054 * the per-function plumbing. 055 * 056 * <h2 class='section'>Example:</h2> 057 * <p class='bjava'> 058 * <jc>// Direct VarFunction impl (less common — TypedFunction is preferred).</jc> 059 * <jk>public class</jk> Reverse <jk>implements</jk> VarFunction { 060 * <ja>@Override</ja> <jk>public</jk> String name() { <jk>return</jk> <js>"reverse"</js>; } 061 * <ja>@Override</ja> <jk>public int</jk> minArity() { <jk>return</jk> 1; } 062 * <ja>@Override</ja> <jk>public int</jk> maxArity() { <jk>return</jk> 1; } 063 * <ja>@Override</ja> <jk>public</jk> String invoke(VarResolverSession <jv>session</jv>, List<Object> <jv>args</jv>) { 064 * <jk>return new</jk> StringBuilder((String) <jv>args</jv>.get(0)).reverse().toString(); 065 * } 066 * } 067 * </p> 068 * 069 * <h2 class='section'>See Also:</h2><ul> 070 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/MarshallSimpleVariableLanguage">Marshall Simple Variable Language</a> 071 * <li class='jc'>{@link TypedFunction} 072 * </ul> 073 */ 074public interface VarFunction { 075 076 /** 077 * The function's invocation name as it appears between {@code #{}} and the opening 078 * parenthesis in the template. Must consist of ASCII letters, digits, and underscores; must 079 * begin with a letter. 080 * 081 * @return The invocation name. Never {@code null} or empty. 082 */ 083 String name(); 084 085 /** 086 * Minimum argument count this function accepts. 087 * 088 * @return The minimum number of args. {@code 0} means the function may be called with no 089 * args. Returns {@code -1} for "any number of args" — equivalent to declaring 090 * {@code minArity == 0 && maxArity == Integer.MAX_VALUE}. 091 */ 092 int minArity(); 093 094 /** 095 * Maximum argument count this function accepts. 096 * 097 * @return The maximum number of args, or {@link Integer#MAX_VALUE} for unbounded variadic 098 * functions. 099 */ 100 int maxArity(); 101 102 /** 103 * Invokes this function with already-resolved, type-coerced arguments. 104 * 105 * <p> 106 * The runtime resolves each {@code #{...}} arg template against the session, then coerces 107 * the resolved string to the target Java type via {@code ArgCoercer}. The resulting 108 * {@code List<Object>} is passed in here. 109 * 110 * @param session The current resolver session. Must not be {@code null}. 111 * @param args The coerced arguments. Size is in {@code [minArity(), maxArity()]}. Each 112 * element is the type the function expects per its signature; for variadic / 113 * {@code Object}-typed slots, elements remain {@link String}. 114 * @return The function's result as a {@link String}. May be empty but should not be 115 * {@code null} (the runtime treats {@code null} as the empty string for SVL output). 116 */ 117 String invoke(VarResolverSession session, List<Object> args); 118 119 /** 120 * Typed variant of {@link #invoke(VarResolverSession, List)} used by <c>#{...}</c> expressions. 121 * 122 * <p> 123 * The default delegates to {@link #invoke(VarResolverSession, List)}. 124 * 125 * @param session The session. 126 * @param args The already-evaluated arguments (typed values, not necessarily strings). 127 * @return The result; <jk>null</jk> means absent. 128 * @throws Exception Function-specific failure. 129 */ 130 @SuppressWarnings({ 131 "java:S112" // Functions may fail with any checked exception; this is the public contract 132 }) 133 default Object invokeValue(VarResolverSession session, List<Object> args) throws Exception { 134 return invoke(session, args); 135 } 136}