View Javadoc
1   package io.jawk.ext;
2   
3   /*-
4    * ╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲
5    * Jawk
6    * ჻჻჻჻჻჻
7    * Copyright (C) 2006 - 2026 MetricsHub
8    * ჻჻჻჻჻჻
9    * This program is free software: you can redistribute it and/or modify
10   * it under the terms of the GNU Lesser General Public License as
11   * published by the Free Software Foundation, either version 3 of the
12   * License, or (at your option) any later version.
13   *
14   * This program is distributed in the hope that it will be useful,
15   * but WITHOUT ANY WARRANTY; without even the implied warranty of
16   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17   * GNU General Lesser Public License for more details.
18   *
19   * You should have received a copy of the GNU General Lesser Public
20   * License along with this program.  If not, see
21   * <http://www.gnu.org/licenses/lgpl-3.0.html>.
22   * ╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱
23   */
24  
25  import java.io.IOException;
26  import java.io.ObjectInputStream;
27  import java.io.Serializable;
28  import java.lang.annotation.Annotation;
29  import java.lang.reflect.Array;
30  import java.lang.reflect.InvocationTargetException;
31  import java.lang.reflect.Method;
32  import java.lang.reflect.Parameter;
33  import java.util.ArrayList;
34  import java.util.Arrays;
35  import java.util.List;
36  import java.util.Map;
37  import java.util.Objects;
38  
39  import io.jawk.ext.annotations.JawkAssocArray;
40  import io.jawk.ext.annotations.JawkFunction;
41  import io.jawk.ext.annotations.JawkOptional;
42  import io.jawk.ext.annotations.JawkRawValue;
43  import io.jawk.ext.annotations.JawkRegexp;
44  import io.jawk.jrt.AssocArray;
45  import io.jawk.jrt.IllegalAwkArgumentException;
46  
47  /**
48   * Metadata describing a single annotated extension function.
49   */
50  public final class ExtensionFunction implements Serializable {
51  
52  	private static final long serialVersionUID = 1L;
53  
54  	/** AWK-visible keyword that dispatches to the underlying Java method. */
55  	private final String keyword;
56  
57  	/** Extension type declaring the Java implementation method. */
58  	private final Class<? extends AbstractExtension> declaringType;
59  
60  	/** Name of the Java method used when rehydrating serialized metadata. */
61  	private final String methodName;
62  
63  	/** Java parameter types of the extension method. */
64  	private final Class<?>[] parameterTypes;
65  	private transient Method method;
66  
67  	/** Flags describing which parameters must receive associative arrays. */
68  	private final boolean[] assocArrayParameters;
69  
70  	/** Whether the underlying Java method accepts varargs. */
71  	private final boolean varArgs;
72  
73  	/** Number of non-vararg parameters that must always be present. */
74  	private final int mandatoryParameterCount;
75  
76  	/** Whether the vararg component type must be an associative array. */
77  	private final boolean varArgAssocArray;
78  
79  	/**
80  	 * Explicit AWK argument positions that need raw, non-coercing evaluation.
81  	 * Transient: annotation-derived metadata is recomputed from the resolved
82  	 * {@link Method} after deserialization so that tuples files written by other
83  	 * Jawk versions stay loadable.
84  	 */
85  	private transient int[] rawValueParameterIndexes;
86  
87  	/** AWK argument positions where regexp literals keep their precompiled pattern. */
88  	private transient int[] regexpParameterIndexes;
89  
90  	ExtensionFunction(String keywordParam, Method methodParam) {
91  		this.keyword = validateKeyword(keywordParam, methodParam);
92  		this.declaringType = resolveDeclaringType(methodParam);
93  		this.methodName = methodParam.getName();
94  		this.parameterTypes = methodParam.getParameterTypes();
95  		this.method = prepareMethod(methodParam);
96  		this.varArgs = methodParam.isVarArgs();
97  		this.assocArrayParameters = inspectParameters(methodParam, methodParam.getParameters());
98  		int optionalCount = scanOptionalParameterCount(methodParam, methodParam.getParameters());
99  		this.mandatoryParameterCount = varArgs ?
100 				assocArrayParameters.length - 1 :
101 				assocArrayParameters.length - optionalCount;
102 		this.varArgAssocArray = varArgs && assocArrayParameters[assocArrayParameters.length - 1];
103 		computeAnnotationMetadata(methodParam);
104 	}
105 
106 	/**
107 	 * Derives the argument-position metadata from the method's annotations.
108 	 * Called from the constructor and again after deserialization, because this
109 	 * metadata belongs to the class loaded in the current JVM, not to the
110 	 * serialized stream.
111 	 */
112 	private void computeAnnotationMetadata(Method methodParam) {
113 		this.rawValueParameterIndexes = scanObjectParameterIndexes(
114 				methodParam,
115 				methodParam.getParameters(),
116 				JawkRawValue.class);
117 		this.regexpParameterIndexes = scanObjectParameterIndexes(
118 				methodParam,
119 				methodParam.getParameters(),
120 				JawkRegexp.class);
121 	}
122 
123 	/*
124 	 * Optional parameters let a fixed-signature method accept a shorter AWK
125 	 * argument list; missing trailing arguments are passed as null. They must be
126 	 * trailing and cannot be combined with varargs.
127 	 */
128 	private static int scanOptionalParameterCount(Method methodParam, Parameter[] parameters) {
129 		int optionalCount = 0;
130 		for (Parameter parameter : parameters) {
131 			if (parameter.isAnnotationPresent(JawkOptional.class)) {
132 				if (methodParam.isVarArgs()) {
133 					throw new IllegalStateException(
134 							"@" + JawkOptional.class.getSimpleName() + " cannot be combined with varargs: "
135 									+ methodParam.toGenericString());
136 				}
137 				optionalCount++;
138 			} else if (optionalCount > 0) {
139 				throw new IllegalStateException(
140 						"@" + JawkOptional.class.getSimpleName() + " parameters must be trailing: "
141 								+ methodParam.toGenericString());
142 			}
143 		}
144 		return optionalCount;
145 	}
146 
147 	private static String validateKeyword(String keyword, Method method) {
148 		Objects.requireNonNull(method, "method");
149 		if (keyword == null || keyword.trim().isEmpty()) {
150 			throw new IllegalStateException(
151 					"@" + JawkFunction.class.getSimpleName() + " on " + method + " must declare a non-empty name");
152 		}
153 		return keyword;
154 	}
155 
156 	private static Class<? extends AbstractExtension> resolveDeclaringType(Method method) {
157 		Class<?> declaringClass = method.getDeclaringClass();
158 		if (!AbstractExtension.class.isAssignableFrom(declaringClass)) {
159 			throw new IllegalStateException(
160 					"@" + JawkFunction.class.getSimpleName() + " must be declared on a subclass of "
161 							+ AbstractExtension.class.getName() + ": " + method);
162 		}
163 		@SuppressWarnings("unchecked")
164 		Class<? extends AbstractExtension> type = (Class<? extends AbstractExtension>) declaringClass;
165 		return type;
166 	}
167 
168 	private static Method prepareMethod(Method method) {
169 		if (java.lang.reflect.Modifier.isStatic(method.getModifiers())) {
170 			throw new IllegalStateException(
171 					"@" + JawkFunction.class.getSimpleName() + " does not support static methods: " + method.toGenericString());
172 		}
173 		method.setAccessible(true);
174 		return method;
175 	}
176 
177 	/*
178 	 * Raw-value and regexp markers change how the compiler evaluates the matching
179 	 * AWK argument, so the annotated Java parameter must be able to receive any
180 	 * runtime value (Pattern, Map, untyped placeholders, ...): plain Object.
181 	 */
182 	private static int[] scanObjectParameterIndexes(
183 			Method methodParam,
184 			Parameter[] parameters,
185 			Class<? extends Annotation> annotationType) {
186 		int count = 0;
187 		int[] indexes = new int[parameters.length];
188 		for (int idx = 0; idx < parameters.length; idx++) {
189 			Parameter parameter = parameters[idx];
190 			if (!parameter.isAnnotationPresent(annotationType)) {
191 				continue;
192 			}
193 			if (parameter.isVarArgs() || parameter.getType() != Object.class) {
194 				throw new IllegalStateException(
195 						"Parameter " + idx + " of " + methodParam + " annotated with @" + annotationType.getSimpleName()
196 								+ " must be a non-vararg " + Object.class.getName());
197 			}
198 			indexes[count++] = idx;
199 		}
200 		return Arrays.copyOf(indexes, count);
201 	}
202 
203 	/**
204 	 * Inspects the declared Java parameters and records which ones are annotated
205 	 * with {@link JawkAssocArray}.
206 	 * <p>
207 	 * The validation is intentionally stricter than checking
208 	 * {@code Map.class.isAssignableFrom(parameterType)} alone. Jawk passes runtime
209 	 * associative arrays as {@link AssocArray} instances, so the declared parameter
210 	 * type must satisfy two constraints:
211 	 * </p>
212 	 * <ul>
213 	 * <li>it must be a {@link Map} type, because {@code @JawkAssocArray} is a
214 	 * map-shaped contract for extension authors</li>
215 	 * <li>it must also be able to receive an {@link AssocArray} instance at
216 	 * invocation time</li>
217 	 * </ul>
218 	 * <p>
219 	 * That second constraint rejects concrete map implementations such as
220 	 * {@link java.util.HashMap}. A declaration like
221 	 * {@code @JawkAssocArray HashMap<Object, Object>} is map-shaped, but it is not
222 	 * compatible with the {@link AssocArray} values that Jawk actually passes, so
223 	 * letting it register here would only defer the failure until reflective
224 	 * invocation.
225 	 * </p>
226 	 *
227 	 * @param methodParam method whose parameters are being inspected
228 	 * @param parameters declared parameters of {@code methodParam}
229 	 * @return flags indicating which parameter positions require associative arrays
230 	 * @throws IllegalStateException when an annotated parameter cannot receive the
231 	 *         runtime {@link AssocArray} values provided by Jawk
232 	 */
233 	private boolean[] inspectParameters(Method methodParam, Parameter[] parameters) {
234 		boolean[] assoc = new boolean[parameters.length];
235 		for (int idx = 0; idx < parameters.length; idx++) {
236 			Parameter parameter = parameters[idx];
237 			if (parameter.isAnnotationPresent(JawkAssocArray.class)) {
238 				Class<?> parameterType = parameter.getType();
239 				if (parameter.isVarArgs()) {
240 					parameterType = parameterType.getComponentType();
241 				}
242 				if (!Map.class.isAssignableFrom(parameterType) || !parameterType.isAssignableFrom(AssocArray.class)) {
243 					throw new IllegalStateException(
244 							"Parameter " + idx + " of " + methodParam + " annotated with @" + JawkAssocArray.class.getSimpleName()
245 									+ " must accept " + AssocArray.class.getName() + " instances via " + Map.class.getName());
246 				}
247 				assoc[idx] = true;
248 			}
249 		}
250 		return assoc;
251 	}
252 
253 	/**
254 	 * Restores the reflective {@link Method} handle after Java deserialization.
255 	 *
256 	 * @param in Object stream containing the serialized metadata
257 	 * @throws IOException If the stream cannot be read
258 	 * @throws ClassNotFoundException If a serialized dependency cannot be resolved
259 	 */
260 	private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
261 		in.defaultReadObject();
262 		try {
263 			Method resolved = declaringType.getDeclaredMethod(methodName, parameterTypes);
264 			this.method = prepareMethod(resolved);
265 			computeAnnotationMetadata(resolved);
266 		} catch (NoSuchMethodException ex) {
267 			throw new IllegalStateException(
268 					"Unable to rehydrate extension method '" + methodName + "' on type " + declaringType.getName(),
269 					ex);
270 		}
271 	}
272 
273 	/**
274 	 * Returns the Awk keyword mapped to this extension function.
275 	 *
276 	 * @return the keyword exposed by the annotated method
277 	 */
278 	public String getKeyword() {
279 		return keyword;
280 	}
281 
282 	/**
283 	 * Returns the extension type that declares the underlying Java method.
284 	 *
285 	 * @return declaring {@link AbstractExtension} subtype
286 	 */
287 	public Class<? extends AbstractExtension> getDeclaringType() {
288 		return declaringType;
289 	}
290 
291 	/**
292 	 * Returns the fully-qualified class name of the declaring extension.
293 	 *
294 	 * @return extension class name
295 	 */
296 	public String getExtensionClassName() {
297 		return declaringType.getName();
298 	}
299 
300 	/**
301 	 * Returns the minimum number of arguments required to invoke the function.
302 	 *
303 	 * @return required argument count before considering varargs
304 	 */
305 	public int getArity() {
306 		return mandatoryParameterCount;
307 	}
308 
309 	/**
310 	 * Indicates whether the parameter at the supplied index must be an associative
311 	 * array.
312 	 *
313 	 * @param index zero-based parameter index
314 	 * @return {@code true} when the parameter must be an associative array
315 	 * @throws IndexOutOfBoundsException when the index exceeds the parameter count
316 	 */
317 	public boolean expectsAssocArray(int index) {
318 		if (index < 0 || index >= assocArrayParameters.length) {
319 			throw new IndexOutOfBoundsException("Parameter index out of range: " + index);
320 		}
321 		return assocArrayParameters[index];
322 	}
323 
324 	/**
325 	 * Collects the indexes of arguments that must be associative arrays for a call
326 	 * with the supplied argument count. Vararg positions are included when the
327 	 * vararg parameter requires associative arrays.
328 	 *
329 	 * @param argCount number of arguments supplied by the caller
330 	 * @return indexes of arguments that must be associative arrays
331 	 */
332 	public int[] collectAssocArrayIndexes(int argCount) {
333 		verifyArgCount(argCount);
334 		List<Integer> indexes = new ArrayList<Integer>();
335 		int upperBound = Math.min(argCount, declaredParameterUpperBound());
336 		for (int idx = 0; idx < upperBound; idx++) {
337 			if (assocArrayParameters[idx]) {
338 				indexes.add(Integer.valueOf(idx));
339 			}
340 		}
341 		if (varArgs && varArgAssocArray) {
342 			for (int idx = mandatoryParameterCount; idx < argCount; idx++) {
343 				indexes.add(Integer.valueOf(idx));
344 			}
345 		}
346 		int[] result = new int[indexes.size()];
347 		for (int idx = 0; idx < indexes.size(); idx++) {
348 			result[idx] = indexes.get(idx).intValue();
349 		}
350 		return result;
351 	}
352 
353 	/** Highest exclusive index of the declared (non-vararg) parameters. */
354 	private int declaredParameterUpperBound() {
355 		return varArgs ? mandatoryParameterCount : parameterTypes.length;
356 	}
357 
358 	/**
359 	 * Collects the indexes of arguments that should be evaluated without
360 	 * autoconverting untyped values to assigned scalar blanks.
361 	 *
362 	 * @param argCount number of arguments supplied by the caller
363 	 * @return indexes requiring raw value evaluation
364 	 */
365 	public int[] collectRawValueIndexes(int argCount) {
366 		verifyArgCount(argCount);
367 		return Arrays.stream(rawValueParameterIndexes).filter(idx -> idx < argCount).toArray();
368 	}
369 
370 	/**
371 	 * Collects the indexes of arguments where a regexp literal keeps its
372 	 * precompiled pattern instead of being evaluated as {@code $0 ~ /re/}.
373 	 *
374 	 * @param argCount number of arguments supplied by the caller
375 	 * @return indexes keeping regexp literals raw
376 	 */
377 	public int[] collectRegexpIndexes(int argCount) {
378 		verifyArgCount(argCount);
379 		return Arrays.stream(regexpParameterIndexes).filter(idx -> idx < argCount).toArray();
380 	}
381 
382 	/**
383 	 * Invokes the underlying Java method on the supplied target instance.
384 	 *
385 	 * @param target extension instance to receive the call
386 	 * @param args arguments evaluated by the interpreter
387 	 * @return result of the Java invocation
388 	 * @throws IllegalAwkArgumentException when the arguments violate the metadata
389 	 * @throws IllegalStateException when reflection cannot invoke the method
390 	 */
391 	public Object invoke(AbstractExtension target, Object[] args) {
392 		Objects.requireNonNull(target, "target");
393 		if (!declaringType.isInstance(target)) {
394 			throw new IllegalArgumentException(
395 					"Extension instance " + target.getClass().getName() + " is not compatible with " + declaringType.getName());
396 		}
397 		int argCount = args == null ? 0 : args.length;
398 		verifyArgCount(argCount);
399 		enforceAssocArrayParameters(args);
400 		Object[] invocationArgs = prepareArguments(args);
401 		try {
402 			return method.invoke(target, invocationArgs);
403 		} catch (IllegalAccessException ex) {
404 			throw new IllegalStateException("Unable to access extension function method for keyword '" + keyword + "'", ex);
405 		} catch (InvocationTargetException ex) {
406 			Throwable cause = ex.getCause();
407 			if (cause instanceof RuntimeException) {
408 				throw (RuntimeException) cause;
409 			}
410 			if (cause instanceof Error) {
411 				throw (Error) cause;
412 			}
413 			throw new IllegalStateException("Invocation of extension function '" + keyword + "' failed", cause);
414 		}
415 	}
416 
417 	private Object[] prepareArguments(Object[] args) {
418 		int argCount = args == null ? 0 : args.length;
419 		if (!varArgs) {
420 			// Omitted optional trailing arguments are passed as null
421 			Object[] invocationArgs = new Object[parameterTypes.length];
422 			if (argCount > 0) {
423 				System.arraycopy(args, 0, invocationArgs, 0, argCount);
424 			}
425 			return invocationArgs;
426 		}
427 		if (argCount == 0) {
428 			return new Object[] { Array.newInstance(parameterTypes[parameterTypes.length - 1].getComponentType(), 0) };
429 		}
430 		Object[] invocationArgs = new Object[mandatoryParameterCount + 1];
431 		for (int idx = 0; idx < mandatoryParameterCount; idx++) {
432 			invocationArgs[idx] = args[idx];
433 		}
434 		int varArgCount = argCount - mandatoryParameterCount;
435 		Class<?> componentType = parameterTypes[parameterTypes.length - 1].getComponentType();
436 		Object varArgArray = Array.newInstance(componentType, varArgCount);
437 		for (int idx = 0; idx < varArgCount; idx++) {
438 			Array.set(varArgArray, idx, args[mandatoryParameterCount + idx]);
439 		}
440 		invocationArgs[mandatoryParameterCount] = varArgArray;
441 		return invocationArgs;
442 	}
443 
444 	/**
445 	 * Verifies that the provided argument count satisfies the arity constraints
446 	 * encoded in the metadata.
447 	 *
448 	 * @param argCount number of arguments the caller supplied
449 	 * @throws IllegalAwkArgumentException when the count violates the signature
450 	 */
451 	public void verifyArgCount(int argCount) {
452 		if (!varArgs) {
453 			int maxCount = parameterTypes.length;
454 			if (argCount < mandatoryParameterCount || argCount > maxCount) {
455 				String expected = mandatoryParameterCount == maxCount ?
456 						String.valueOf(maxCount) :
457 						mandatoryParameterCount + " to " + maxCount;
458 				throw new IllegalAwkArgumentException(
459 						"Extension function '" + keyword + "' expects " + expected + " argument(s), not " + argCount);
460 			}
461 			return;
462 		}
463 		if (argCount < mandatoryParameterCount) {
464 			throw new IllegalAwkArgumentException(
465 					"Extension function '" + keyword + "' expects " + getArity() + " argument(s), not " + argCount);
466 		}
467 	}
468 
469 	private void enforceAssocArrayParameters(Object[] args) {
470 		if (args == null) {
471 			return;
472 		}
473 		int argCount = args.length;
474 		int upperBound = Math.min(argCount, declaredParameterUpperBound());
475 		for (int idx = 0; idx < upperBound; idx++) {
476 			if (assocArrayParameters[idx]) {
477 				requireAssocArray(idx, args[idx]);
478 			}
479 		}
480 		if (varArgs && varArgAssocArray) {
481 			for (int idx = mandatoryParameterCount; idx < argCount; idx++) {
482 				requireAssocArray(idx, args[idx]);
483 			}
484 		}
485 	}
486 
487 	private void requireAssocArray(int idx, Object arg) {
488 		if (!(arg instanceof Map)) {
489 			throw new IllegalAwkArgumentException(
490 					"Argument " + idx + " passed to extension function '" + keyword + "' must be an associative array");
491 		}
492 	}
493 }