001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package com.sun.midp.midlet;
028:
029: import com.sun.midp.events.EventTypes;
030: import com.sun.midp.events.NativeEvent;
031: import com.sun.midp.events.EventQueue;
032:
033: /**
034: * This class provides methods to send events of types
035: * handled by MIDletEventConsumer I/F implementors.
036: * This class completely hide event construction & sending in its methods.
037: *
038: * The primary user of this class are MIDletProxyList & MIDletProxy
039: * in AMS isolate. Threrefore ve can use MIdletProxy object reference
040: * as sendXXXEvent() method parameter instead of currently used int IDs.
041: *
042: * Generic comments for all XXXEventProducers:
043: *
044: * For each supported event type there is a separate sendXXXEvent() method,
045: * that gets all needed parameters to construct an event of an approprate class.
046: * The method also performs event sending itself.
047: *
048: * If a given event type merges a set of logically different subtypes,
049: * this class shall provide separate methods for these subtypes.
050: *
051: * It is assumed that only one object instance of this class
052: * is initialized with the system event that is created at (isolate) startup.
053: *
054: * This class only operates on the event queue given to it during
055: * construction, the class does not obtain any restricted object itself,
056: * so it does not need protection.
057: *
058: * All MIDP stack subsystems that need to send events of supported types,
059: * must get a reference to an already created istance of this class.
060: * Typically, this instance should be passed as a constructor parameter.
061: *
062: * Class is NOT final to allow debug/profile/test/automation subsystems
063: * to change, substitute, complement default "event sending" functionality :
064: * Ex.
065: * class LogXXXEventProducer
066: * extends XXXEventProducer {
067: * ...
068: * void sendXXXEvent(parameters) {
069: * LOG("Event of type XXX is about to be sent ...")
070: * super.sendXXXEvent(parameters);
071: * LOG("Event of type XXX has been sent successfully !")
072: * }
073: * ...
074: * }
075: */
076: public class MIDletEventProducer {
077:
078: /** Cached reference to the MIDP event queue. */
079: protected EventQueue eventQueue;
080:
081: /**
082: * Construct a new MIDletEventProducer.
083: *
084: * @param theEventQueue An event queue where new events will be posted.
085: */
086: public MIDletEventProducer(EventQueue theEventQueue) {
087: eventQueue = theEventQueue;
088: }
089:
090: /*
091: * MIDlet State Management (Lifecycle) Events
092: *
093: * ACTIVATE_MIDLET_EVENT
094: * PAUSE_MIDLET_EVENT
095: * DESTROY_MIDLET_EVENT
096: *
097: */
098:
099: /**
100: * Pause a MIDlet.
101: * Probably: need some form of MIDlet ID instead of displayId.
102: * use MIDletProxy instead of 2 int ID parameters.
103: *
104: * @param isolateId ID of the target isolate (where to send event)
105: * @param midletClassName class name of the MIDlet
106: */
107: public void sendMIDletActivateEvent(int isolateId,
108: String midletClassName) {
109: sendMIDletEvent(EventTypes.ACTIVATE_MIDLET_EVENT, isolateId,
110: midletClassName);
111: }
112:
113: /**
114: * Activate a MIDlet.
115: * Former: void MIDletProxy.pauseMidlet();
116: *
117: * @param isolateId ID of the target isolate (where to send event)
118: * @param midletClassName class name of the MIDlet
119: */
120: public void sendMIDletPauseEvent(int isolateId,
121: String midletClassName) {
122: sendMIDletEvent(EventTypes.PAUSE_MIDLET_EVENT, isolateId,
123: midletClassName);
124: }
125:
126: /**
127: * Destroy a MIDlet.
128: * Former: void MIDletProxy.destroyMidlet();
129: *
130: * @param isolateId ID of the target isolate (where to send event)
131: * @param midletClassName class name of the MIDlet
132: */
133: public void sendMIDletDestroyEvent(int isolateId,
134: String midletClassName) {
135: sendMIDletEvent(EventTypes.DESTROY_MIDLET_EVENT, isolateId,
136: midletClassName);
137: }
138:
139: /**
140: * Sends an event with the only integer parameter for display ID
141: * to a MIDlet .
142: *
143: * @param eventType type of event to be sent
144: * @param midletIsolateId ID of the target isolate
145: * @param midletClassName class name of the MIDlet
146: */
147: private void sendMIDletEvent(int eventType, int midletIsolateId,
148: String midletClassName) {
149: NativeEvent event = new NativeEvent(eventType);
150:
151: event.stringParam1 = midletClassName;
152:
153: eventQueue.sendNativeEventToIsolate(event, midletIsolateId);
154: }
155: }
|