1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  This class provides container for message.

    15 *

    16 */

    17 

    18 

    19 #ifndef MIDPRUNTIMESTARTER_H

    20 #define MIDPRUNTIMESTARTER_H

    21 

    22 #include <map>

    23 

    24 #include "commslistener.h"

    25 #include "commsmessage.h"

    26 

    27 #include "scopedlocks.h"

    28 #include "monitor.h"

    29 

    30 #include "applicationinfo.h"

    31 #include "applicationstatecontroller.h"

    32 #include "midpruntimepushsupport.h"

    33 #include "midpruntimeinternalsupport.h"

    34 #include "jvmstarter.h"

    35 

    36 #include "javastorage.h"

    37 #include "javastorageentry.h"

    38 

    39 #include "commsclientendpoint.h"

    40 

    41 namespace java // codescanner::namespace

    42 {

    43 namespace util // codescanner::namespace

    44 {

    45 class DynamicLibLoader;

    46 } // end namespace util

    47 

    48 namespace runtime // codescanner::namespace

    49 {

    50 

    51 /**

    52  * This class is responsible for starting the MIDP runtime. It should be noted

    53  * that all the thread critical state changes must be done using thread safe

    54  * method doStateChange.

    55  */

    56 

    57 OS_NONSHARABLE_CLASS(MidpRuntimeStarter) : public ApplicationInfo,

    58         public ApplicationStateController,

    59         public java::comms::CommsListener,

    60         public MidpStarterPushSupport,

    61         public MidpStarterInternalSupport

    62 {

    63 public:

    64 

    65     /**

    66      * Constructor of the MidpRuntimeStarter.

    67      */

    68     MidpRuntimeStarter();

    69 

    70     /**

    71      * Destructor of the MidpRuntimeStarter.

    72      */

    73     ~MidpRuntimeStarter(); // Not to be inherited, so can be non virtual.

    74 

    75     /**

    76      * Starts the MIDP runtime according to given arguments. Unknown argument

    77      * will lead to throwing java::runtime::RuntimeException.

    78      * @param argc Count of the arguments.

    79      * @param argv An array of arguments. The accepted arguments are in the

    80      *             midpruntimearguments.h file.

    81      * @return Status of the method call - 0 on success case.

    82      * @throws std::exception, java::runtime::RuntimeException or

    83      *         java::util::ExceptionBase on error cases.

    84      *

    85      */

    86     int start(int argc, char *argv[]);

    87 

    88     // From ApplicationStateController.

    89 

    90     /**

    91      * To be removed...

    92      */

    93     virtual void ApplicationStateChangeRequest(ApplicationState state);

    94 

    95     /**

    96      * Implementation of method startMidletRequestFromPush from interface

    97      * MidpStarterPushSupport

    98      * @see midpruntimepushsupport.h.

    99      */

   100     virtual void

   101     startMidletRequestFromPush(const std::wstring& pushAdditionalInfo);

   102 

   103     /**

   104      * Implementation of method closeRuntimeRequestFromPush from interface

   105      * MidpStarterPushSupport

   106      * @see midpruntimepushsupport.h.

   107      */

   108     virtual void closeRuntimeRequestFromPush();

   109 

   110     /**

   111      * Implementation of method closeRuntimeInd from interface

   112      * MidpStarterInternalSupport

   113      * @see midpruntimeinternalsupport.h.

   114      */

   115     virtual void closeRuntimeInd();

   116 

   117     /**

   118      * Implementation of method setUid from interface

   119      * MidpStarterInternalSupport

   120      * @see midpruntimeinternalsupport.h.

   121      */

   122     virtual void setUids(const java::util::Uid& midletUid,

   123                          const java::util::Uid& midletSuiteUid);

   124 

   125     /**

   126      * Implementation of method getRootPath from interface

   127      * ApplicationInfo

   128      * @see applicationinfo.h.

   129      */

   130     virtual const std::wstring& getRootPath() const;

   131 

   132     /**

   133      * Implementation of method getRootPath from interface

   134      * ApplicationInfo

   135      * @see applicationinfo.h.

   136      */

   137     virtual const java::util::Uid& getUid() const;

   138 

   139     /**

   140      * Implementation of method processMessage from interface

   141      * java::comms::CommsListener. This method will process all the

   142      * RTC messages received from the Java Captain.

   143      * @see commslistener.h

   144      */

   145     virtual void processMessage(java::comms::CommsMessage& aMessage);

   146 

   147 

   148 

   149 private: // Definitions

   150 

   151     /**

   152      * States of the runtime starter.

   153      */

   154     enum State // codescanner::enummembers::enumnames

   155     {

   156         /**

   157          * The object is created and initializations have been started.

   158          */

   159         Constructed = 0x1,

   160 

   161         /**

   162          * The starter is in push listening state. The JVM has not been

   163          * started.

   164          */

   165         PushListen = 0x2,

   166 

   167         /**

   168          * The JVM is started and Java peer is active. This doesn't mean

   169          * that the MIDlet is running. The Java peer can be in pre warmed

   170          * state waiting for the start request from Java Captain.

   171          */

   172         Active      = 0x4,

   173 

   174         /**

   175          * The starter has received request to shut down the process.

   176          */

   177         Closing     = 0x8

   178     };

   179 

   180     /**

   181      * State change request to the runtime starter.

   182      */

   183     enum StateChangeRequest // codescanner::enummembers::enumnames

   184     {

   185         /**

   186          * Start the MIDlet

   187          */

   188         Start = 0x1,

   189 

   190         /**

   191          * Stop the MIDlet

   192          */

   193         Stop  = 0x2

   194     };

   195 

   196     /**

   197      * A utility class (struct) for containing MIDlet specific information.

   198      */

   199     OS_NONSHARABLE_CLASS(MidletInfo)

   200     {

   201 public:

   202         /**

   203          * Constructor.

   204          */

   205         MidletInfo(): mPushStart(false),

   206                 mPreWarmStart(false),

   207                 mAutoInvocationRequested(false),

   208                 mDebugRequested(false),

   209                 mMIDletHasArgs(false),

   210                 mBackGroundRequested(false) {}

   211 

   212 public:

   213         /**

   214          * The UID of the MIDlet.

   215          */

   216         java::util::Uid mMIDletUid;

   217 

   218         /**

   219         * The UID of the MIDlet Suite.

   220         */

   221         java::util::Uid mMIDletSuiteUid;

   222 

   223 

   224         /**

   225          * The defined UI orientation of the MIDlet.

   226          */

   227         std::wstring mMidletSplashScreenAttribute;

   228 

   229         /**

   230           * The classpath of the MIDlet.

   231           */

   232         std::wstring    mClassPath;

   233 

   234         /**

   235          * The rootpath of the MIDlet.

   236          */

   237         std::wstring    mMIDletRootPath;

   238 

   239         /**

   240          * The recorded intial heap size of the MIDlet.

   241          */

   242         std::wstring    mMIDletHeapInitalSize;

   243 

   244         /**

   245          * Should start to push listen mode.

   246          */

   247         bool            mPushStart;

   248 

   249         /**

   250          * Should start to pre warm listen mode.

   251          */

   252         bool            mPreWarmStart;

   253 

   254         /**

   255          * Is the start result of auto invocation.

   256          */

   257         bool            mAutoInvocationRequested;

   258 

   259         /**

   260          * Should the debugging features be enabled.

   261          */

   262         bool            mDebugRequested;

   263 

   264         /**

   265          * Has the MIDlet been started with command line args

   266          */

   267         bool            mMIDletHasArgs;

   268 

   269         /**

   270          * Is the start such that request the UI to go to back ground.

   271          */

   272         bool            mBackGroundRequested;

   273 

   274         /**

   275          * The arguments of the MIDlet if any

   276          */

   277         std::wstring    mMIDletArgs;

   278     };

   279 

   280 private: // Methods

   281 

   282     /**

   283      * Parses the arguments provided by Java Captain when creating the

   284      * process. The argument interpretations are stored into a member variable

   285      * mMidletInfo for easy future access. Any Unknown argument

   286      * will lead to throwing java::runtime::RuntimeException.

   287      * @param argc Count of the arguments.

   288      * @param argv An array of arguments. The accepted arguments are in the

   289      *             midpruntimearguments.h file.

   290      * @throws std::exception, java::runtime::RuntimeException or

   291      *         java::util::ExceptionBase on error cases.

   292      */

   293     void parseArgs(int argc, char *argv[]);

   294 

   295     /**

   296      * Starts the core UI.

   297      * @param[out] coreUiLoader A dynamic lib loader for loading

   298      *                          dynamically the coreui lib.

   299      * @throws std::exception, java::runtime::RuntimeException or

   300      *         java::util::ExceptionBase on error cases.

   301      */

   302     void startCoreUi(std::auto_ptr<java::util::DynamicLibLoader>& coreUiLoader);

   303 

   304     /**

   305      * Initailizes comms connection to Java Captain. If it fails then

   306      * RuntimeException will be thrown.

   307      * @throws std::exception, java::runtime::RuntimeException or

   308      *         java::util::ExceptionBase on error cases.

   309      */

   310     void initComms();

   311 

   312     /**

   313      * Does the state change in the the MIDP runtime starter.

   314      * This method is thread safe.

   315      * @throws std::exception, java::runtime::RuntimeException or

   316      *         java::util::ExceptionBase on error cases.

   317      */

   318     void doStateChange(StateChangeRequest request);

   319 

   320     /**

   321      * Finds MIDlet suite UID form the JavaStorage.

   322      * @param storage Opened session to JavaStorage.

   323      * @throws std::exception, java::runtime::RuntimeException or

   324      *         java::util::ExceptionBase on error cases.

   325      */

   326     void getMIDletSuiteUidFromStorage(java::storage::JavaStorage& storage);

   327 

   328     /**

   329      * Finds the value of given key from APPLICATION_PACKAGE_TABLE in

   330      * Java Storage. In this method will call a new session to Java Storage

   331      * is alway created. At the end of method the session is closed. The user

   332      * can provide already opened storage connection. If that is not available

   333      * the method will create a temp connection that will be closed when

   334      * exiting from the method.

   335      * @param storage Opened session to JavaStorage.

   336      * @param key A key to APPLICATION_PACKAGE_TABLE. Use constants defined in

   337      *            javastoragenames.h.

   338      * @param value A reference to wstring where to store the result. If the

   339      *              is unknown then RuntimeException will be thrown.

   340      * @throws std::exception, java::runtime::RuntimeException or

   341      *         java::util::ExceptionBase on error cases.

   342      */

   343     void getMIDletSuiteInfoFromStorage(java::storage::JavaStorage* storage,

   344                                        const std::wstring& key,

   345                                        std::wstring& value) const;

   346 

   347     /**

   348      * Finds the value of given key from APPLICATION_PACKAGE_ATTRIBUTES_TABLE

   349      * in Java Storage. This table contains all the MIDlet jad and jar manifest

   350      * arguments

   351      * @param storage Opened session to JavaStorage.

   352      * @param searchKey The key of the attribute to search.

   353      * @return A pointer to value. The user is responsible for deleting the

   354      *         pointer. 0 if value can't be found.

   355      * @throws std::exception, java::runtime::RuntimeException or

   356      *         java::util::ExceptionBase on error cases.

   357      */

   358     std::wstring*

   359     getMidletAttributeFromStorage(java::storage::JavaStorage& storage,

   360                                   const std::wstring& searchKey) const;

   361 

   362     /**

   363      * Utility for finding the value from the JavaStorageApplicationEntry_t

   364      * received from Java Storage.

   365      * @param entry A list of certain teble content.

   366      * @param key A key to table. Use constants defined in javastoragenames.h.

   367      * @return The value as wstring. If the key is unknown then

   368      *         RuntimeException will be thrown.

   369      * @throws std::exception, java::runtime::RuntimeException or

   370      *         java::util::ExceptionBase on error cases.

   371      */

   372     std::wstring

   373     getDbValue(const java::storage::JavaStorageApplicationEntry_t& entry,

   374                const std::wstring& key) const;

   375 

   376     /**

   377      * Starts to listen push connection. The actual listenin is done by the

   378      * Push framework which is initialized by this method.

   379      * @throws std::exception, java::runtime::RuntimeException or

   380      *         java::util::ExceptionBase on error cases.

   381      */

   382     void handlePushStart();

   383 

   384     /**

   385      * Delivers a close message to push framework in order to ensure proper

   386      * closing of certain push implementations.

   387      * @throws std::exception, java::runtime::RuntimeException or

   388      *         java::util::ExceptionBase on error cases.

   389      */

   390     void closePush();

   391 

   392     /**

   393      * If the default heap size has been recorded into file named as 'heap'

   394      * in the root of MIDlet's root path, then this method will return

   395      * the stored size in B.

   396      * return the default heap size in kB if available, otherwise -1.

   397      */

   398     int getHeapSize() const;

   399 

   400     /**

   401      * No copy constructor allowed

   402      */

   403     MidpRuntimeStarter(const MidpRuntimeStarter& starter);

   404 

   405     /**

   406      * No copy constructor allowed

   407      */

   408     MidpRuntimeStarter& operator= (const MidpRuntimeStarter& starter);

   409 

   410     /**

   411      * Encode string to a private format that is safe to pass to Java side

   412      * as a Java system property.

   413      * Java side function com.nokia.mj.impl.rt.midp.MidletLifeCycle::decodeArgs

   414      * is used to decode the string

   415      *

   416      * @param args original wstring

   417      * @return encoded wstring

   418      */

   419     std::wstring encodeArgs(const std::wstring& args);

   420 

   421 private: //Members

   422     /**

   423      * Comms client endpoint towards Java Captain.

   424      */

   425     std::auto_ptr<java::comms::CommsClientEndpoint> mComms;

   426 

   427     /**

   428      * For caching important MIDlet specific data.

   429      */

   430     std::auto_ptr<MidletInfo>                       mMidletInfo;

   431 

   432     /**

   433      * Utility for making methods thread safe.

   434      */

   435     java::util::ScopedMutex                         mProcessesMutex;

   436 

   437     /**

   438      * The state of the MIDP starter.

   439      */

   440     int                                             mRuntimeState;

   441 

   442     /**

   443      * A lock for push wait case.

   444      */

   445     std::auto_ptr<java::util::Monitor>              mMonitor;

   446 

   447     /**

   448      * A library loader for push case.

   449      */

   450     std::auto_ptr<java::util::DynamicLibLoader>     mPushLib;

   451 

   452     /**

   453      * Utility for making methods thread safe.

   454      */

   455     std::wstring                                    mPushAdditionalInfo;

   456 

   457 };

   458 

   459 } // end namespace runtime

   460 } // end namespace java

   461 

   462 #endif // MIDPRUNTIMESTARTER_H