This software and documentation is the confidential and proprietary information of Sun Microsystems, Inc. ("Confidential Information"). You shall not disclose such Confidential Information and shall use it only in accordance with the terms of the license agreement you entered into with Sun.

SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.

TRADEMARKS

Please submit any comments to the following email address:

This document is intended as a guide to the facilities PersonalJava provides to applications, applets, and their developers. It is a "delta" rather then a full specification; that is, it describes the ways in which PersonalJava differs from JDK 1.1.

PersonalJava is designed to meet the following goals:

These packages provide the core capabilities of Java, as reflected in the many books on Java programming and as observed in our samples of current applet and application usage. They reflect the capabilities of "small" devices and their users (insofar as it is possible to make generalizations about either).

These packages provide capabilities that are more likely to be required by "enterprise" applications than small consumer devices, that are not yet widely used, or that require amounts of ROM beyond what most consumer devices are able to accommodate.

The remainder of this specification consists of descriptions of the packages contained in the PersonalJava API. The description for each package contains a table that lists the classes and interfaces for that package. In the tables, classes are marked as required, modified, unsupported, or optional.

Required classes are fully implemented as in the JDK 1.1 specification.

A class is marked as modified if any of its methods are not supported or are modified in the PersonalJava API. Descriptions for any optional or modified methods are provided following the class and interface tables for each package.

If a class is marked as unsupported, calling its constructor or calling any of its static methods will result in a java.lang.UnsupportedOperationException. Any instances of unsupported classes that are normally held in static class variables will instead hold null.

Unsupported methods will throw a java.lang.UnsupportedOperationException when called.

Methods for Double Buffering

PersonalJava provides a new method, isDoubleBuffered, for class Component.

    // in class java.awt.Component
    public boolean isDoubleBuffered();

If isDoubleBuffered returns true, then all drawing done inside paint and update methods will be double buffered automatically. The default value for the double buffering setting is platform-specific.

To achieve double buffering on a platform that does not support it, developers should explicitly create an off-screen image, draw into it, and use drawImage to display it. However, doing so may take large amounts of memory, and could therefore fail.

Applet class MyAnimator checks at init time to see if the hardware will automatically double-buffer its graphical output. If not, it allocates its own off-screen image buffer:

public class MyAnimator extends Applet implements Runnable {

    ...
    Image offScreenBuffer = null;

    Graphics offScreenGraphics = null;

    void allocateOffScreen() {
        // Create an off-screen Image buffer and a Graphics context
        offScreenBuffer = createImage(getSize().width, getSize().height);
        offScreenGraphics = offScreenBuffer.getGraphics();
    }        

    public void init() { 
        // Carefully check whether the platform supports double-buffering.
        // We use reflection so that this code compiles and runs on JDK 1.1.
	try {
	    java.lang.reflect.Method m = 
		this.getClass().getMethod("isDoubleBuffered", null);

	    if (((Boolean)m.invoke(this, null)).booleanValue()) {
		allocateOffScreen();
	} catch (Throwable oops) {

	}
        ...
    }

    public void paint(Graphics g) {
        if (offScreenGraphics == null) {
            // Platform handles double-buffering, so just draw on the screen
            drawFrame(g);
        } else {
            // We have to do double-buffering ourselves.
            // First draw offscreen into allocated image buffer.
	    Dimensions d = getSize();
	    if (sizeDiffers(this, offScreenBuffer)) {
	        allocateOffScreen();
	    }
            drawFrame(offScreenGraphics);
            // Then copy the buffer onto the screen.
            g.drawImage(offScreenBuffer, 0, 0, this);
        }
    }

    ...
}

Interfaces for Specifying Component Behavior

In mouseless environments, users can navigate from one on-screen component to another by using keys or buttons on the system's input device. When the user navigates to a component, the visual representation of that component is modified in some way to indicate that it is the "current" component.

The input device may provide a way for the user to "select" the current component to indicate that the user desires to interact with the component. For example, after navigating to an on-screen button, the user might press the Go key on a remote control to indicate that the on-screen button is to be "pressed".

Examples: Using the Component Behavior Interfaces

Class MyLabel represents an area that simply displays a test string. It isn't concerned with any sort of input at all:

public class MyLabel extends Canvas implements NoInputPreferred {

    public MyLabel(String text) {
	...
    }

