/*

* Copyright (c) 2008 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:

*

*/

package com.nokia.mj.impl.rt.support;

import com.nokia.mj.impl.rt.JvmPort;

/**

 * Provides JVM utilities <b>only</b> for Java runtime implementations to use.

 * Some of these

 * utilities hide differences between CLDC and CDC configurations and some

 * provide completely non-standard access to JVM features and to process memory.

 * <p>

 * Example how to enable System.exit() funtionality.

 * <pre>

 * package com.nokia.mj.impl.mypackage;

 *

 * import com.nokia.mj.impl.rt.support;

 *      public void myClass()

 *      {

 *          public void myMethod()

 *          {

 *              //loads the system library.

 *              JvmInternal.enableRuntimeExit();

 *

 *              //my implementation...

 *          }

 *      }

 * </pre>

 * @author Nokia Corporation

 * @version 1.0

 */

public class JvmInternal

{

    /**

     * Enables ability to use methods <code>System.exit</code> and

     * <code>Runtime.exit</code>.

     * MIDP requires that if MIDlet tries to call <code>System.exit</code>

     * or <code>Runtime.exit</code>. If this is prevented by calling method

     * {@link JvmInternal#disableRuntimeExit} either runtime implementation is not allowed

     * to call the <code>exit</code> methods. Calling

     * <code>enableRuntimeExit</code> removes the prevention.

     */

    public static void enableRuntimeExit()

    {

        JvmPort.getInstance().enableRuntimeExit();

    }

    /**

     * Disables ability to use methods <code>System.exit</code> and

     * <code>Runtime.exit</code>.

     * MIDP requires that if MIDlet tries to call <code>System.exit</code>

     * or <code>Runtime.exit</code>. If this is prevented it can be released

     * using {@link JvmInternal#enableRuntimeExit} method.

     */

    public static void disableRuntimeExit()

    {

        JvmPort.getInstance().disableRuntimeExit();

    }

    /**

     * Terminates forcefully JVM process. This method is used to

     * forcefully terminate the process running the JVM. It should

     * be used if the graceful shutdown cant be done.

     * <p>

     * It should be noted that after calling this method the process

     * terminates. So if there are any necessary action related to the

     * shut down, those should be done before calling this method.

     *

     * @param status The exit status.

     */

    public static void exitVm(int status)

    {

        JvmPort.getInstance().exitVm(status);

    }

    /**

     * Enables finalization for given class.

     * @param clazz The class to be finalized.

     */

    public static void enableFinalization(Class clazz)

    {

        JvmPort.getInstance().enableFinalization(clazz);

    }

    /**

     * Runs the finalization methods of any objects pending finalization.

     * This method uses <code>System.runFinalization</code> in CDC based

     * configurations while in CLDC a proprieatary API is used.

     */

    public static void runFinalization()

    {

        JvmPort.getInstance().runFinalization();

    }

    /**

     * Cleans the young generation heap. The use JVM might not support

     * cleaning of the young generation heap.

     * @return True if running youngGenerationGc is supported, otherwise

     * false

     */

    public static boolean runYoungGenerationGc()

    {

        return JvmPort.getInstance().runYoungGenerationGc();

    }

    /**

     * Registers a ThreadEventListener to receive notifications about Java

     * thread events. There can be at most one registered listener at time

     * - new registration replaces the old one and null can be used to clear

     * the registration completely.

     * <p>

     * The registered listener will be notified on each subsequent Thread

     * creation, Thread death, and uncaught exceptions.

     *

     * @param listener the Listener or null to clear the active listener

     */

    public static void setThreadEventListener(ThreadEventListener listener)

    {

        JvmPort.getInstance().setThreadEventListener(listener);

    }

    /**

     * JAVADOCS ARE UNDER CONSTRUCTION!!

     * <p>

     * Sets package names to the list of restricted packages. Normally the

     * package names should end with '.' to avoid matching word prefixes.

     * For example, using "com.nokia" as a restricted package name restricts

     * "com.nokiapkg.*", while restricting "com.nokia." does not.

     *

     * @param packageNames an array of package names to restrict

     * @throws SecurityException if one of the restricted package names

     * is a prefix of the name of a class being loaded

     */

    public static void addRestrictedPackagePrefixes(String[] packageNames)

    throws SecurityException

    {

        JvmPort.getInstance().addRestrictedPackagePrefixes(packageNames);

    }

    /**

     * JAVADOCS ARE UNDER CONSTRUCTION!!

     * <p>

     * Sets package names to the list of protected packages. Normally the

     * package names should end with '.' to avoid matching word prefixes.

     * For example, using "com.nokia" as a protected package name protectets

     * "com.nokiapkg.*", while protecting "com.nokia." does not.

     *

     * @param packageNames an array of package names to restrict

     * @throws SecurityException if one of the restricted package names

     * is a prefix of the name of a class being loaded

     */

    public static void addProtectedPackagePrefixes(String[] packageNames)

    throws SecurityException

    {

        JvmPort.getInstance().addProtectedPackagePrefixes(packageNames);

    }

    /**

     * Appends the given path to class path.

     */

    public static void appendToClassPath(String path)

    {

        JvmPort.getInstance().appendToClassPath(path);

    }

    /**

     * Adds the defined system property containing all the user

     * properties. This will not override any system properies.

     * The semanitc is equivalent to Hashtable.put() method.

     * @param key a key.

     * @param value a value.

     * @throws NullPointerException if either key or value is null.

     */

    public static void setSystemProperty(Object key, Object value)

    {

        JvmPort.getInstance().setSystemProperty(key, value);

    }

    /**

     * Adds the defined user property containing all the user

     * properties. This will not override any system properies.

     * The semanitc is equivalent to Hashtable.put() method.

     * @param key a key.

     * @param value a value.

     * @throws NullPointerException if either key or value is null.

     */

    public static void setUserProperty(Object key, Object value)

    {

        JvmPort.getInstance().setUserProperty(key, value);

    }

    /**

     * Shrinks the Java heap to a minimum. This call will lead to call

     * of the gc.

     *

     * @return Number of bytes shrinked.

     */

    public static int shrinkJavaHeapToMinimum()

    {

        return JvmPort.getInstance().shrinkJavaHeapToMinimum();

    }

    /**

     * Expands the size of the Java heap.

     *

     * @param amount Amount of bytes to be expanded.

     * @return Number of bytes expanded.

     */

    public static int expandJavaHeap(int amount)

    {

        return JvmPort.getInstance().expandJavaHeap(amount);

    }

}