diff -r f5050f1da672 -r 04becd199f91 javaruntimes/starterutils/inc/jvmstarter.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/javaruntimes/starterutils/inc/jvmstarter.h Tue Apr 27 16:30:29 2010 +0300 @@ -0,0 +1,301 @@ +/* +* 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: This interface is meant for used when starting the JVM. +* +*/ + + +#ifndef JVMSTARTER_H +#define JVMSTARTER_H + +#include "javaoslayer.h" + +#include +#include + +namespace java // codescanner::namespace +{ + +namespace runtime // codescanner::namespace +{ + +/** + * This class is responsible for generalizing the start of the platform + * specfic JVM. It provides a set of methods that can be used in platform + * agnostic way when setting certain arguments passed to the JVM. It also + * includes a set of methods that assume that the caller sets the arguments + * in platform specific format. + *

+ * By default the starter sets JVM specific arguments that are optimized + * for the MIDPruntime. However the class provides methods for overriding + * these arguments. + *

+ * There are two ways to start the JVM. The recommended way is to first + * set the arguments using the setter and append methods and the start the + * JVM. Using this approach there is limited need to implement platform + * dependent code. This approach also supports the argument modification + * from some external source during runtime. The other way to start the + * JVM is to directly start the JVM with platform specific arguments. In this + * case the arguments are passed directly to JVM wihtout any extra processing. + *

+ * Possibility of overriding JVM arguments during runtime from external source: + * This feature allows user to modify set of JVM arguments. Before starting + * the JVM, JvmStarter tries to load javavmargsmodifier plugin. If the + * loading succeeds, then the plugin is able to provide a list of arguments + * to be appended or overridden. The actual overriging is done by the + * starter. It has a control whether to accept the modifications or not. + * An identifier is a passed to the plugin in order to be able to variate + * the behavior depending on the runtime. The runtime can be e.g. MIDP, + * installer, TCK runner or someone else. + * main() method. + *

+ * Setting JVM into debug mode: + * This feature seemless to the JvmStarter. It is responsibility of the + * Runtime specific starter to append the debug arguments using the + * appendRawJvmArgument() method. + *

+ * JvmStarter is not thread safe. + *

+ * Usage of approach 1: + * @code + * std::auto_ptr jvm + * (JvmStarter::getJvmStarterInstance(JvmStarter::CLDC, L"Midp")); + * std::wstring classPath(getMidletClassPath()); + * jvm->appendClassPath(classPath); + * jvm->appendSystemProperty(L"-Dcom.nokia.legacy.support=symbian"); + * jvm->appendApplicationArgument(L"arg1"); + * jvm->appendApplicationArgument(L"arg2"); + * jvm->appendApplicationArgument(L"arg3"); + * jvm->appendApplicationArgument(L"arg4"); + * int status = jvm->startJvm(); + * return status; + * @endcode + *

