WebObjects 5.2

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:

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.

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.