/*
* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
*
*/


package com.nokia.mj.impl.rt.midp;

import javax.microedition.midlet.MIDlet;
import javax.microedition.midlet.MIDletStateChangeException;

import com.nokia.mj.impl.rt.legacy.LegacySupport;

/**
 * A class for communication gate between MIDlet and the MIDP life cycle.
 * <p>
 * The MIDlet class is in such package where it is not possible to add any new
 * public classes. The issue is that some important methods are defined
 * as protected, so they can only be called from MIDlet class. The MIDlet
 * class can not contain any new public methods, so in order to delegate
 * calls to these protected methods, there must be introduced package private
 * methods that are accessed via a class which is in javax.microedition.midlet
 * package as a package private private class. This package private class will
 * be subclass of this class.
 * <p>
 * Other reason having this class is used to delegate command originated by the
 * MIDlet to the MIDP life cycle - e.g. notifyDestroyed.
 * <p>
 * During the MIDlet construction an instance of the sub class is constructed.
 * The subclass constructs this class and provides a refernce to just created
 * instance of a MIDlet subclass. This class will store the reference to the
 * MIDlet instance. During the construction of this class it will give a
 * reference to this to the MIDP life cycle, which will store the refernce in
 * order to delegate calls to MIDlet.
 */
public abstract class MidletApplicationBase
{

    /**
     * A reference to the MIDlet.
     */
    private MIDlet mMidlet;

    /*** ----------------------------- PUBLIC ------------------------------ */
    /**
     * This method will delegate the MIDlet wish to enter into the destroyed
     * state to the MIDP life cycle.
     */
    public final void notifyDestroyed()
    {
        MidletLifeCycle.getInstance().notifyDestroyed();
    }

    /**
     * This method will delegate the MIDlet wish to enter into the paused
     * state to the MIDP life cycle.
     */
    public final void notifyPaused()
    {
        MidletLifeCycle.getInstance().notifyPaused();
    }

    /**
     * This method will delegate the MIDlet wish to enter into the active
     * state to the MIDP life cycle.
     */
    public final void resumeRequest()
    {
        MidletLifeCycle.getInstance().resumeRequest();
    }

    /**
     * The implementation of MIDlet.getAppProperty().
     * @see javax.microedition.midlet.MIDlet#getAppProperty(java.lang.String).
     * @param key The name of the attribute.
     * @return The value of the attribute if found, otherwise null.
     */
    public final String getAppProperty(String key)
    {
        return ApplicationInfoImpl.getMidletInfo().getAttribute(key);

    }

    /*** ---------------------------- PROTECTED --------------------------- */

    /**
     * The constructor of MidletApplicationBase. Will give a reference to this
     * to be stored by the MIDP life cycle.
     * @param midlet A reference to just created MIDlet.
     */
    protected MidletApplicationBase(MIDlet midlet)
    {
        mMidlet = midlet;
        MidletLifeCycle lifeCycle = MidletLifeCycle.getInstance();
        lifeCycle.setMidletApplication(this);

        // Set the created MIDlet to be accessed by legacy runtime.
        LegacySupport.setMidlet(midlet);

    }

    /**
     * A getter for a reference to the MIDlet.
     * @return The MIDlet.
     */
    protected final MIDlet getMidlet()
    {
        return mMidlet;
    }

    /**
     * An abstract method for delegating the start cmd to the MIDlet.
     * @see javax.microedition.midlet.MIDlet#startApp().
     */
    protected abstract void invokeStartApp() throws MIDletStateChangeException;

    /**
     * An abstract method for delegating the pause cmd to the MIDlet.
     * @see javax.microedition.midlet.MIDlet#pauseApp().
     */
    protected abstract void invokePauseApp();

    /**
     * An abstract method for delegating the destroy cmd to the MIDlet.
     * The unconditional is always true and any thrown exceptions will
     * be ignored.
     * @see javax.microedition.midlet.MIDlet#destroyApp().
     * @param unconditional Always true.
     */
    protected abstract void invokeDestroyApp(boolean unconditional)
    throws MIDletStateChangeException;

    /*** ----------------------------- PRIVATE ---------------------------- */

    /**
     * The default constructor is not allowed.
     */
    private MidletApplicationBase()
    {
    }
}