/*
* 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:  Utilities for starting the Java runtime.
*
*/


#ifndef RUNTIMESTARTERUTILS_H
#define RUNTIMESTARTERUTILS_H

#include <string>
#include "javaoslayer.h"
#include "jvmstarter.h"

namespace java // codescanner::namespace
{

namespace comms // codescanner::namespace
{
class CommsClientEndpoint;
}

namespace runtime // codescanner::namespace
{

class OsThreadSupervisor;
class DevelopmentFeaturesListener;

/**
 * This class is responsible for providing utilies related to starting
 * the javaruntime.
 */
OS_NONSHARABLE_CLASS(RuntimeStarterUtils)
{
public:

    /**
     * Constructor of the RuntimeStarterUtils.
     */
    OS_IMPORT RuntimeStarterUtils();

    /**
     * Destructor of the RuntimeStarterUtils. Will destroy the instance of
     * comms client endpoint if has been created by this object. The class
     * is not meant to be inherited, so destructor can be non virtual.
     */
    OS_IMPORT ~RuntimeStarterUtils();

    /**
     * Creates a platform dependent thread supervisor for detecting thread
     * panics. When the thread supervisioning is enabled, any panicing thread
     * belonging to this process will lead to termination of the process.
     * At least in Symbian it is important to enable this feature. Panic of
     * one thread doesn't automatically lead to termination of the whole
     * process.
     * <p>
     * The lifetime of the supervisor is tight to existence of instance of
     * this class. Once the object is destroyed, alos the supervisor is
     * terminated.
     * @param tryThreadDumping Whether to try to do thread dump in panic case.
     *                         Might cause another panic.
     * @throws std::exception on error cases.
     */
    OS_IMPORT void startThreadSupervisor(bool tryThreadDumping = false);

    /**
     * This method will enable various kind of development features - like
     * debugging, profiling and thread dumping. At the moment all these
     * development features are to some extent controlled by Java Captain.
     * This is natural to MIDP runtime but a little problematic to non-managed
     * runtimes like Installer and TCK runner. Captain is not aware of these
     * non-managed runtimes.
     * <p>
     * This method will make a comms connection to Java Captain if it doesn't.
     * exist. For determining the existence it will search if a named comms
     * client endpoint is already created with name "javacaptain". If it
     * doesn't, then a new one is created. The endpoint is used when
     * generating thread dumps. Java Captain will deliver dump message to
     * all the running Java process that it is aware of.
     * <p>
     * Internally this method will ask from Java Captain if there are some
     * extra arguments to be provided to the JVM (if onlyThreadDump is set
     * to false). Those parameters can be
     * related e.g to debugging, profiling or something else.
     * <p>
     * The method will add a new lister to listen to thread dump messages from
     * Java Captain.
     * <p>
     * Note! If this method needs to create a new instance of comms client
     * endpoint, the exitence of endpoint is tight to existence of instance
     * of RuntimeUtils object. I.e. the endpoint is destroyd when the
     * destructor is called.
     * @param jvmStarter. User must provide a valid reference to JvmStarter.
     *                    This method will append certain JVM arguments
     *                    if some development features are set on. The
     *                    same JvmStarter must be used for starting the JVM.
     * @param askForArgs. If set to false, only thread dumping listening
     *                    is enabled and no message is sent to Captain.
     * @param applicationArgs. If askForArgs is true, this paramater must
     *                         point to a wstring. The arguments for the
     *                         application to be started will be returned in
     *                         the wstring.
     */
    OS_IMPORT void enableDevelopmentFeatures(JvmStarter& jvmStarter,
            bool askForArgs = false,
            std::wstring *applicationArgs = NULL);
    /**
     * Finds the add-on JSRs from platform dependent repository.
     * @param extendedBootClassPath a refernce to wstring where the method can store
     *                              the boot classpath. If the there are no add-on JSRs,
     *                              this will be empty wstring.
     */
    OS_IMPORT void getExtBootClassPath(std::wstring& extendedBootClassPath);

private: // Classes

private: // Methods.

    /*
     * No copy constructor allowed.
     */
    RuntimeStarterUtils(const RuntimeStarterUtils&);

    /*
     * No Assignment operator allowed.
     */
    RuntimeStarterUtils& operator= (const RuntimeStarterUtils&);

    void addRuntimeArguments(const std::wstring& aRuntimeArgs, JvmStarter& jvmStarter);

private: // Member variables.
    java::comms::CommsClientEndpoint* mComms;
    OsThreadSupervisor*               mSupervisor;
    DevelopmentFeaturesListener*      mListener;
};

} // end namespace runtime
} // end namespace java


#endif // RUNTIMESTARTERUTILS_H