net.rim.device.api.util
Class ListenerUtilities

java.lang.Object
  extended by net.rim.device.api.util.ListenerUtilities

public final class ListenerUtilities
extends Object

Utility methods for managing a list of listeners.

Behaviour
Whenever a listener is added or removed from the list, a new Vector is constructed. When an event needs to be distributed to the listeners, a copy of the listener list is thus not required.

To fire an event, use code similar to this example:

 private void fireXXXEvent( parms ) {
     Vector tmpListeners = listeners;
     if( tmpListeners != null ) {
         int size = tmpListeners.size();
         for( int i = 0; i < size; ++i ) {
             ((YYYListener) tmpListeners.elementAt( i )).XXX( parms );
         }
     }
 }
 


Method Summary
static Object[] addListener(Object[] listeners, Object listener)
          Adds a listener to the list of listeners.
static Vector addListener(Vector listeners, Object listener)
          Adds a listener to the list of listeners.
static boolean containsListener(Object[] listeners, Object listener)
          Determines if the specified listener is present in the list.
static Object[] fastAddListener(Object[] listeners, Object listener)
          Adds a listener to the list of listeners.
static Vector fastAddListener(Vector listeners, Object listener)
          Adds a listener to the current list of listeners.
static Object[] removeListener(Object[] listeners, Object listener)
          Removes a listener from the list of listeners.
static Vector removeListener(Vector listeners, Object listener)
          Removes a listener from the list of listeners.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

addListener

public static final Vector addListener(Vector listeners,
                                       Object listener)
Adds a listener to the list of listeners.

The list holds only one occurence of each listener added. Note that this method never affects the contents of the original list of listeners, although it returns that vector if the listener to add already exists in the list.

Parameters:
listeners - Current list of listeners; if null, this method creates a new vector for you.
listener - Listener to add; if already in the list, this method does nothing. If this parameter is null, this method throws a NullPointerException.
Returns:
New list of listeners (if the listener already existed in this list, then this method simply returns the listeners vector passed in).
Throws:
NullPointerException - if the listener parameter is null.

fastAddListener

public static final Vector fastAddListener(Vector listeners,
                                           Object listener)
Adds a listener to the current list of listeners.

The list holds only one occurence of each listener added. Note that this method operates on the contents of the original list of listeners (as long as its non-null), and then returns that vector.

Parameters:
listeners - Current list of listeners; if null, this method creates a new vector for you.
listener - Listener to add; if already in the list, this method does nothing. If this parameter is null, this method throws a NullPointerException.
Returns:
Modified list of listeners (however, if the listener already existed in this list, then this method simply returns the list unmodified).
Throws:
NullPointerException - if the listener parameter is null.

removeListener

public static final Vector removeListener(Vector listeners,
                                          Object listener)
Removes a listener from the list of listeners.

Parameters:
listeners - Current list of listeners; if null, this method does nothing.
listener - Listener to remove; if this listener does not exist in the list or if null is used in place of this parameter, this method does nothing.
Returns:
New list of listeners. If the listener did not exist in the list, this method returns the listeners vector passed in. If the listeners vector was null, this method returns null.

addListener

public static final Object[] addListener(Object[] listeners,
                                         Object listener)
Adds a listener to the list of listeners.

The list holds only one occurence of each listener added. Note that this method never affects the contents of the original list of listeners, although it returns that array if the listener to add already exists in the list.

Parameters:
listeners - Current list of listeners; if null, this method creates a new array for you.
listener - Listener to add; if already in the list, this method does nothing. If this parameter is null, this method throws a NullPointerException.
Returns:
New list of listeners (if the listener already existed in this list, then this method simply returns the listeners array passed in).
Throws:
NullPointerException - if the listener parameter is null.
Since:
BlackBerry API 4.0.0

fastAddListener

public static final Object[] fastAddListener(Object[] listeners,
                                             Object listener)
Adds a listener to the list of listeners.

The list holds only one occurence of each listener added. Note that this method operates on the contents of the original list of listeners (as long as its non-null), and then returns that vector.

Parameters:
listeners - Current list of listeners; if null, this method creates a new array for you.
listener - Listener to add; if already in the list, this method does nothing. If this parameter is null, this method throws a NullPointerException.
Returns:
New list of listeners (if the listener already existed in this list, then this method simply returns the listeners array passed in).
Throws:
NullPointerException - if the listener parameter is null.
Since:
BlackBerry API 4.0.0

removeListener

public static final Object[] removeListener(Object[] listeners,
                                            Object listener)
Removes a listener from the list of listeners.

Parameters:
listeners - Current list of listeners; if null, this method does nothing.
listener - Listener to remove; if this listener does not exist in the list or if null is used in place of this parameter, this method does nothing.
Returns:
New list of listeners. If the listener did not exist in the list, this method returns the listeners array passed in. If the listeners array was null, this method returns null.
Since:
BlackBerry API 4.0.0

containsListener

public static final boolean containsListener(Object[] listeners,
                                             Object listener)
Determines if the specified listener is present in the list.

Parameters:
listeners - Current list of listeners; if null, this method returns false.
listener - Listener to check; if this listener does not exist in the list or if null is used in place of this parameter, this method returns false.
Returns:
True if the listener exists in the list, false otherwise.
Since:
BlackBerry API 4.2.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal