01: /*
02:
03: This software is OSI Certified Open Source Software.
04: OSI Certified is a certification mark of the Open Source Initiative.
05:
06: The license (Mozilla version 1.0) can be read at the MMBase site.
07: See http://www.MMBase.org/license
08:
09: */
10: package org.mmbase.util.functions;
11:
12: import java.util.*;
13:
14: /**
15: * A representation of a piece of functionality (a 'function'). A function has a name, a
16: * return type, and a parameter-definition (which is a {@link Parameter} array).
17: *
18: * The goal of a Function object is to call its {@link #getFunctionValue(Parameters)} method, which
19: * executes it, given the specified parameters.
20: *
21: * @author Pierre van Rooden
22: * @author Daniel Ockeloen
23: * @author Michiel Meeuwissen
24: * @version $Id: Function.java,v 1.10 2006/09/27 20:42:21 michiel Exp $
25: * @since MMBase-1.7
26: * @see Parameter
27: * @see Parameters
28: */
29: public interface Function<R> {
30: /**
31: * Creates an empty 'Parameters' object for you, which you have to fill and feed back to getFunctionValue
32: * @see #getFunctionValue(Parameters)
33: */
34: public Parameters createParameters();
35:
36: /**
37: * Executes the defined function supplying the given arguments.
38: * @see #createParameters
39: * @param parameters The parameters for the function. To specify an empty parameter list use {@link Parameters#VOID}.
40: * Implementors are encouraged to support <code>null</code> too.
41: * @return The function value, which can be of any type compatible to {@link #getReturnType}
42: */
43: public R getFunctionValue(Parameters parameters);
44:
45: /**
46: * Executes the defined function supplying the given List of arguments.
47: * This is a convenience method, as the List is mapped to a Parameters type and passed to {@link #getFunctionValue(Parameters)}.
48: * @param parameters The parameters for the function. To specify an empty parameter list use {@link Parameters#VOID}.
49: *
50: * @return The function value, which can be of any type compatible to {@link #getReturnType}
51: */
52: public R getFunctionValueWithList(List<?> parameters);
53:
54: /**
55: * @since MMBase-1.9
56: */
57: public R getFunctionValue(Object... parameters);
58:
59: /**
60: * For documentational purposes a function object needs a description too.
61: */
62: public void setDescription(String description);
63:
64: /**
65: * @see #setDescription(String)
66: */
67: public String getDescription();
68:
69: /**
70: * A function <em>must</em> have a name. This is the name which was used to aquire the function object.
71: * @return The function's name, never <code>null</code>
72: */
73: public String getName();
74:
75: /**
76: * @return The currently set Parameter definition array, or <code>null</code> if not set already.
77: */
78: public Parameter<?>[] getParameterDefinition();
79:
80: /**
81: * A function object is of no use, as long as it lacks a definition.
82: * @param params An array of Parameter objects.
83: * @throws IllegalStateException if there was already set a parameter definition for this function object.
84: */
85: public void setParameterDefinition(Parameter<?>[] params);
86:
87: /**
88: * @return The return type of the function's result value, or <code>null</code> if unknown.
89: */
90: public ReturnType<R> getReturnType();
91:
92: /**
93: * Sets the return type of the function's result value.
94: * @param type A ReturnType object. For void functions that could be {@link ReturnType#VOID}.
95: * @throws IllegalStateException if there was already set a return type for this function object.
96: */
97: public void setReturnType(ReturnType<R> type);
98:
99: }
|