    public void paint(Graphics g) {
	g.drawString(text, x, y);
    }
}

Class MyNumberField represents an area into which the user can type a number. It only concerns itself with character input, but not positional or other sorts of input:

public class MyNumberField extends Canvas implements KeyboardInputPreferred, KeyListener {

    public MyNumberField() {
	...
    }

    /* Insert the key in the field */
    public void keyTyped(KeyEvent e) {
        ...
    }

    /* Ignore it  - input handled by keyTyped */
    public void keyPressed(KeyEvent e) {
    }

    /* Ignore it  - input handled by keyTyped */
    public void keyReleased(KeyEvent e) {
    }

    /* We want the user to be able to TAB to this component. */
    public boolean isFocusTraversable() {
        return true;
    }

    ...
}

Class MyButton, below, represents a button on the screen. It only concerns itself with actions (up and down clicks) and whether it's selected, so we make it implement ActionInputPreferred:

public class MyButton extends Canvas implements ActionInputPreferred {

    public MyButton(Image down, Image up, Image disabled) {

	MouseListener mouseListener = new MouseAdapter() {
		
            public void mousePressed(MouseEvent e) { 
	 	... // User clicked; do something
	    }

   	    public void mouseReleased(MouseEvent e) { 
		... // User released
	    }

   	    public void mouseEntered(MouseEvent e) { 
		... // User has navigated here
	    }

   	    public void mouseExited(MouseEvent e) { 
		... // User has navigated away
	    }
	};

	addMouseListener(mouseListener);
    }

    ...
}

public class MyScribbler extends Canvas implements PositionalInputPreferred,
    MouseMotionListener, KeyListener
 {

    private final static char controlP = 0x10;

    Color currentColor = Color.black;
    boolean painting = true;

    public MyScribbler() {
	...
    }

    /* User is holding the button while moving.  Draw a line.
       Since not all input devices allow dragging, we provide
       other means for doing this in the mouseMoved method. */
    public void mouseDragged(MouseEvent e) {
        addLine(e.x, e.y, currentColor);
	repaint();
    }

    /* User has moved the pointing device to a new position.
       If the user has selected drawing mode via control-P, draw a line, else
       just move. */
    public void mouseMoved(MouseEvent e) {
        if (painting) {
            addLine(e.x, e.y, currentColor);
	    repaint();
	}
    }

    /* Show this character at the current position */
    public void keyTyped(KeyEvent e) {
        char ch = e.getKeyChar();
        if (ch == controlP) {
            painting = !painting;
        } else {
            addChar(e.x, e.y, e.getKeyChar());
	    repaint();
        }
    }

    /* Ignore key press  - it's handled by keyTyped */
    public void keyPressed(KeyEvent e) {
    }

    /* Ignore key release - it's handled by keyTyped */
    public void keyReleased(KeyEvent e) {
    }

    /* We don't want the user to be able to TAB to this component. */
    public boolean isFocusTraversable() {
        return false;
    }

}

A component should implement only one of the input preference interfaces. If a component implements more than one, it should behave as if none had been implemented.

An implementation should ignore these input preferences when appropriate. For example, on a platform with a keyboard and mouse, the implementation might always ignore them. On a platform with a remote control that contains a trackball, the implementation might ignore all but KeyboardInputPreferred. On a platform with only a keyboard, the implementation might ignore only KeyboardInputPreferred.

If a component does not implement any of these interfaces, an implementation might establish a default for predictability, might attempt to detect what the component wants based on event listeners, or might apply other heuristics.

Developers should be aware that the specific character encodings available (as used in ByteArrayOutputStream, InputStreamReader, and OutputStreamWriter) are platform specific and may be quite limited in PersonalJava implementations. However, an implementation should guarantee the availability of converters for ISO 8859-1 ("Latin-1"), Unicode (big- and little-endian varieties, both marked and unmarked), and the native character encoding of the platform itself.

Developers should be aware that the specific character encodings available (as used in String) are platform specific and may be quite limited in PersonalJava implementations. However, an implementation should guarantee the availability of converters for ISO 8859-1 ("Latin-1"), Unicode (big- and little-endian varieties, both marked and unmarked), and the native character encoding of the platform itself.

For compatibility, the following class is also provided and can be included in applets developed on or targeted at JDK 1.1 platforms:

    package com.sun.lang;
    public class UnsupportedOperationException extends RuntimeException {
        public UnsupportedOperationException();
        public UnsupportedOperationException(String s);
    }

    package com.sun.util;

    public abstract class PTimer {

        public static PTimer getTimer();

