com.sun.dtv.ui.event
Class KeyEvent

java.lang.Object
  java.util.EventObject
      java.awt.AWTEvent
          java.awt.event.ComponentEvent
              java.awt.event.InputEvent
                  java.awt.event.KeyEvent
                      com.sun.dtv.ui.event.KeyEvent

All Implemented Interfaces:

ScarceResource, UserInputEvent, Serializable

Direct Known Subclasses:

RemoteControlEvent

public class KeyEvent
extends KeyEvent
implements UserInputEvent

This class extends the KeyEvent class by implementing the UserInputEvent interface. Being just a marker interface, UserInputEvent is derived from ScarceResource interface though, therefore methods from there have to be implemented here.

See Also:

ScarceResource.reserve(boolean, long, com.sun.dtv.resources.ScarceResourceListener), ScarceResource.release(), Serialized Form

Field Summary

Fields inherited from class java.awt.event.KeyEvent

CHAR_UNDEFINED, KEY_FIRST, KEY_LAST, KEY_PRESSED, KEY_RELEASED, KEY_TYPED, VK_0, VK_1, VK_2, VK_3, VK_4, VK_5, VK_6, VK_7, VK_8, VK_9, VK_A, VK_ACCEPT, VK_ADD, VK_AGAIN, VK_ALL_CANDIDATES, VK_ALPHANUMERIC, VK_ALT, VK_ALT_GRAPH, VK_AMPERSAND, VK_ASTERISK, VK_AT, VK_B, VK_BACK_QUOTE, VK_BACK_SLASH, VK_BACK_SPACE, VK_BRACELEFT, VK_BRACERIGHT, VK_C, VK_CANCEL, VK_CAPS_LOCK, VK_CIRCUMFLEX, VK_CLEAR, VK_CLOSE_BRACKET, VK_CODE_INPUT, VK_COLON, VK_COMMA, VK_COMPOSE, VK_CONTROL, VK_CONVERT, VK_COPY, VK_CUT, VK_D, VK_DEAD_ABOVEDOT, VK_DEAD_ABOVERING, VK_DEAD_ACUTE, VK_DEAD_BREVE, VK_DEAD_CARON, VK_DEAD_CEDILLA, VK_DEAD_CIRCUMFLEX, VK_DEAD_DIAERESIS, VK_DEAD_DOUBLEACUTE, VK_DEAD_GRAVE, VK_DEAD_IOTA, VK_DEAD_MACRON, VK_DEAD_OGONEK, VK_DEAD_SEMIVOICED_SOUND, VK_DEAD_TILDE, VK_DEAD_VOICED_SOUND, VK_DECIMAL, VK_DELETE, VK_DIVIDE, VK_DOLLAR, VK_DOWN, VK_E, VK_END, VK_ENTER, VK_EQUALS, VK_ESCAPE, VK_EURO_SIGN, VK_EXCLAMATION_MARK, VK_F, VK_F1, VK_F10, VK_F11, VK_F12, VK_F13, VK_F14, VK_F15, VK_F16, VK_F17, VK_F18, VK_F19, VK_F2, VK_F20, VK_F21, VK_F22, VK_F23, VK_F24, VK_F3, VK_F4, VK_F5, VK_F6, VK_F7, VK_F8, VK_F9, VK_FINAL, VK_FIND, VK_FULL_WIDTH, VK_G, VK_GREATER, VK_H, VK_HALF_WIDTH, VK_HELP, VK_HIRAGANA, VK_HOME, VK_I, VK_INPUT_METHOD_ON_OFF, VK_INSERT, VK_INVERTED_EXCLAMATION_MARK, VK_J, VK_JAPANESE_HIRAGANA, VK_JAPANESE_KATAKANA, VK_JAPANESE_ROMAN, VK_K, VK_KANA, VK_KANA_LOCK, VK_KANJI, VK_KATAKANA, VK_KP_DOWN, VK_KP_LEFT, VK_KP_RIGHT, VK_KP_UP, VK_L, VK_LEFT, VK_LEFT_PARENTHESIS, VK_LESS, VK_M, VK_META, VK_MINUS, VK_MODECHANGE, VK_MULTIPLY, VK_N, VK_NONCONVERT, VK_NUM_LOCK, VK_NUMBER_SIGN, VK_NUMPAD0, VK_NUMPAD1, VK_NUMPAD2, VK_NUMPAD3, VK_NUMPAD4, VK_NUMPAD5, VK_NUMPAD6, VK_NUMPAD7, VK_NUMPAD8, VK_NUMPAD9, VK_O, VK_OPEN_BRACKET, VK_P, VK_PAGE_DOWN, VK_PAGE_UP, VK_PASTE, VK_PAUSE, VK_PERIOD, VK_PLUS, VK_PREVIOUS_CANDIDATE, VK_PRINTSCREEN, VK_PROPS, VK_Q, VK_QUOTE, VK_QUOTEDBL, VK_R, VK_RIGHT, VK_RIGHT_PARENTHESIS, VK_ROMAN_CHARACTERS, VK_S, VK_SCROLL_LOCK, VK_SEMICOLON, VK_SEPARATER, VK_SEPARATOR, VK_SHIFT, VK_SLASH, VK_SPACE, VK_STOP, VK_SUBTRACT, VK_T, VK_TAB, VK_U, VK_UNDEFINED, VK_UNDERSCORE, VK_UNDO, VK_UP, VK_V, VK_W, VK_X, VK_Y, VK_Z

