1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.jexl3.introspection;
19 import org.apache.commons.jexl3.JexlException;
20
21 /**
22 * Interface used for regular method invocation.
23 * Ex.
24 * <code>
25 * ${foo.bar()}
26 * </code>
27 *
28 * @since 1.0
29 */
30 public interface JexlMethod {
31 /**
32 * returns the return type of the method invoked.
33 *
34 * @return return type
35 */
36 Class<?> getReturnType();
37
38 /**
39 * Invocation method, called when the method invocation should be performed
40 * and a value returned.
41
42 * @param obj the object
43 * @param params method parameters.
44 * @return the result
45 * @throws Exception on any error.
46 */
47 Object invoke(Object obj, Object... params) throws Exception;
48
49 /**
50 * Specifies if this JexlMethod is cacheable and able to be reused for this
51 * class of object it was returned for.
52 *
53 * @return true if can be reused for this class, false if not
54 */
55 boolean isCacheable();
56
57 /**
58 * Checks whether a tryInvoke return value indicates a failure or not.
59 * <p>Usage is : <code>Object r = tryInvoke(...); if (tryFailed(r) {...} else {...}</code>
60 *
61 * @param rval the value returned by tryInvoke
62 * @return true if tryInvoke failed, false otherwise
63 */
64 boolean tryFailed(Object rval);
65
66 /**
67 * Attempts to reuse this JexlMethod, checking that it is compatible with
68 * the actual set of arguments.
69 * Related to isCacheable since this method is often used with cached JexlMethod instances.
70 *
71 * @param name the method name
72 * @param obj the object to invoke the method upon
73 * @param params the method arguments
74 * @return the result of the method invocation that should be checked by tryFailed to determine if it succeeded
75 * or failed.
76 * @throws JexlException.TryFailed if the underlying method was invoked but threw an exception
77 * ({@link java.lang.reflect.InvocationTargetException})
78 */
79 Object tryInvoke(String name, Object obj, Object... params) throws JexlException.TryFailed;
80 }