+ * Usage of approach 2: + * @code + * std::auto_ptr jvm + * (JvmStarter::getJvmStarterInstance(JvmStarter::CDC, L"CDC_MAIN")); + * std::vector args; + * args.push_back("c:\\"); + * args.push_back("-jcl:cdc11"); + * args.push_back("-classpath"); + * ScopedCharArray cp(JavaCommonUtils::wstringToUtf8(getClassPath())); + * args.push_back(cp); + * ScopedCharArray className(JavaCommonUtils::wstringToUtf8(getClassName())); + * args.push_back(className); + * args.push_back("App arg1 in UTF-8"); + * args.push_back("App arg2 in UTF-8"); + * const char** argv = &((args)[0]); + * int argCount = args.size(); + * int status = jvm->startJvm(argCount, argv); + * return status; + * @endcode + */ + + +OS_NONSHARABLE_CLASS(JvmStarter) +{ +public: + /** + * Enum for defining the used configuration for the JVM + */ + enum Configuration // codescanner::enummembers::enumnames + { + CLDC, + CDC, + FOUNDATION, + UNDEFINED + }; + + /** + * Creates a platform dependent JvmStarter implementation. This method + * should be used when approach 1 is selected. + * @param configuration Used configuration. + * @param indetifier A string identifier for different runtimes. This + * identifier is passed to the JVM args modifier. + * @return valid pointer to JvmStarter instance. The platform specific + * default arguments have been set. + * @throws std::exception on error cases + */ + OS_IMPORT static JvmStarter* + getJvmStarterInstance(const Configuration configuration, + const std::wstring& indetifier); + + /** + * Creates a platform dependent JvmStarter implementation. This method + * should be used when approach 2 is selected. + * @return valid pointer to JvmStarter instance. + * @throws std::exception on error cases + */ + OS_IMPORT static JvmStarter* getJvmStarterInstance(); + + /** + * Destructor of the JvmStarter. + */ + virtual ~JvmStarter() {} + + /** + * Appends the provided file to the classpath. It is responsisbility of + * the user to provide fully qualified classpath. The path separator + * can be either '/' or '\' - the method will convert it to correct + * format. + * @param file Fully qualified file name to be appended to classpath. + * Assumed character encoding is UCS-2. + * @throws std::exception on error cases + */ + virtual void appendClassPath(const std::wstring& file) = 0; + + /** + * Appends the provided file to the bootclasspath. The rules in + * method appendClassPath() are also valid for this method. + * @param file Fully qualified file name to be appended + * to bootclasspath. + * Assumed character encoding is UCS-2. + * @throws std::exception on error cases + */ + virtual void appendBootClassPath(const std::wstring& file) = 0; + + /** + * Prepends the provided file to the bootclasspath. The rules in + * method appendClassPath() are also valid for this method. + * @param file Fully qualified file name to be appended + * to bootclasspath. + * Assumed character encoding is UCS-2. + * @throws std::exception on error cases + */ + virtual void prependBootClassPath(const std::wstring& file) = 0; + + /** + * Appends the provided fully qualified path to be part of the extension + * path of the JVM. The path separator can be either '/' or '\' - + * the method will convert it to platform specific format. + * + * @param file Fully qualified file name to be appended + * to extension path. + * Assumed character encoding is UCS-2. + * @throws std::exception on error cases + */ + virtual void appendExtensionPath(const std::wstring& extensionPath) = 0; + + /** + * Sets the main class of the runtime to be started. + * The package seprator is '.' + * @param mainClass The Java class containing the main() method to be + * invoked. + * Assumed character encoding is UCS-2. + * @throws std::exception on error cases + */ + virtual void setMainClass(const std::wstring& mainClass) = 0; + + /** + * Appens argument that are the arguments of the Java main() method. + * @param argument Argument to be appended. + * Assumed character encoding is UCS-2. + * @throws std::exception on error cases + */ + virtual void appendApplicationArgument(const std::wstring& argument) = 0; + + /** + * Adds system property. The property must be in format '-D[:value] + * @param systemproperty System property to be added. + * Assumed character encoding is UCS-2. + * @throws std::exception on error cases + */ + virtual void appendSystemProperty(const std::wstring& systemproperty) = 0; + + /** + * Starts the JVM. Before this method is called all the necessary + * initializations must have been done. The method will block until the + * JVM is shut down. If the JVM is not able to shut down + * because some non daemon java thread is blocking the shut down, this + * method will never return. + * @return The status of the main method returned by the JVM + * @throws std::exception on error cases + */ + virtual int startJvm() = 0; + + /** + * Starts the JVM with specified arguments. This call leads directly + * launching the platform specific JVM. Caller of this method is + * responsible for setting the arguments in correct JVM specific format. + * The used encoding of the arguments is UTF-8. This is a raw way to + * start the JVM. There usage of the other argument setter methods have + * no effect to the arguments. The support of modifying the arguments + * from some external source is not supported when this method is called. + * The method will block until the JVM is shut down. If the JVM is not + * able to shut down because some non daemon java thread is blocking + * the shut down, this method will never return. + * @param argc The number of the arguments. + * @param argv Array of UTF-8 encoded char arrays. + * @return The status of the main method returned by the JVM + * @throws std::exception on error cases + */ + virtual int startJvm(int argc, char** argv) = 0; + + /** + * Overrides the default old heap size. + * @param heapSize Heap size in kilo bytes. + * @throws std::exception on error cases + */ + virtual void overrideOldHeapSize(int heapSize) = 0; + + /** + * Overrides the default new heap size. + * @param heapSize Heap size in kilo bytes. + * @throws std::exception on error cases + */ + virtual void overrideNewHeapSize(int heapSize) = 0; + + /** + * Overrides the default stack of the native thread. + * + * @param stackSize Stack size in kilo bytes. + * @throws std::exception on error cases + */ + virtual void overrideNativeStackSize(int stackSize) = 0; + + /** + * Overrides the default stack of the java thread. + * + * @param stackSize Stack size in kilo bytes. + * @throws std::exception on error cases + */ + virtual void overrideJavaStackSize(int stackSize) = 0; + + /** + * Adds or overwrites the defined JVM argument. It is reponsibility + * of the caller that the passed argument is supported by the used + * JVM. + * + * @param argument JVM argument. + * @throws std::exception on error cases + */ + virtual void appendRawJvmArgument(const std::wstring& argument) = 0; + + /** + * Sets the VM to run without JIT + */ + virtual void disableJit() = 0; + + /** + * Enables thread dumping feature if possible. + */ + virtual void enableThreadDumping() = 0; +}; + +} // end namespace runtime +} // end namespace java + + +#endif // JVMSTARTER_H