ovm.polyd.policy
Class Dispatching

java.lang.Object
  extended by ovm.polyd.policy.Dispatching
Direct Known Subclasses:
MultiDisp, NonSubsump, Overloading

public abstract class Dispatching
extends java.lang.Object

The common superclass of all dispatching policies.

The methods defined in this class can be overridden in order to create user-defined dispatching policies. Please check out the invidual methods below to know more.


Method Summary
 int bestMatch(java.lang.Class[] args, java.lang.reflect.Method[] meth)
          Dynamically selects the most appropriate method for a certain combination of arguments.
 int bestMatch(java.lang.Class[] args, java.lang.reflect.Method[] meth, java.lang.Object[] raws, java.lang.Class[] implems, java.lang.reflect.Method proto, java.lang.String name)
          Dynamically selects the most appropriate method for a certain combination of arguments.
 java.lang.reflect.Method[] compatibleSet(java.lang.Class[] args, java.lang.reflect.Method[] meth)
          Performs a static preselection on a set of methods, and/or a consistency check.
 java.lang.reflect.Method[] compatibleSet(java.lang.Class[] args, java.lang.reflect.Method[] meth, java.lang.Class[] implems, java.lang.reflect.Method proto, java.lang.String name)
          Performs a static preselection on a set of methods, and/or a consistency check.
 boolean disableCaching()
          Disables method caching for this policy.
 boolean handleMissing(java.lang.Class[] args, java.lang.reflect.Method[] meth)
          Handles messages which cannot be dispatched to any method, according to the current dispatching policy.
 boolean handleMissing(java.lang.Class[] args, java.lang.reflect.Method[] meth, java.lang.Object[] raws, java.lang.Class[] implems, java.lang.reflect.Method proto, java.lang.String name)
          Handles messages which cannot be dispatched to any method, according to the current dispatching policy.
 java.lang.Class[] remapNull(java.lang.Class[] args, java.lang.reflect.Method[] meth)
          Remaps the arguments when an unexpected null argument is encountered.
 java.lang.Object[][] remapNull(java.lang.Class[] args, java.lang.reflect.Method[] meth, java.lang.Object[] raws, java.lang.Class[] implems, java.lang.reflect.Method proto, java.lang.String name)
          Remaps the arguments when an unexpected null argument is encountered.
static Dispatching theDispatcher()
          Returns an instance of this dispatching policy.
 java.lang.String toString()
          Returns the name of this dispatcher
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

theDispatcher

public static Dispatching theDispatcher()
Returns an instance of this dispatching policy.

This method must be defined in every user-defined dispatching policy. It must return one instance of the same class, normally a singleton allocated during construction. This method is used reflexively to allow access to the fields and methods of the class given the class name.

Returns:
an instance of this class (a singleton)

remapNull

public java.lang.Object[][] remapNull(java.lang.Class[] args,
                                      java.lang.reflect.Method[] meth,
                                      java.lang.Object[] raws,
                                      java.lang.Class[] implems,
                                      java.lang.reflect.Method proto,
                                      java.lang.String name)
Remaps the arguments when an unexpected null argument is encountered. If an argument is null, and it is not caught by @IfNull, find a suitable alternative combination of classes here.

Define this method if you would like to be able to handle null arguments in a more general form with respect to what is allowed by @IfNull tags. While @IfNull operate on individual arguments, this method can be used to alter the interpretation of all the arguments together when one of them is unexpectedly null.

As an alternative to this general method, you can use the simpler form remapNull(Class[], Method[]). If both are overridden, the most general form will be used. For maximum efficiency, do not override remapNull, but use the simpler @IfNull tag instead.

Parameters:
args - the array of classes of non-raw arguments
meth - the array of methods that will be used for the selection
raws - the array of raw arguments
implems - the array of implementing bodies
proto - the prototype through which this call was made
name - if the prototype was renamed, this is the new name (otherwise, the same as the prototype)
Returns:
an array containing exactly two elements. The first is the remapped array of classes, the second is the remapped array of raw arguments
See Also:
IfNull

remapNull

public java.lang.Class[] remapNull(java.lang.Class[] args,
                                   java.lang.reflect.Method[] meth)
Remaps the arguments when an unexpected null argument is encountered.

If an argument is null, and it is not caught by @IfNull, find a suitable alternative combination of classes here.

Parameters:
args - the array of classes of non-raw arguments
meth - the array of methods that will be used for the selection
Returns:
the remapped array of classes
See Also:
remapNull(Class[], Method[], Object[], Class[], Method, String)

bestMatch

public int bestMatch(java.lang.Class[] args,
                     java.lang.reflect.Method[] meth,
                     java.lang.Object[] raws,
                     java.lang.Class[] implems,
                     java.lang.reflect.Method proto,
                     java.lang.String name)
Dynamically selects the most appropriate method for a certain combination of arguments.

The most crucial part of a dispatching policy, this method contains the logic required to decide which is the implementing method that better fits a certain calling context. In order to help in the choice, PolyD supplies various bits of information.

