public class CallbackResolver
extends java.lang.Object
Callback
object. Each callback is
stored in a dictionary and can be found by a literal match with a function
name or can be optionally matched with a set of valid function name
abbreviations.
The namespace for the dictionary is flat. For one function name that is
matched in the resolver dictionary, there is only one Callback
object that can be found. This means that any features that are coded
in a callback definition must be implemented the same way for all target
methods. This is especially important when overloading function names.
Limitations on function overloading:
null
it is static, otherwise it is used as the
instance for the method call.
addCallback(Keyword,Object,Method)
method
since this hardcodes the Method
object to be used
for the invocation. In this case, the same exact method will
*always* by invoked.
addCallback(Keyword,Object,String,String)
method. This delays the resolution of the Method
object until lookupCallback(java.lang.String)
is invoked
which is the time at which the proper signature is known. Each
time the lookup is done, the signature that is passed in is used
to resolve to the correct target method with the same name as
that coded in the callback definition.
Keyword
object that
can be found and this single object can have only 1 associated
target method name. This single method name must have 1 signature
for every match to a valid signature that will be found in the
Progress function call.
invokeCallback
method reads a callback definition and then
calculates and uses some information from it. There is an inherent
race condition in between obtaining and using this callback information.Modifier and Type | Field and Description |
---|---|
private KeywordDictionary |
kwDict
Stores the set of all
Keywords with each keyword
corresponding to a specific Callback object. |
Constructor and Description |
---|
CallbackResolver()
Default constructor which instantiates a
CallbackResolver
object which matches on a case-insensitive basis. |
CallbackResolver(boolean matchCase)
Instantiates a
CallbackResolver object. |
Modifier and Type | Method and Description |
---|---|
void |
addCallback(Keyword word,
java.lang.Object instance,
java.lang.reflect.Method method)
Creates a
object using the
Callback.Callback(Object,Method) constructor and then
stores this instance in the Keyword object and adds this
associated Keyword object to the dictionary. |
void |
addCallback(Keyword word,
java.lang.Object instance,
java.lang.String className,
java.lang.String methodName)
Creates a
object using the
Callback.Callback(Object,String,String) constructor and then
stores this instance in the Keyword object and adds this
associated Keyword object to the dictionary. |
void |
dump()
Prints a report to
stderr which includes 1 line per
entry in the dictionary. |
java.lang.Object |
invokeCallback(java.lang.String funcName,
java.lang.Class returnType,
java.lang.Class[] signature,
java.lang.Object[] args)
Lookup the callback definition associated with the function name and
invoke the target method using the passed arguments.
|
Callback |
lookupCallback(java.lang.String funcName)
Processes a dictionary lookup for a specified
Callback . |
(package private) void |
populateSymbolResolver(SymbolResolver sym)
The Lexer and Parser that processes an expression must be aware of the
same
Keyword objects as this instance. |
private KeywordDictionary kwDict
Keywords
with each keyword
corresponding to a specific Callback
object.public CallbackResolver()
CallbackResolver
object which matches on a case-insensitive basis.public CallbackResolver(boolean matchCase)
CallbackResolver
object.matchCase
- Controls lookup algorithm case-sensitivity.public void addCallback(Keyword word, java.lang.Object instance, java.lang.String className, java.lang.String methodName)
Callback
object using the
Callback.Callback(Object,String,String)
constructor and then
stores this instance in the Keyword
object and adds this
associated Keyword
object to the dictionary.
This method MUST be used to add an overloaded function to the dictionary, since this is the only way to add a callback definition in which the signature of the target is NOT hard coded.
word
- Keyword object to add. Must not be null
.instance
- Target object on which to invoke the callback or
null
if the method is static.className
- Fully qualified class name of the target object's class.
Must not be null
.methodName
- Method name of the method to invoke on the target object.
Use null
or an empty string to specify a
constructor.public void addCallback(Keyword word, java.lang.Object instance, java.lang.reflect.Method method)
Callback
object using the
Callback.Callback(Object,Method)
constructor and then
stores this instance in the Keyword
object and adds this
associated Keyword
object to the dictionary.
This method CANNOT be used to add an overloaded function to the
dictionary, since the signature of the target is hard coded into the
Method
object. Use
instead.addCallback(Keyword,Object,String,String)
word
- Keyword object to add.instance
- Target object on which to invoke the callback or null if the
method is static.method
- Method object which can be used to invoke the target
method via reflection.public Callback lookupCallback(java.lang.String funcName)
Callback
.
If a match is found, the associated Callback
object is
returned. Otherwise null
is returned.
funcName
- The function name to be used as a key in the lookup. If case-
sensitivity is off, this may be in any case (including
mixed case) and the result will always match.Callback
object or null if no match was found.public java.lang.Object invokeCallback(java.lang.String funcName, java.lang.Class returnType, java.lang.Class[] signature, java.lang.Object[] args) throws java.lang.ClassNotFoundException, java.lang.NoSuchMethodException, java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.InstantiationException, java.lang.NullPointerException
The lookup function will find the callback definition, if it exists.
Once obtained, the Callback.getMethod
will be called. If
it returns a valid Method
object then the caller-passed
arguments are *not* checked and this Method
is used. For
this reason function overloading cannot be used when the callback
definition has a hard-coded Method
object and no class
and method names encoded.
If Callback.getMethod()
is called and the method is
null
, then the reflection services are used to obtain a
java.lang.reflect.Method
object based on the class name,
method name and the signature definition passed in as a parameter by
the caller.
Once the Method
is obtained, reflection is used to invoke
that method and the arguments array is passed.
NO caching of the Method
object is done at the time of
a lookup. This allows one to code a callback definition using only
the class and method names and then to defer all signature processing
until this lookup method is called. In this case, the signature
passed into the lookup is used to resolve the target method using
reflection and if the correct method exists it will be found.
funcName
- The function name to be used as a key in the lookup. If case-
sensitivity is off, this may be in any case (including
mixed case) and the result will always match.returnType
- The Class
object representing the class of the
method's return type.signature
- An array of Class
objects representing the class
of each parameter in addition to the sequence of the
parameters.args
- An array of Object
objects representing each
parameter in the proper sequence expected by the target
method.java.lang.ClassNotFoundException
java.lang.NoSuchMethodException
java.lang.IllegalAccessException
java.lang.reflect.InvocationTargetException
java.lang.InstantiationException
java.lang.NullPointerException
public void dump()
stderr
which includes 1 line per
entry in the dictionary. If a Callback
object has an
associated Keyword
that supports abbreviations, then
multiple entries will be found that refer to the same
Keyword
.void populateSymbolResolver(SymbolResolver sym)
Keyword
objects as this instance. This helper method
obtains the list of Keyword
objects from the keyword
dictionary and adds each to the SymbolResolver
to
properly populate it.sym
- Object to populate with full list of Keywords
.