--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/javaruntimes/starterutils/inc/jvmstarter.h Mon May 03 12:27:20 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 <string>
+#include <map>
+
+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.
+ * <p>
+ * By default the starter sets JVM specific arguments that are optimized
+ * for the MIDPruntime. However the class provides methods for overriding
+ * these arguments.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * JvmStarter is not thread safe.
+ * <p>
+ * Usage of approach 1:
+ * @code
+ * std::auto_ptr<JvmStarter> 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
+ * <p>
+ * Usage of approach 2:
+ * @code
+ * std::auto_ptr<JvmStarter> jvm
+ * (JvmStarter::getJvmStarterInstance(JvmStarter::CDC, L"CDC_MAIN"));
+ * std::vector<char*> 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<key>[: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