NSSelector

Inherits from:
Object

Implements:
Serializable

Package:
com.webobjects.foundation

Class Description

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

To create a selector, use NSSelector's single constructor, which takes the method's name and an array of the parameter types. Note that to obtain a Class object for a type, append .class to the type's name. For example, the Class object for Object is Object.class and the Class object for boolean is boolean.class

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, int.class} );

To apply a selector on an object, use the overloaded instance method invoke. 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, use an object of the corresponding wrapper class. invoke converts the object back to the primitive type when it invokes the method. For example, to pass the float f, use new Float(f); and to pass the boolean value true, use new Boolean(true).

This code sample gives you 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, use the overloaded static method invoke. 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, int.class},      obj1, new Object[] {"hi", new Integer(i)}); NSSelector.invoke("doIt", String.class, int.class,     obj1, "bye", new Integer(10));

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

NSSelector is similar to java.lang.reflect.Method, which fully specifies a particular class's implementation of a method, and you can apply it only to objects of that class. NSSelector doesn't specify the method's class, so you can apply it to an object of any class. To find the java.lang.reflect.Method object for a method that matches a selector and that's in a particular object or class, use methodOnObject or methodOnClass.

Method Types

Constructors

NSSelector

Static methods

invoke

Invoking selectors

invoke

Testing selectors

implementedByClass
implementedByObject

Converting selectors to java.lang.reflect.Methods

methodOnClass
methodOnObject

Accessing selector elements

name
parameterTypes

Methods inherited from Object

equals
hashCode
toString

Constructors

NSSelector

public NSSelector(String methodName)

Creates a selector for the method that's named methodName and takes no parameters.

public NSSelector( String methodName, Class[] parameterTypes)

Creates a selector for the method that's named methodName and takes parameters parameterTypes. To create a selector for a method that takes no arguments, use null for parameterTypes. For an example, see the class description for this class.

Static Methods

invoke

public static Object invoke( String methodName, Class[] parameterTypes, Object target, Object[] arguments) throws IllegalAccessException, IllegalArgumentException, java.lang.reflect.InvocationTargetException, NoSuchMethodException

Creates and applies a selector that has any number of arguments. This method creates a selector with methodName and the parameter types in the array parameterTypes, applies that selector to target with the arguments in the array arguments, and returns the result. To apply a method that takes no arguments, use null for the arrays parameterTypes and arguments. As part of its implementation, this method uses the NSSelector constructor and the instance method invoke. For more information, see those method descriptions.

public static Object invoke( String methodName, Class parameterType, Object target, Object argument) throws IllegalAccessException, IllegalArgumentException, java.lang.reflect.InvocationTargetException, NoSuchMethodException

Creates and applies a selector that has one argument. This method creates a selector with methodName and parameterType, applies that selector to target with argument, and returns the result. As part of its implementation, this method uses the NSSelector constructor and the instance method invoke. For more information, see those method descriptions.

public static Object invoke( String methodName, Class parameterType1, Class parameterType2, Object target, Object argument1, Object argument2) throws IllegalAccessException, IllegalArgumentException, java.lang.reflect.InvocationTargetException, NoSuchMethodException

Creates and applies a selector that has two arguments. This method creates a selector with methodName and the parameter types parameterType1 and parameterType2, applies that selector to target with the arguments argument1 and argument2, and returns the result. As part of its implementation, this method uses the NSSelector constructor and the instance method invoke. For more information, see those method descriptions.

Instance Methods

equals

public boolean equals(Object anObject)

Compares the receiving NSSelector object to anObject. If anObject is an NSSelector and the contents of anObject are equal to the contents of the receiver, this method returns true. If not, it returns false. Two selectors are equal if their names and parameter types are equal.

hashCode

public int hashCode()

Provide an appropriate hash code useful for storing the receiver in a hash-based data structure.

implementedByClass

public boolean implementedByClass(Class targetClass)

Returns whether the class targetClass implements a method that matches the selector.

implementedByObject

public boolean implementedByObject(Object target)

Returns whether the object target implements a method that matches the selector. As part of its implementation, this method uses implementedByClass.

invoke

public Object invoke( Object target, Object[] arguments) throws IllegalAccessException, IllegalArgumentException, java.lang.reflect.InvocationTargetException, NoSuchMethodException

Invokes the method specified by the selector on target with arguments, and returns the result. If that method is void, it returns null. Note that the method may be a static or instance method.

invoke can't handle arguments or return values of primitive types (such as boolean, int, or float). If the method matching the selector returns a value of a primitive type, invoke 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 invoke, use an object of the corresponding wrapper class. invoke converts the object back to the primitive type when it invokes the method.

invoke throws an exception in the following cases:

If target has no method that matches the selector, it throws NoSuchMethodException.
If a method matches the selector but is inaccessible to target, it throws IllegalAccessException.
If it can't convert an argument to the type specified in the selector, it throws IllegalArgumentException.
If the invoked method throws an exception, it wraps that exception in a java.lang.reflect.InvocationTargetException and throws the new exception without completing.

As part of its implementation, this method uses methodOnClass.

For an example, see the class description for this class.

public Object invoke( Object target) throws IllegalAccessException, IllegalArgumentException, java.lang.reflect.InvocationTargetException, NoSuchMethodException

Invokes the method specified by the selector on target with no arguments, and returns the result. If that method is void, it returns null. Note that the method may be a static or instance method.

As part of its implementation, this method calls the invoke instance method that takes an array of arguments. For more information, see that method's description.

public Object invoke( Object target, Object argument) throws IllegalAccessException, IllegalArgumentException, java.lang.reflect.InvocationTargetException, NoSuchMethodException

Invokes the method specified by the selector on target with one argument (argument), and returns the result. If that method is void, it returns null. Note that the method may be a static or instance method.

As part of its implementation, this method calls the invoke instance method that takes an array of arguments. For more information, see that method's description.

public Object invoke( Object target, Object argument1, Object argument2) throws IllegalAccessException, IllegalArgumentException, java.lang.reflect.InvocationTargetException, NoSuchMethodException

Invokes the method specified by the selector on target with two arguments (argument1 and argument2), and returns the result. If that method is void, it returns null. Note that the method may be a static or instance method.

As part of its implementation, this method calls the invoke instance method that takes an array of arguments. For more information, see that method's description.