It is assumed that the same combination of arguments always leads to the same method being selected. PolyD relies on this property in order to cache the method selection, and you should not assume that bestMatch will be called every time a message is dispatched.

If your particular dispatching policy cannot guarantee that it will select always the same method for a given combination of arguments, or if you absolutely need to make sure that bestMatch will be called every single time a message is dispatched, then you will have to disable caching altogether for this policy, see disableCaching().

If you do not require raw arguments, or the whole set of arguments available to this method, a simpler form can be defined instead, see bestMatch(Class[], Method[]).

Parameters:
args - the array of classes of non-raw arguments
meth - the array of methods involved in the selection
raws - the array of raw arguments
implems - the array of implementing bodies
proto - the prototype through which the message was sent
name - if the prototype was renamed, this is the new name
Returns:
the index of the best applicable method in the meth array, or -1 if none can be chosen.

bestMatch

public int bestMatch(java.lang.Class[] args,
                     java.lang.reflect.Method[] meth)
Dynamically selects the most appropriate method for a certain combination of arguments.

Parameters:
args - the array of classes of non-raw arguments
meth - the array of methods involved in the selection
Returns:
the index of the best applicable method in the meth array, or -1 if none can be chosen.
See Also:
bestMatch(Class[], Method[], Object[], Class[], Method, String)

compatibleSet

public java.lang.reflect.Method[] compatibleSet(java.lang.Class[] args,
                                                java.lang.reflect.Method[] meth,
                                                java.lang.Class[] implems,
                                                java.lang.reflect.Method proto,
                                                java.lang.String name)
Performs a static preselection on a set of methods, and/or a consistency check.

Redefine this method if you would like to perform a static analysis on the set of methods that might be called through each prototype defined in the dispatcher interface. The main uses of this method are:

  1. Verifying that the set of methods is internally consistent, for example checking that there are no duplicates or ambiguities.
  2. Performing a static preselection, determining the subset of methods that can really be ever chosen as a result of a message sent through the given prototype.
If an inconsistency is detected, you should throw some sort of PolicyException. Return the applicable subset of meth (or all of it). Redefining this method in a user-defined policy is not mandatory, but it is recommended. It is also possible to define in its place the simpler compatibleSet(Class[], Method[]).

Parameters:
args - the array of classes of non-raw arguments
meth - the array of methods that will be used for the selection
implems - the array of implementing bodies
proto - the prototype through which the methods might be called
name - if the prototype was renamed, this is the new name
Returns:
the selected subset, or meth
See Also:
PolicyException

compatibleSet

public java.lang.reflect.Method[] compatibleSet(java.lang.Class[] args,
                                                java.lang.reflect.Method[] meth)
Performs a static preselection on a set of methods, and/or a consistency check.

Parameters:
args - the array of classes of non-raw arguments
meth - the array of methods that will be used for the selection
Returns:
the selected subset, or meth
See Also:
compatibleSet(Class[], Method[], Class[], Method, String)

handleMissing

public boolean handleMissing(java.lang.Class[] args,
                             java.lang.reflect.Method[] meth,
                             java.lang.Object[] raws,
                             java.lang.Class[] implems,
                             java.lang.reflect.Method proto,
                             java.lang.String name)
Handles messages which cannot be dispatched to any method, according to the current dispatching policy.

This method can take whatever action might be appropriate, including calling further methods. However, it should not throw a MissingMethodException. If no reasonable corrective action can be taken, simply return false to the caller.

An alternative, simpler form of this method is also available, see handleMissing(Class[], Method[]). Redefining remapNull in user-defined policies is not required.

Parameters:
args - the array of classes of non-raw arguments
meth - the array of methods involved in the selection
raws - the array of raw arguments
implems - the array of implementing bodies
proto - the prototype through which the methods might be called
name - if the prototype was renamed, this is the new name
Returns:
true if it was possible to handle the message, false otherwise

handleMissing

public boolean handleMissing(java.lang.Class[] args,
                             java.lang.reflect.Method[] meth)
Handles messages which cannot be dispatched to any method, according to the current dispatching policy.

Parameters:
args - the array of classes of non-raw arguments
meth - the array of methods involved in the selection
Returns:
true if it was possible to handle the message, false otherwise
See Also:
handleMissing(Class[], Method[], Object[], Class[], Method, String)

disableCaching

public boolean disableCaching()
Disables method caching for this policy.

If this method is overridden in your user-defined policy, and it returns true, then the whole caching mechanism offered by PolyD will be disabled for this dispatching policy. As a result, bestMatch will be called each and every time a message is dispatched.

Disabling caching involves a large performance penalty, and should really only be used for those policies for which the method selection depends on external factors and the chosen method may be different from time to time even for the same arguments. Alternatively, disabling caching can sometimes be of use during debugging.

User-defined policies shuld not normally override this method. Note that this method should always return the same value for one given dispatching policy (either always true, or always false).

Returns:
true if method caching must be disabled, false otherwise

toString

public java.lang.String toString()
Returns the name of this dispatcher

Overrides:
toString in class java.lang.Object
Returns:
a string containing the name of the dispatcher