com.webobjects.foundation
Class NSSelector

java.lang.Object
  |
  +--com.webobjects.foundation.NSSelector

All Implemented Interfaces:

Serializable

public class NSSelector

extends Object

implements Serializable

An NSSelector object specifies a method signature (a method's name and parameter list). You can apply a selector on any object, and it performs the method that matches it, if there is one.

NSSelector is very similar to Method. However, java.lang.reflect.Method objects specify a particular class's implementation of a method, and you can only apply them to objects of that class (or subclass). NSSelectors can be used on any object, regardless of class, which has a method name and signature that matches the selector. To find the java.lang.reflect.Method object that matches an NSSelector for a particular object or class, use methodOnObject or methodOnClass

To create a selector, you can use a single-argument constructor or a two-argument constructor. The two-argument constructor takes the method's name and an array of the parameter types. Note that to obtain a Class object for a type, .class is to be appended to the type's name. For example, the Class object for Object is Object.class.

Class properties:

• method: method name
• parameters: parameter types

NSSelector

This code sample creates a selector for the doIt method:

  void doIt(String str,int i){...}

  NSSelector sel =
  new NSSelector("doIt",new Class [] {String.class,Integer.class});
  

To apply a selector on an object, the overloaded instance method invoke is used. It performs the method that matches the selector and returns the result. If the target object doesn't have a method matching the selector, it throws NoSuchMethodException. The most basic form of invoke takes the target object and an Object array of the arguments. Other forms are convenience methods for selectors with no, one, or two arguments. Note that to pass an argument of a primitive type to invoke, an object of the corresponding wrapper class is used. invoke converts the object back to the primitive type when it invokes the method. For example, to pass the float f, new Float(f) is used; and to pass the boolean value true, new Boolean(true) is used.

This code sample gives two ways to apply the selector sel (defined above) to an object:

  MyClass obj1 =new MyClass(),obj2 =new MyClass();
  int i =5;
  sel.invoke(obj1,new Object [] {"hi" ,new Integer(i)});
  sel.invoke(obj2,"bye",new Integer(10));
  

To create and apply a selector in one step, the overloaded static method invoke is used. The basic form takes four arguments: the method name, an array of the parameter types, the target object, and an array of the arguments. Other forms are convenience methods for selectors with one or two arguments. This code sample shows two ways to create and apply a selector for the doIt method:

 void doIt(String str,int i){...}
 MyClass obj1 =new MyClass(),obj2 =new MyClass();
  int i =5;
 NSSelector.invoke("doIt",new Class [] {String.class,Integer.class},
         obj1,new Object [] {{"hi",new Integer(i)});
  NSSelector.invoke("doIt",String.class,Integer.class,
          obj1,"bye",new Integer(10));
  

Other methods return whether an object or class has a method that matches a selector (and implementedByClass) and returns the method name and parameter types for a selector (name and parameterTypes).

See Also:

Method, invoke(Object, Object[]), name(), parameterTypes(), implementedByObject(java.lang.Object), implementedByClass(java.lang.Class), methodOnObject(java.lang.Object), methodOnClass(java.lang.Class), Serialized Form

Constructor Summary

NSSelector(String name)
Creates a selector for a method that takes no parameters.

NSSelector(String name, Class[] parameterTypes)
Creates a new selector for a method that takes arguments.

Method Summary

boolean	equals(Object otherSelector) Determines whether an object is an NSSelector equal to this NSSelector.
int	hashCode()
boolean	implementedByClass(Class targetClass) Indicates whether a class implements the method that this NSSelector specifies.
boolean	implementedByObject(Object target) Indicates whether the target object implements the method that this NSSelector specifies.
Object	invoke(Object target) A convenience method similar to invoke(Object, Object[]), but with no arguments.
Object	invoke(Object target, Object argument) A convenience method similar to invoke(Object, Object[]), but using one argument.
Object	invoke(Object target, Object[] parameters) Invokes the method encapsulated by this NSSelector with parameters on the target object.
Object	invoke(Object target, Object argument1, Object argument2) A convenience method similar to invoke(Object, Object[]), but using two arguments.
static Object	invoke(String name, Class[] parameterTypes, Object target, Object[] parameters) A convenience method that creates an NSSelector for a method that takes any number of arguments, and immediately applies it to the target object.
static Object	invoke(String name, Class parameterType1, Class parameterType2, Object target, Object argument1, Object argument2) A convenience method that creates an NSSelector for a method that two arguments, and immediately applies it to the target object.
static Object	invoke(String name, Class parameterType, Object target, Object argument) A convenience method that creates an NSSelector for a method that one argument, and immediately applies it to the target object.
Method	methodOnClass(Class targetClass) Returns the java.lang.reflect.Method that corresponds to this NSSelector on the targetClass.
Method	methodOnObject(Object target) Returns the java.lang.reflect.Method that corresponds to this NSSelector on the target object.
String	name()
Class[]	parameterTypes() Returns a copy of the array of parameter types specified by this NSSelector.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

NSSelector

public NSSelector(String name)

Creates a selector for a method that takes no parameters.

Parameters:

name - name of the method this NSSelector specifies

NSSelector

public NSSelector(String name,
                  Class[] parameterTypes)

Creates a new selector for a method that takes arguments.

The parameterTypes array can be created easily: Class parameters[] = new Class[] {String.class, Integer.class, Boolean.class}

Parameters:

name - name of the method this NSSelector specifies

parameterTypes - parameter-type list for the method specified by name; null if the method takes no parameters

Method Detail

equals

public boolean equals(Object otherSelector)

Determines whether an object is an NSSelector equal to this NSSelector. Two selectors are equal if their names and parameter types are equal.

Overrides:

equals in class Object

Parameters:

otherSelector - the object to compare this NSSelector against

Returns:

true true when otherSelector is an NSSelector with the same method and parameters as this NSSelector

See Also:

Object.equals(java.lang.Object)

hashCode

public int hashCode()

Overrides:

hashCode in class Object

Returns:

hash code useful for storing this NSSelector in a hash-based data structure

See Also:

Object.hashCode()

implementedByClass

public boolean implementedByClass(Class targetClass)

Indicates whether a class implements the method that this NSSelector specifies.

Parameters:

targetClass - a java.lang.Class object to search

Returns:

true if targetClass implements method/parameters

See Also:

Class

implementedByObject

public boolean implementedByObject(Object target)

Indicates whether the target object implements the method that this NSSelector specifies.

Parameters:

target - object to check

Returns:

true if target implements method/parameters

See Also:

implementedByClass(java.lang.Class), Class

invoke

public Object invoke(Object target,
                     Object[] parameters)
              throws IllegalAccessException,
                     IllegalArgumentException,
                     InvocationTargetException,
                     NoSuchMethodException

Invokes the method encapsulated by this NSSelector with parameters on the target object. Note that the method may be either a static or instance method.

This method can't handle parameters or return values of primitive types (such as boolean, int, or float). If method returns a value of a primitive type, this method returns the value in an object of the corresponding wrapper type (such as Boolean, Integer, or Float). To pass an argument of a primitive type to method, wrap the value in the corresponding wrapper class.

Parameters:

target - object on which to invoke the method corresponding to this selector

parameters - arguments to be used when invoking method on target; null if the method takes no arguments

Returns:

the return value from the method invoked or null if method is void

Throws:

java.lang.refelct.NoSuchMethodException - target has no method that matches method/parameters

IllegalAccessException - a method in target matches method/parameters, but cannot be accessed by target

IllegalArgumentException - this method can't convert an argument to the type specified in parameters

java.lang.InvocationTargetException - method throws an exception (the exception thrown is wrapped in this exception)

See Also:

methodOnClass(java.lang.Class), Method.invoke(java.lang.Object, java.lang.Object[])

invoke

public Object invoke(Object target)
              throws IllegalAccessException,
                     IllegalArgumentException,
                     InvocationTargetException,
                     NoSuchMethodException

A convenience method similar to invoke(Object, Object[]), but with no arguments.

Parameters:

target - object on which to invoke method

Returns:

value returned by method or null if method is void

Throws:

java.lang.refelct.NoSuchMethodException - target has no method that matches method/parameters

IllegalAccessException - a method in target matches method/parameters, but cannot be accessed by target

IllegalArgumentException - this method can't convert an argument to the type specified in parameters

java.lang.InvocationTargetException - method throws an exception (the exception thrown is wrapped in this exception)

See Also:

invoke(Object, Object[])

invoke

public Object invoke(Object target,
                     Object argument)
              throws IllegalAccessException,
                     IllegalArgumentException,
                     InvocationTargetException,
                     NoSuchMethodException

A convenience method similar to invoke(Object, Object[]), but using one argument.

Parameters:

target - object on which to invoke method/parameter

argument - argument to use when invoking method on target

Returns:

value returned by method/parameter or null if method is void

Throws:

java.lang.refelct.NoSuchMethodException - target has no method that matches method/parameters

IllegalAccessException - a method in target matches method/parameters, but cannot be accessed by target

IllegalArgumentException - this method can't convert argument to the type specified in parameters

java.lang.InvocationTargetException - method throws an exception (the exception thrown is wrapped in this exception)

See Also:

invoke(Object, Object[])

invoke

public Object invoke(Object target,
                     Object argument1,
                     Object argument2)
              throws IllegalAccessException,
                     IllegalArgumentException,
                     InvocationTargetException,
                     NoSuchMethodException

A convenience method similar to invoke(Object, Object[]), but using two arguments.

Parameters:

target - object on which to invoke method/parameters

argument1 - first argument to be passed to method

argument2 - second argument to be passed to method

Returns:

value returned by method/parameters or null if method is void

Throws:

java.lang.refelct.NoSuchMethodException - target has no method that matches method/parameters

IllegalAccessException - a method in target matches method/parameters, but cannot be accessed by target

IllegalArgumentException - this method can't convert argument1 or argument2 to the appropriate type, specified in parameters

java.lang.InvocationTargetException - method throws an exception (the exception thrown is wrapped in this exception)

See Also:

invoke(Object, Object[])

invoke

public static Object invoke(String name,
                            Class[] parameterTypes,
                            Object target,
                            Object[] parameters)
                     throws IllegalAccessException,
                            IllegalArgumentException,
                            InvocationTargetException,
                            NoSuchMethodException

A convenience method that creates an NSSelector for a method that takes any number of arguments, and immediately applies it to the target object. Uses the invoke(Object, Object[]) method.

Parameters:

name - name of the new NSSelector's method

parameterTypes - parameter type list for the method specified by name; null if the method takes no arguments

target - object the new NSSelector is applied to

parameters - arguments to be used when invoking the method specified by name on target; null if the method takes no arguments

Returns:

value returned by the method specified in name; null if the method is void

Throws:

java.lang.refelct.NoSuchMethodException - target has no method that matches the method specified by name/parameterTypes

IllegalAccessException - a method in target matches name/parameterTypes, but cannot be accessed by target

IllegalArgumentException - this method can't convert an argument in parameters to the corresponding type in parameterTypes

java.lang.InvocationTargetException - the method invoked throws an exception (the exception thrown is wrapped in this exception)

See Also:

invoke(Object, Object[])

invoke

public static Object invoke(String name,
                            Class parameterType,
                            Object target,
                            Object argument)
                     throws IllegalAccessException,
                            IllegalArgumentException,
                            InvocationTargetException,
                            NoSuchMethodException

A convenience method that creates an NSSelector for a method that one argument, and immediately applies it to the target object.

Parameters:

name - name of the new NSSelector's method

parameterType - java.lang.Class object for the class of argument

target - object the new NSSelector is applied to

argument - argument to be used when invoking the method specified by name on target

Returns:

value returned by the method specified by name or null if the method is void

Throws:

java.lang.refelct.NoSuchMethodException - target has no method that matches the method specified by name/parameterType

IllegalAccessException - a method in target matches name/parameterType, but cannot be accessed by target

IllegalArgumentException - this method can't convert argument to parameterType

java.lang.InvocationTargetException - the method invoked throws an exception (the exception thrown is wrapped in this exception)

See Also:

invoke(String, Class[], Object, Object[])

invoke

public static Object invoke(String name,
                            Class parameterType1,
                            Class parameterType2,
                            Object target,
                            Object argument1,
                            Object argument2)
                     throws IllegalAccessException,
                            IllegalArgumentException,
                            InvocationTargetException,
                            NoSuchMethodException

A convenience method that creates an NSSelector for a method that two arguments, and immediately applies it to the target object.

Parameters:

name - name of the new NSSelector's method

parameterType1 - class of the value in argument1

parameterType2 - class of the value in argument2

target - object the new NSSelector is applied to

argument1 - first argument to use when invoking method on target

argument2 - second argument to use

Returns:

value returned by method/parameters; null if method is void

Throws:

java.lang.refelct.NoSuchMethodException - target has no method that matches the method specified by name/parameterType1/parameterType2

IllegalAccessException - a method in target matches name/parameterType1/parameterType2, but cannot be accessed by target

IllegalArgumentException - this method can't convert argument1 to parameterType1 or argument2 to parameterType2

java.lang.InvocationTargetException - the method invoked throws an exception (the exception thrown is wrapped in this exception)

See Also:

invoke(String, Class[], Object, Object[])

methodOnClass

public Method methodOnClass(Class targetClass)
                     throws NoSuchMethodException

Returns the java.lang.reflect.Method that corresponds to this NSSelector on the targetClass.

Parameters:

targetClass - class to search for method/parameters on

Returns:

method that matches method/parameters in targetClass

Throws:

java.lang.refelct.NoSuchMethodException - targetClass does not implement method/parameters

See Also:

Method, Class.getMethod(java.lang.String, java.lang.Class[])

methodOnObject

public Method methodOnObject(Object target)
                      throws NoSuchMethodException

Returns the java.lang.reflect.Method that corresponds to this NSSelector on the target object.

Parameters:

target - object to search for method/parameters on

Returns:

method that matches method/parameters in target

Throws:

java.lang.refelct.NoSuchMethodException - target does not implement method/parameters

See Also:

Method, Class.getMethod(java.lang.String, java.lang.Class[])

name

public String name()

Returns:

the name of the method specified by this NSSelector (method).

parameterTypes

public Class[] parameterTypes()

Returns a copy of the array of parameter types specified by this NSSelector.

Returns:

array of parameter types (parameters)

toString

public String toString()

Overrides:

toString in class Object

Returns:

string representation of this NSSelector, indicating its class and method name.