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 interface is meant for used when starting the JVM.

    15 *

    16 */

    17 

    18 

    19 #ifndef JVMSTARTER_H

    20 #define JVMSTARTER_H

    21 

    22 #include "javaoslayer.h"

    23 

    24 #include <string>

    25 #include <map>

    26 

    27 namespace java // codescanner::namespace

    28 {

    29 

    30 namespace runtime // codescanner::namespace

    31 {

    32 

    33 /**

    34  * This class is responsible for generalizing the start of the platform

    35  * specfic JVM. It provides a set of methods that can be used in platform

    36  * agnostic way when setting certain arguments passed to the JVM. It also

    37  * includes a set of methods that assume that the caller sets the arguments

    38  * in platform specific format.

    39  * <p>

    40  * By default the starter sets JVM specific arguments that are optimized

    41  * for the MIDPruntime. However the class provides methods for overriding

    42  * these arguments.

    43  * <p>

    44  * There are two ways to start the JVM. The recommended way is to first

    45  * set the arguments using the setter and append methods and the start the

    46  * JVM. Using this approach there is limited need to implement platform

    47  * dependent code. This approach also supports the argument modification

    48  * from some external source during runtime. The other way to start the

    49  * JVM is to directly start the JVM with platform specific arguments. In this

    50  * case the arguments are passed directly to JVM wihtout any extra processing.

    51  * <p>

    52  * Possibility of overriding JVM arguments during runtime from external source:

    53  * This feature allows user to modify set of JVM arguments. Before starting

    54  * the JVM, JvmStarter tries to load javavmargsmodifier plugin. If the

    55  * loading succeeds, then the plugin is able to provide a list of arguments

    56  * to be appended or overridden. The actual overriging is done by the

    57  * starter. It has a control whether to accept the modifications or not.

    58  * An identifier is a passed to the plugin in order to be able to variate

    59  * the behavior depending on the runtime. The runtime can be e.g. MIDP,

    60  * installer, TCK runner or someone else.

    61  * main() method.

    62  * <p>

    63  * Setting JVM into debug mode:

    64  * This feature seemless to the JvmStarter. It is responsibility of the

    65  * Runtime specific starter to append the debug arguments using the

    66  * appendRawJvmArgument() method.

    67  * <p>

    68  * JvmStarter is not thread safe.

    69  * <p>

    70  * Usage of approach 1:

    71  * @code

    72  * std::auto_ptr<JvmStarter> jvm

    73  *            (JvmStarter::getJvmStarterInstance(JvmStarter::CLDC, L"Midp"));

    74  * std::wstring classPath(getMidletClassPath());

    75  * jvm->appendClassPath(classPath);

    76  * jvm->appendSystemProperty(L"-Dcom.nokia.legacy.support=symbian");

    77  * jvm->appendApplicationArgument(L"arg1");

    78  * jvm->appendApplicationArgument(L"arg2");

    79  * jvm->appendApplicationArgument(L"arg3");

    80  * jvm->appendApplicationArgument(L"arg4");

    81  * int status = jvm->startJvm();

    82  * return status;

    83  * @endcode

    84  * <p>

    85  * Usage of approach 2:

    86  * @code

    87  * std::auto_ptr<JvmStarter> jvm

    88  *          (JvmStarter::getJvmStarterInstance(JvmStarter::CDC, L"CDC_MAIN"));

    89  * std::vector<char*> args;

    90  * args.push_back("c:\\");

    91  * args.push_back("-jcl:cdc11");

    92  * args.push_back("-classpath");

    93  * ScopedCharArray cp(JavaCommonUtils::wstringToUtf8(getClassPath()));

    94  * args.push_back(cp);

    95  * ScopedCharArray className(JavaCommonUtils::wstringToUtf8(getClassName()));

    96  * args.push_back(className);

    97  * args.push_back("App arg1 in UTF-8");

    98  * args.push_back("App arg2 in UTF-8");

    99  * const char** argv = &((args)[0]);

   100  * int argCount = args.size();

   101  * int status = jvm->startJvm(argCount, argv);

   102  * return status;

   103  * @endcode

   104  */

   105 

   106 

   107 OS_NONSHARABLE_CLASS(JvmStarter)

   108 {

   109 public:

   110     /**

   111     * Enum for defining the used configuration for the JVM

   112     */

   113     enum Configuration // codescanner::enummembers::enumnames

   114     {

   115         CLDC,

   116         CDC,

   117         FOUNDATION,

   118         UNDEFINED

   119     };

   120 

   121     /**

   122      * Creates a platform dependent JvmStarter implementation. This method

   123      * should be used when approach 1 is selected.

   124      * @param configuration Used configuration.

   125      * @param indetifier A string identifier for different runtimes. This

   126      *        identifier is passed to the JVM args modifier.

   127      * @return valid pointer to JvmStarter instance. The platform specific

   128      *         default arguments have been set.

   129      * @throws std::exception on error cases

   130      */

   131     OS_IMPORT static JvmStarter*

   132     getJvmStarterInstance(const Configuration configuration,

   133                           const std::wstring& indetifier);

   134 

   135     /**

   136      * Creates a platform dependent JvmStarter implementation. This method

   137      * should be used when approach 2 is selected.

   138      * @return valid pointer to JvmStarter instance.

   139      * @throws std::exception on error cases

   140      */

   141     OS_IMPORT static JvmStarter* getJvmStarterInstance();

   142 

   143     /**

   144      * Destructor of the JvmStarter.

   145      */

   146     virtual ~JvmStarter() {}

   147 

   148     /**

   149      * Appends the provided file to the classpath. It is responsisbility of

   150      * the user to provide fully qualified classpath. The path separator

   151      * can be either '/' or '\' - the method will convert it to correct

   152      * format.

   153      * @param file Fully qualified file name to be appended to classpath.

   154      *             Assumed character encoding is UCS-2.

   155      * @throws std::exception on error cases

   156      */

   157     virtual void appendClassPath(const std::wstring& file) = 0;

   158 

   159     /**

   160      * Appends the provided file to the bootclasspath. The rules in

   161      * method appendClassPath() are also valid for this method.

   162      * @param file Fully qualified file name to be appended

   163      *             to bootclasspath.

   164      *             Assumed character encoding is UCS-2.

   165      * @throws std::exception on error cases

   166      */

   167     virtual void appendBootClassPath(const std::wstring& file) = 0;

   168 

   169     /**

   170      * Prepends the provided file to the bootclasspath. The rules in

   171      * method appendClassPath() are also valid for this method.

   172      * @param file Fully qualified file name to be appended

   173      *             to bootclasspath.

   174      *             Assumed character encoding is UCS-2.

   175      * @throws std::exception on error cases

   176      */

   177     virtual void prependBootClassPath(const std::wstring& file) = 0;

   178 

   179     /**

   180      * Appends the provided fully qualified path to be part of the extension

   181      * path of the JVM. The path separator can be either '/' or '\' -

   182      * the method will convert it to platform specific format.

   183      *

   184      * @param file Fully qualified file name to be appended

   185      *             to extension path.

   186      *             Assumed character encoding is UCS-2.

   187      * @throws std::exception on error cases

   188      */

   189     virtual void appendExtensionPath(const std::wstring& extensionPath) = 0;

   190 

   191     /**

   192      * Sets the main class of the runtime to be started.

   193      * The package seprator is '.'

   194      * @param mainClass The Java class containing the main() method to be

   195      *                  invoked.

   196      *                  Assumed character encoding is UCS-2.

   197      * @throws std::exception on error cases

   198      */

   199     virtual void setMainClass(const std::wstring& mainClass) = 0;

   200 

   201     /**

   202      * Appens argument that are the arguments of the Java main() method.

   203      * @param argument Argument to be appended.

   204      *                 Assumed character encoding is UCS-2.

   205      * @throws std::exception on error cases

   206      */

   207     virtual void appendApplicationArgument(const std::wstring& argument) = 0;

   208 

   209     /**

   210      * Adds system property. The property must be in format '-D<key>[:value]

   211      * @param systemproperty System property to be added.

   212      *                       Assumed character encoding is UCS-2.

   213      * @throws std::exception on error cases

   214      */

   215     virtual void appendSystemProperty(const std::wstring& systemproperty) = 0;

   216 

   217     /**

   218      * Starts the JVM. Before this method is called all the necessary

   219      * initializations must have been done. The method will block until the

   220      * JVM is shut down. If the JVM is not able to shut down

   221      * because some non daemon java thread is blocking the shut down, this

   222      * method will never return.

   223      * @return The status of the main method returned by the JVM

   224      * @throws std::exception on error cases

   225      */

   226     virtual int startJvm() = 0;

   227 

   228     /**

   229      * Starts the JVM with specified arguments. This call leads directly

   230      * launching the platform specific JVM. Caller of this method is

   231      * responsible for setting the arguments in correct JVM specific format.

   232      * The used encoding of the arguments is UTF-8. This is a raw way to

   233      * start the JVM. There usage of the other argument setter methods have

   234      * no effect to the arguments. The support of modifying the arguments

   235      * from some external source is not supported when this method is called.

   236      * The method will block until the JVM is shut down. If the JVM is not

   237      * able to shut down because some non daemon java thread is blocking

   238      * the shut down, this method will never return.

   239      * @param argc The number of the arguments.

   240      * @param argv Array of UTF-8 encoded char arrays.

   241      * @return The status of the main method returned by the JVM

   242      * @throws std::exception on error cases

   243      */

   244     virtual int startJvm(int argc, char** argv) = 0;

   245 

   246     /**

   247      * Overrides the default old heap size.

   248      * @param heapSize Heap size in kilo bytes.

   249      * @throws std::exception on error cases

   250      */

   251     virtual void overrideOldHeapSize(int heapSize) = 0;

   252 

   253     /**

   254      * Overrides the default new heap size.

   255      * @param heapSize Heap size in kilo bytes.

   256      * @throws std::exception on error cases

   257      */

   258     virtual void overrideNewHeapSize(int heapSize) = 0;

   259 

   260     /**

   261      * Overrides the default stack of the native thread.

   262      *

   263      * @param stackSize Stack size in kilo bytes.

   264      * @throws std::exception on error cases

   265      */

   266     virtual void overrideNativeStackSize(int stackSize) = 0;

   267 

   268     /**

   269      * Overrides the default stack of the java thread.

   270      *

   271      * @param stackSize Stack size in kilo bytes.

   272      * @throws std::exception on error cases

   273      */

   274     virtual void overrideJavaStackSize(int stackSize) = 0;

   275 

   276     /**

   277      * Adds or overwrites the defined JVM argument. It is reponsibility

   278      * of the caller that the passed argument is supported by the used

   279      * JVM.

   280      *

   281      * @param argument JVM argument.

   282      * @throws std::exception on error cases

   283      */

   284     virtual void appendRawJvmArgument(const std::wstring& argument) = 0;

   285 

   286     /**

   287      * Sets the VM to run without JIT

   288      */

   289     virtual void disableJit() = 0;

   290 

   291     /**

   292      * Enables thread dumping feature if possible.

   293      */

   294     virtual void enableThreadDumping() = 0;

   295 };

   296 

   297 } // end namespace runtime

   298 } // end namespace java

   299 

   300 

   301 #endif // JVMSTARTER_H