Java DTV API 1.3
18-Nov-2009

com.sun.dtv.ui.event
Class KeyEvent

java.lang.Object
  extended by java.util.EventObject
      extended by java.awt.AWTEvent
          extended by java.awt.event.ComponentEvent
              extended by java.awt.event.InputEvent
                  extended by java.awt.event.KeyEvent
                      extended by 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:

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)

Java DTV API 1.3
18-Nov-2009

Copyright © 2008-2009 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved.

U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Sun, Sun Microsystems, the Sun logo and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.Products covered by and information contained in this service manual are controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited.

DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Use of this document is subject to license terms.