Fields inherited from class java.awt.event.InputEvent

ALT_DOWN_MASK, ALT_GRAPH_DOWN_MASK, ALT_GRAPH_MASK, ALT_MASK, BUTTON1_DOWN_MASK, BUTTON1_MASK, BUTTON2_DOWN_MASK, BUTTON2_MASK, BUTTON3_DOWN_MASK, BUTTON3_MASK, CTRL_DOWN_MASK, CTRL_MASK, META_DOWN_MASK, META_MASK, SHIFT_DOWN_MASK, SHIFT_MASK

Fields inherited from class java.awt.event.ComponentEvent

COMPONENT_FIRST, COMPONENT_HIDDEN, COMPONENT_LAST, COMPONENT_MOVED, COMPONENT_RESIZED, COMPONENT_SHOWN

Fields inherited from class java.awt.AWTEvent

ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, COMPONENT_EVENT_MASK, consumed, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, id, INPUT_METHOD_EVENT_MASK, INVOCATION_EVENT_MASK, ITEM_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, PAINT_EVENT_MASK, RESERVED_ID_MAX, TEXT_EVENT_MASK, WINDOW_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK

Fields inherited from class java.util.EventObject

source

Constructor Summary

KeyEvent(Component source, int id, long when, int modifiers, int keyCode, char keyChar)
Constructs a KeyEvent object.

Method Summary

static void	addResourceTypeListener(ResourceTypeListener listener) Adds a ResourceTypeListener to the implementation.
static KeyEvent[]	getInstances() Return the list of all existing instances of KeyEvent, whether they are already reserved or not.
boolean	isAvailable() Checks whether the given resource is currently available for reservation.
void	release() Releases this resource.
static void	removeResourceTypeListener(ResourceTypeListener listener) Removes a previously attached listener.
void	reserve(boolean force, long timeout, ScarceResourceListener listener) Requests reservation of the given scarce resource instance.
static KeyEvent	reserveOne(int keyCode, boolean force, long timeoutms, ScarceResourceListener listener) Returns a reserved instance out of the pool of all KeyEvent instances matching the specified key code.

Methods inherited from class java.awt.event.KeyEvent

getKeyChar, getKeyCode, getKeyModifiersText, getKeyText, isActionKey, paramString, setKeyChar, setKeyCode, setSource

Methods inherited from class java.awt.event.InputEvent

consume, getModifiers, getModifiersEx, getModifiersExText, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown

Methods inherited from class java.awt.event.ComponentEvent

getComponent

Methods inherited from class java.awt.AWTEvent

getID, toString

Methods inherited from class java.util.EventObject

getSource

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

KeyEvent

public KeyEvent(Component source,
                int id,
                long when,
                int modifiers,
                int keyCode,
                char keyChar)

Constructs a KeyEvent object.

Parameters:

source - the Component that originated the event

id - an integer identifying the type of event

when - a long integer that specifies the time the event occurred

modifiers - the modifier keys down during event (shift, ctrl, alt, meta) Either extended _DOWN_MASK or old _MASK modifiers should be used, but both models should not be mixed in one event. Use of the extended modifiers is preferred.

keyCode - the integer code for an actual key, or VK_UNDEFINED (for a key-typed event) (as defined in java.awt.event.KeyEvent)

keyChar - the Unicode character generated by this event, or CHAR_UNDEFINED (for key-pressed and key-released events which do not map to a valid Unicode character) (as defined in java.awt.event.KeyEvent)

See Also:

KeyEvent

Method Detail

reserve

public void reserve(boolean force,
                    long timeout,
                    ScarceResourceListener listener)
             throws IllegalArgumentException,
                    TimeoutException

Requests reservation of the given scarce resource instance. The method will block until this instance is available. The method returns normally only if the reservation succeeded. All other cases are handled by exceptions.

First, if there is a security manager, its checkPermission method is called with the permission ScarceResourcePermission(name, "reserve"). If force is moreover set to true, then the permission is also checked on ScarceResourcePermission(name, "force").

During the reservation process, if that resource instance is already allocated, the implementation must notify the current owner of that resource about the reservation request via the ScarceResourceListener interface:

• either by ScarceResourceListener.releaseRequested() if force is false,
• or by ScarceResourceListener.releaseForced() in the other case.

The listener will be used for such notification only until this resource is released. After releasing, the implementation must not call any of the listener's interface methods.

After that first event, the implementation will proceed accordingly and release (or not) the requested resource. In case the implementation releases the resource, it will trigger a ScarceResourceListener.released() event to the original listening owner of the resource to inform him that the resource does not belong to him anymore.

The application may control the time to wait for such a resource to be available by setting timeoutms. In case the duration of the reservation exceeds the time expressed in timeoutms, a TimeoutException is thrown.

Under normal operation, resources are released using the release method. However, in the case where the application does not release resources when requested or the application is terminated, the implementation must release all resources allocated to the application to allow other applications to be notified of changes in resource allocation and to be able to reserve them. See the Resource Cleanup section of the application lifecycle.

Specified by:

reserve in interface ScarceResource

Parameters:

force - If true, this method will withdraw the resource from the current owner. If false, the implementation will block and wait until the resource is made available (using release()) or until timeoutms.

timeout - A positive amount of time in millisecond until which this method will wait for the resource to be released by its current owner. The value of -1 indicates that the implementation will wait forever.

listener - The listener to be attached to receive notification about the status of the resource.

Throws:

IllegalArgumentException - If listener is null or if the value specified in timeoutms is not valid i.e. not either a positive integer or -1.

TimeoutException - If the time specified in timeoutms is over and the resource could not be reserved.

reserveOne

public static KeyEvent reserveOne(int keyCode,
                                  boolean force,
                                  long timeoutms,
                                  ScarceResourceListener listener)
                           throws IllegalArgumentException,
                                  TimeoutException

Returns a reserved instance out of the pool of all KeyEvent instances matching the specified key code. This method either returns with the instance or throws an exception according to the situation.

This method behaves exactly as the reserve() method.

Parameters:

keyCode - the integer code for an actual key, or VK_UNDEFINED (for a key-typed event) (as defined in java.awt.event.KeyEvent)

force - If true, this method is allowed to withdraw any given resource from its current owner. If false, the implementation will block and wait until a resource of the given type is made available (using release()) or until timeoutms milliseconds.

timeoutms - A positive amount of time in millisecond until which this method will wait for any resource to be released by its current owner. The value of -1 indicates that the implementation will wait forever.

listener - The listener to be attached to receive notification about the status of the resource.

Returns:

The instance of type KeyEvent that has been reserved.

Throws:

IllegalArgumentException - If listener is null or if the value specified in timeoutms is not valid i.e. not either a positive integer or -1.

TimeoutException - If the time specified in timeoutms is over and the resource could not be reserved.

See Also:

reserve(boolean, long, com.sun.dtv.resources.ScarceResourceListener)

release

public void release()

Releases this resource.

The resource will be made available to another application across the platform. After calling this method, it is no more possible to interact with the given resource: calls to critical methods of that scarce resource must be ignored and may throw IllegalStateException. This assertion is valid and the behavior required for any class implementing the ScarceResource interface. In order to interact again with the given resource, the application must call the reserve() method and become the owner again.

The implementation may dispose any system resources that this object is using. After the implementation must not call any of the methods of the listener that was attached at reservation time.

If the resource was already available (i.e. not reserved), this method does nothing.

Specified by:

release in interface ScarceResource

isAvailable

public boolean isAvailable()

Checks whether the given resource is currently available for reservation. The returned value gives the current situation and does not guarantee that the resource will still be available at a later moment e.g. at reservation time: another application may have taken that resource in the meantime.

Specified by:

isAvailable in interface ScarceResource

Returns:

A boolean set to true if the given resource is currently available for reservation.

getInstances

public static KeyEvent[] getInstances()

Return the list of all existing instances of KeyEvent, whether they are already reserved or not.

Returns:

list of all existing instances of KeyEvent

addResourceTypeListener

public static void addResourceTypeListener(ResourceTypeListener listener)
                                    throws NullPointerException

Adds a ResourceTypeListener to the implementation. Whenever a reserve() or a release() is called on any resources of the same type, the implementation will call the listener's corresponding methods.

Parameters:

listener - The listener that is triggered for events on resources of the same type.

Throws:

NullPointerException - If listener is null.

See Also:

removeResourceTypeListener(com.sun.dtv.resources.ResourceTypeListener)

removeResourceTypeListener

public static void removeResourceTypeListener(ResourceTypeListener listener)
                                       throws NullPointerException

Removes a previously attached listener. If the listener was not attached before, this method does nothing.

Parameters:

listener - The listener that is triggered for events on resources of the same type.

Throws:

NullPointerException - If listener is null.

See Also:

addResourceTypeListener(com.sun.dtv.resources.ResourceTypeListener)