        public abstract void schedule(PTimerSpec t);
        public abstract void deschedule(PTimerSpec t);
    }

    public class PTimerSpec {
    
        // Defaults to a one-shot timer going off immediately.
        // "Regular" defaults to true.
        public PTimerSpec() {
            setAbsolute(false);
            setRepeat(false);
            setRegular(true);
            setTime(0);
        }
    
        // Accessors
    
        public void setAbsolute(boolean absolute);
        public boolean isAbsolute();
    
        public void setRepeat(boolean repeat);
        public boolean isRepeat();
    
        // "Regular" defaults to true.
        public void setRegular(boolean regular);
        public boolean isRegular();
    
        public void setTime(long time);
        public long getTime();
    
        // Listeners
    
        public void addTimerWentOffListener(PTimerWentOffListener l);
        public void removeTimerWentOffListener(PTimerWentOffListener l);
        
        // Convenience functions
    
        public void setAbsoluteTime(long when) {
            setAbsolute(true);
            setTime(when);
            setRepeat(false);
        }
        
        public void setDelayTime(long delay) {
            setAbsolute(false);
            setTime(delay);
            setRepeat(false);
        }
    
        // For the benefit of PTimer implementations
    
        public void notifyListeners(PTimer source);
    }
    
    public class PTimerWentOffEvent extends java.util.EventObject {
    
        private PTimerSpec timerSpec;
    
        public PTimerWentOffEvent(PTimer source, PTimerSpec spec) {
            super(source);
    
            timerSpec = spec;
        }
            
        public PTimerSpec getTimerSpec() {
            return timerSpec;
        }
    }
    
    public interface PTimerWentOffListener {
        void timerWentOff(PTimerWentOffEvent e);
    }

The PTimer methods are:

getTimer()

Returns a timer object. There may be one PTimer instance per virtual machine, one per applet, one per call to getTimer, or some other platform dependent implementation.

schedule(PTimerSpec)

Begins monitoring a PTimerSpec. When the timer specification should fire, the timer will call PTimerSpec.notifyListeners.

deschedule(PTimerSpec)

Removes a PTimerSpec from the set of monitored specifications. The descheduling happens as soon as practical, but may not happen immediately.

The PTimerSpec methods are:

PTimerSpec()

Creates a new timer specification that defaults to a one-shot timer that goes off after a delay of 0ms.

setAbsolute(boolean)
isAbsolute()

Determines whether the time specification in setTime is an absolute time or a delay time.

setRepeat(boolean)
isRepeat()

Determines whether a delay time should fire once or continue delaying and firing until descheduled. This value has no effect if the time specification is absolute.

setRegular(boolean)
isRegular()

Determines whether a repeating delay time measures from the time the event fires (regular) or from the time the event listeners finish executing (not regular). For example, imagine you have a timer specification that repeats every 10ms, but calling the listeners via notifyListeners takes 5ms. If the specification is regular, the listeners will be called every 10ms. If the specification is not regular, the listeners will be called every 15ms (10ms after the listeners finish executing). Due to system load or the length of time the event listeners take to execute, it may not be possible for regular specifications to fire fast enough. In this case, the specification will fire as fast as possible.

setTime(long)
getTime()

Sets the time at which the specification fires. Absolute times are in milliseconds since midnight, January 1, 1970 UTC. Relative times are in milliseconds. A specification with an absolute time less than java.lang.System.currentTimeMillis() will fire as soon as it is registered.

addTimerWentOffListener(PTimerWentOffListener)

Adds a listener to call when the specification fires.

removeTimerWentOffListener(PTimerWentOffListener)

Removes a listener from the list of listeners to call when the specification fires. If the listener is not currently registered on this timer specification, this method does nothing.

setAbsoluteTime(long)

Sets the timer specification to fire at the specified absolute time.

setDelayTime(long)

Sets the timer specification to fire once after the specified delay.

notifyListeners(PTimer)

Calls all the listeners registered on this specification. This method is primarily for the benefit of implementers of subclasses of PTimer and will normally not be used by developers.

Unless it has unusual timing requirements, an applet should use the timer provided by getTimer rather than creating one of its own. By doing so, an implementation may be able to conserve resources by providing timing services via an existing thread rather than creating a new one.

Name	Version	Required	Optional
http:	1.0
SSL (Secure Sockets Layer)	3.0
gopher:	--
ftp:	--		(requires java.net.ServerSocket)
mailto: (SMTP)	--
file:	--

Image Formats