FileDocCategorySizeDatePackage
MIDletControllerEventProducer.javaAPI DocphoneME MR2 API (J2ME)16216Wed May 02 18:00:06 BST 2007com.sun.midp.main

MIDletControllerEventProducer

public class MIDletControllerEventProducer extends Object
This class provides methods to send events of types handled by MIDletControllerEventConsumer I/F implementors. This class completely hide event construction & sending in its methods. This class is intended to be used by MIDletStateHandler & MIDletPeer classes in Allication Isolate. So in some of its sendXXXEvent()methods we can change int IDs to MIDletPeer references. Generic comments for all XXXEventProducers: For each supported event type there is a separate sendXXXEvent() method, that gets all needed parameters to construct an event of an approprate class. The method also performs event sending itself. If a given event type merges a set of logically different subtypes, this class shall provide separate methods for these subtypes. It is assumed that only one object instance of this class is initialized with the system event that is created at (isolate) startup. This class only operates on the event queue given to it during construction, the class does not obtain any restricted object itself, so it does not need protection. All MIDP stack subsystems that need to send events of supported types, must get a reference to an already created istance of this class. Typically, this instance should be passed as a constructor parameter. Class is NOT final to allow debug/profile/test/automation subsystems to change, substitute, complement default "event sending" functionality : Ex. class LogXXXEventProducer extends XXXEventProducer { ... void sendXXXEvent(parameters) { LOG("Event of type XXX is about to be sent ...") super.sendXXXEvent(parameters); LOG("Event of type XXX has been sent successfully !") } ... }

Fields Summary
protected com.sun.midp.events.EventQueue
eventQueue
Cached reference to the MIDP event queue.
protected int
amsIsolateId
Cached reference to AMS isolate ID.
protected int
currentIsolateId
Cached reference to current isolate ID.
final com.sun.midp.events.NativeEvent
startErrorEvent
Preallocate start error event to work in case of out of memory
final com.sun.midp.events.NativeEvent
midletCreatedEvent
Preallocate MIDlet created event to work in case of out of memory
final com.sun.midp.events.NativeEvent
midletActiveEvent
Preallocate MIDlet active event to work in case of out of memory
final com.sun.midp.events.NativeEvent
midletPausedEvent
Preallocate MIDlet paused event to work in case of out of memory
final com.sun.midp.events.NativeEvent
midletDestroyedEvent
Preallocate MIDlet destroyed event to work in case of out of memory
final com.sun.midp.events.NativeEvent
midletRsPausedEvent
Preallocate MIDlet resources paused event to work in case of out of memory
Constructors Summary
public MIDletControllerEventProducer(com.sun.midp.events.EventQueue theEventQueue, int theAmsIsolateId, int theCurrentIsolateId)
Construct a new MIDletControllerEventProducer.

param
theEventQueue An event queue where new events will be posted.
param
theAmsIsolateId AMS Isolate Id
param
theCurrentIsolateId Current Isolate Id


        eventQueue = theEventQueue;
        amsIsolateId = theAmsIsolateId;
        currentIsolateId = theCurrentIsolateId;

        /* Cache all of the notification events. */
        startErrorEvent =
            new NativeEvent(EventTypes.MIDLET_START_ERROR_EVENT);
        midletCreatedEvent =
            new NativeEvent(EventTypes.MIDLET_CREATED_NOTIFICATION);
        midletActiveEvent =
            new NativeEvent(EventTypes.MIDLET_ACTIVE_NOTIFICATION);
        midletPausedEvent =
            new NativeEvent(EventTypes.MIDLET_PAUSED_NOTIFICATION);
        midletDestroyedEvent =
            new NativeEvent(EventTypes.MIDLET_DESTROYED_NOTIFICATION);
        midletRsPausedEvent =
            new NativeEvent(EventTypes.MIDLET_RS_PAUSED_NOTIFICATION);
Methods Summary
public voidsendDisplayBackgroundRequestEvent(int midletDisplayId)
Called to send a background request event to the AMS isolate.

param
midletDisplayId ID of the sending Display

        sendEvent(new NativeEvent(EventTypes.BACKGROUND_REQUEST_EVENT),
                midletDisplayId);
public voidsendDisplayCreateNotifyEvent(int midletDisplayId, java.lang.String midletClassName)
Called to send a Display created notification to the AMS isolate.

param
midletDisplayId ID of the sending Display
param
midletClassName Class name of the MIDlet that owns the display

        NativeEvent event =
            new NativeEvent(EventTypes.DISPLAY_CREATED_NOTIFICATION);

        event.intParam1 = currentIsolateId;
        event.intParam2 = midletDisplayId;

        event.stringParam1 = midletClassName;

        eventQueue.sendNativeEventToIsolate(event, amsIsolateId);
public voidsendDisplayForegroundRequestEvent(int midletDisplayId, boolean isAlert)
Called to send a foreground request event to the AMS isolate.

param
midletDisplayId ID of the sending Display
param
isAlert true if the current displayable is an Alert

        NativeEvent event =
            new NativeEvent(EventTypes.FOREGROUND_REQUEST_EVENT);

        if (isAlert) {
            event.intParam2 = 1;
        } else {
            event.intParam2 = 0;
        }

        sendEvent(event, midletDisplayId);
public voidsendDisplayPreemptStartEvent(int midletDisplayId)
Called to start preempting and end preempting. Probably: will need more parameters, ex. MIDlet ID

param
midletDisplayId ID of the sending Display

        NativeEvent event =
            new NativeEvent(EventTypes.PREEMPT_EVENT);

        event.intParam2 = -1; /* start = true */

        sendEvent(event, midletDisplayId);
public voidsendDisplayPreemptStopEvent(int midletDisplayId)
Called to start preempting and end preempting. Probably: will need more parameters, ex. MIDlet ID

param
midletDisplayId ID of the sending Display

        NativeEvent event =
            new NativeEvent(EventTypes.PREEMPT_EVENT);

        event.intParam2 = 0; /* start = false */

        sendEvent(event, midletDisplayId);
private voidsendEvent(com.sun.midp.events.NativeEvent event, int midletDisplayId)
Sends standard MIDlet controller event setting two integer parameters for display ID and isolate ID. It is synchronized by the event to be sent to avoid inconsistent parameters setting.

param
event event to be sent
param
midletDisplayId ID of the sending Display

        synchronized (event) {
            event.intParam1 = currentIsolateId;
            event.intParam4 = midletDisplayId;
            eventQueue.sendNativeEventToIsolate(event, amsIsolateId);
        }
private voidsendEvent(com.sun.midp.events.NativeEvent event, int midletSuiteId, java.lang.String midletClassName)
Sends standard MIDlet controller event setting two parameters for suite ID and class name. It is synchronized by the event to be sent to avoid inconsistent parameters setting.

param
event event to be sent
param
midletSuiteId ID of the MIDlet suite
param
midletClassName Class name of the MIDlet

        synchronized (event) {
            event.intParam1 = midletSuiteId;
            event.stringParam1 = midletClassName;
            eventQueue.sendNativeEventToIsolate(event, amsIsolateId);
        }
public voidsendMIDletActiveNotifyEvent(int midletSuiteId, java.lang.String midletClassName)
Called to send a MIDlet active notification to the AMS isolate.

param
midletSuiteId ID of the MIDlet suite
param
midletClassName Class name of the MIDlet

        sendEvent(midletActiveEvent, midletSuiteId, midletClassName);
public voidsendMIDletCreateNotifyEvent(int midletSuiteId, java.lang.String midletClassName, int midletExternalAppId, java.lang.String midletDisplayName)
Called to send a MIDlet created notification to the AMS isolate.

param
midletSuiteId ID of the MIDlet suite
param
midletClassName Class name of the MIDlet
param
midletExternalAppId ID of given by an external application manager
param
midletDisplayName name to show the user


        synchronized (midletCreatedEvent) {
            midletCreatedEvent.intParam1 = midletSuiteId;
            midletCreatedEvent.intParam2 = currentIsolateId;
            midletCreatedEvent.intParam3 = midletExternalAppId;

            midletCreatedEvent.stringParam1 = midletClassName;
            midletCreatedEvent.stringParam2 = midletDisplayName;

            eventQueue.sendNativeEventToIsolate(midletCreatedEvent,
                                                amsIsolateId);
        }
public voidsendMIDletDestroyNotifyEvent(int midletSuiteId, java.lang.String midletClassName)
Called to send a MIDlet destroyed notification to the AMS isolate.

param
midletSuiteId ID of the MIDlet suite
param
midletClassName Class name of the MIDlet

        sendEvent(midletDestroyedEvent, midletSuiteId, midletClassName);
public voidsendMIDletDestroyRequestEvent(int midletDisplayId)
Called by the display to request the central AMS to destroy the owning MIDlet.

param
midletDisplayId ID of the sending Display

        sendEvent(new NativeEvent(EventTypes.MIDLET_DESTROY_REQUEST_EVENT),
                midletDisplayId);
public voidsendMIDletForegroundTransferEvent(int originMIDletSuiteId, java.lang.String originMIDletClassName, int targetMIDletSuiteId, java.lang.String targetMIDletClassName)
Called to send a foreground MIDlet transfer event to the AMS isolate. Former: NEW method, originally sent from CHAPI

param
originMIDletSuiteId ID of MIDlet from which to take forefround ownership away,
param
originMIDletClassName Name of MIDlet from which to take forefround ownership away
param
targetMIDletSuiteId ID of MIDlet to give forefround ownership to,
param
targetMIDletClassName Name of MIDlet to give forefround ownership to

        NativeEvent event =
            new NativeEvent(EventTypes.FOREGROUND_TRANSFER_EVENT);

        event.intParam1 = originMIDletSuiteId;
        event.intParam2 = targetMIDletSuiteId;

        event.stringParam1 = originMIDletClassName;
        event.stringParam2 = targetMIDletClassName;

        eventQueue.sendNativeEventToIsolate(event, amsIsolateId);
public voidsendMIDletPauseNotifyEvent(int midletSuiteId, java.lang.String midletClassName)
Called to send a MIDlet paused notification to the AMS isolate.

param
midletSuiteId ID of the MIDlet suite
param
midletClassName Class name of the MIDlet

        sendEvent(midletPausedEvent, midletSuiteId, midletClassName);
public voidsendMIDletResumeRequest(int midletSuiteId, java.lang.String midletClassName)
Called to send a MIDlet resume request to the AMS isolate.

param
midletSuiteId ID of the MIDlet suite
param
midletClassName Class name of the MIDlet

        sendEvent(new NativeEvent(EventTypes.MIDLET_RESUME_REQUEST),
                  midletSuiteId, midletClassName);
public voidsendMIDletRsPauseNotifyEvent(int midletSuiteId, java.lang.String midletClassName)
Sends notification for MIDlet resources pause to the AMS isolate.

param
midletSuiteId ID of the MIDlet suite
param
midletClassName Class name of the MIDlet

        sendEvent(midletRsPausedEvent, midletSuiteId, midletClassName);
public voidsendMIDletStartErrorEvent(int midletSuiteId, java.lang.String midletClassName, int midletExternalAppId, int errorCode, java.lang.String errorDetails)
Notifies AMS that MIDlet creation failed NEW: earlier it has been explicitely generated by void static AppIsolateMIDletSuiteLoader.main(...)

param
midletExternalAppId ID of given by an external application manager
param
midletSuiteId ID of the MIDlet suite
param
midletClassName Class name of the MIDlet
param
errorCode start error code


        synchronized (startErrorEvent) {
            // use pre-created event to work in case of handling out of memory
            startErrorEvent.intParam1 = midletSuiteId;
            startErrorEvent.intParam2 = midletExternalAppId;
            startErrorEvent.intParam3 = errorCode;

            startErrorEvent.stringParam1 = midletClassName;
            startErrorEvent.stringParam2 = errorDetails; 

            eventQueue.sendNativeEventToIsolate(startErrorEvent, amsIsolateId);
        }
public voidsendSetForegroundByNameRequestEvent(int suiteId, java.lang.String className)
Called to send a request to AMS isolate for a MIDlet be in the foreground.

param
suiteId MIDlet's suite ID
param
className MIDlet's class name


        NativeEvent event =
            new NativeEvent(EventTypes.SET_FOREGROUND_BY_NAME_REQUEST);

        event.intParam1 = suiteId;
        event.stringParam1 = className;

        eventQueue.sendNativeEventToIsolate(event, amsIsolateId);