Chapter 4

Java Virtual Machine Capabilities

The Oracle Java ME Embedded Client Java VM implementation fully supports the Java Native Interface (JNI) specification version 1.2.

4.1 Resource Registry for Cleanup Resources

This feature allows the application to control the resources consumed by the PBP graphic layer by setting a ResourceRegistry implementation and have the ability to track which resources are currently consumed and have the ability to dispose them at any time.

The class misc.bluray.jvmbi.ResourceRegistry defines APIs to register and unregister objects with a disposer to dispose them. The stack has a singleton resource registry available. By default, the registry does nothing. However, the application can set its own implementation of the registry using the following API:

ResourceRegistry.setInstance(ResourceRegistry registry)

The PBP layer implementation registers the following objects with their disposers to the available registry:

• java.awt.Graphics objects

• java.awt.Image objects

• sun.xlet.ixc.Worker threads

• javax.microedition.xlet.XletContext objects

• Names of bound javax.microedition.xlet.XletContext objects

• Event listeners of all types: window, key, mouse, etcetera.

• java.awt event dispatch thread.

• Timer threads

4.2 Override Runtime Properties

This feature can be used for Java applications to override Java system property values at runtime. This is useful in cases where the Java property value can vary according to the context in which it is queried.

Using Dynamic Properties

Let us consider an example of property user.dir. When running in a multiple Xlet environment, the value of this property can be different for each Xlet. The Java application would like to control the value of this property and provide the correct value according the context of the thread querying the value.

Dynamic properties are implemented using an interface com.sun.cdc.config.PropertyProvider and a control manager called com.sun.cdc.config.DynamicProperties.

Follow these steps to use dynamic properties.

1. Implement the PropertyProvider interface:

   /**
    * Returns the current value of the dynamic
    * propertycorresponding to this
    * <code>PropertyProvider</code>.
    *
    * @param key key for the dynamic property.
    * @param fromCache indicates whether property value should 
    * be taken from internal cache. It can be ignored if properties
    * caching is not supported by underlying implementation.
    * @return the value that is returned by
    * <code>System.getProperty()</code> call for the corresponding
    * dynamic property.
    */
    public String getValue(String key, boolean fromCache);
    
    /**
    * Tells underlying implementation to cache values of all the
    * properties corresponding to this particular class. This call
    * can be ignored if property caching is not supported.
    *
    * @return <code>true</code> on success, <code>false</code>
    * otherwise
    */
    public boolean cacheProperties();

2. Register the properties you want to control using DynamicProperties.put method:

   /**
    * Sets the specified <code>PropertyProvider</code> object to be
    * called for dynamic property resolution. This method should be
    * used at the time of properties initialization.
    *
    * @param key key for the dynamic property.
    * @param provider <code>PropertyProvider</code> instance that
    * is used to resolve the dynamic property with the
    * specified key.
    */
    public static void put(String key, PropertyProvider provider);

3. In the PropertyProvider.getValue method implementation you can override the value of the registered properties. The property providers are called before the system properties are used. For any property you registered for (using the DynamicProperties.put method), if you do not return null you are overriding the system values.

   This is a sample implementation:

   import com.sun.cdc.config.DynamicProperties; 
   import com.sun.cdc.config.PropertyProvider; 
    
   public class MyProperties implements PropertyProvider { 
   
       public MyProperties() { 
            /* 
             * to register a property to be in your control
             */ 
           DynamicProperties.put("my.prop", this); 
       } 
    
       /* 
        * Implementation of PropertyProvider interface 
        */ 
       public String getValue(String key, boolean fromCache) 
          { 
           if (key.equals("my.prop")) { 
               String myValue; 
               // calculate the value 
               ... 
               return myValue; 
               } 
               return null; 
       } 
    
       public boolean cacheProperties() { 
           /* not supported */ 
           return false; 
       } 
   }

4.3 Enable/Disable JAR Caching

Caching of an accessed JAR file can be enabled or disabled using the system-wide property java.net.enableJarCaching.

Caching enabled by default. If the property is not set, the default value is set to TRUE.

4.4 Heap Monitor

The heap monitor is intended to detect low Java heap availability in order to avoid a Java out of memory exception. A heap status monitor task monitors the Java heap size at a certain periodicity. When the Java heap size grows beyond a certain High Water mark, the following measures are taken:

1. Trigger system garbage collection.

2. Application registers callback to identify which Xlet to kill.

3. Destroy the last Xlet that was initiated.

These actions are repeated in the next period until the heap size falls below the High Watermark.

The default policy is to destroy the latest Xlet initialized (LIFO). Since the motive is to kill Xlets, this Monitor task only starts when an Xlet is initialized. It is canceled when there is no Xlet on the system.

To set your callback to identify which Xlet must be killed, use the following API:

JNIEXPORT void JNICALL
JVM_SetDestroyXletIdentifierHook(jobject (*JVMdestroyXletIdentifier)
    (void)); 

The object returned by your callback is of type java.lang.Thread.

You can use any thread that belongs to the Xlet you want to kill. The VM extracts the Xlet application ID (see 3.4 The Xlet Life Cycle) and use it to kill the Xlet.

Periodicity of monitoring and the Heap High Watermark can be specified by the user as command line parameter at VM startup time.

The following are the properties with brief description:

• Heap High Watermark:

  sun.misc.heapHighWaterMark: It is percentage and not absolute size. So if -Dsun.misc.heapHighWaterMark=70, then Xlet killing would be attempted when the Java heap size grows beyond 70% of Max heap size.

• Heap Check Period:

  sun.misc.heapCheckPeriod: Period specified in milliseconds. Minimum is fixed at 1 sec, so this property cannot be set below 1000ms. If set, it would default to 1000ms.