Personal Basis Profile

This profile provides two major features
- Support for basic GUI functionality
- Lifecycle management of applications
The GUI functionality is provided by a subset of the AWT, without most of the widgets
A basic lifecycle model to start, stop, suspend and resume applications is supported using Xlets
The Sun Personal Basis distribution includes a Programmer's Guide

An AWT application

An application to show a button and print a message when pressed is


import java.awt.*;
import java.awt.event.*;

public class ButtonDemo extends Frame implements ActionListener {

    public static void main(String [] args) {
	ButtonDemo demo = new ButtonDemo();
	demo.pack();
	demo.setVisible(true);
    }

    public ButtonDemo() {
	setLayout(new BorderLayout());
	Button btn = new Button("Press me");
	add(btn, BorderLayout.CENTER);
	btn.addActionListener(this);
    }

    public void actionPerformed(ActionEvent e) {
	System.out.println("Button pressed");
    }
}

This application will not work in Personal Basis Profile, because there is no Button object

Converting to an AWT application that works under PBP

The PBP has the Frame widget, all of the AWT events and AWT listeners, and the AWT geometry managers
It has graphics objects, and basic drawing functions
It doesn't have the widgets such as the Button
All that is needed (:-) is to define your own widgets, and write code for them

An AWT application working under PBP


import java.awt.*;
import java.awt.event.*;
import java.util.ArrayList;
import java.util.EventObject;

public class PPButtonDemo extends Frame implements ActionListener {

    public static void main(String [] args) {
	PPButtonDemo demo = new PPButtonDemo();
	demo.pack();
	demo.setVisible(true);
    }

    public PPButtonDemo() {
	setLayout(new BorderLayout());
	PPButton btn = new PPButton("Press me");
	add(btn, BorderLayout.CENTER);
	btn.addActionListener(this);
    }

    public void actionPerformed(ActionEvent e) {
	System.out.println("Button pressed");
    }
}

class PPButton extends Component implements MouseListener {

    private static Font font = new Font("sanserif", Font.PLAIN, 12);
    private static Color color = new Color(0xAAAACC); 
    private static Color darker = color.darker().darker();
    private String label;
    private ArrayList listeners = new ArrayList(); 
    private boolean pressed; 
    private boolean inside;

    public PPButton(String label) {
	this.label = label;
	setSize(12 + 8 * label.length(), 20); 
	addMouseListener(this);
    }
    
    public Dimension getPreferredSize() { 
	return getSize(); 
    }

    public Dimension getMinimumSize() { 
	return getSize();
    }
    
    public Dimension getMaximumSize() { 
	return new Dimension(Integer.MAX_VALUE, Integer.MAX_VALUE); 
    }
    
    public void paint(Graphics g) {
	Dimension d = getSize();
	g.setColor(darker); 
	g.fillRoundRect(0, 0, d.width, d.height, 10, 10);
	if (!pressed || !inside) { 
	    g.setColor(color);
	} 
	int border = 3; 
	g.fillRoundRect(border, border, 
			d.width - 2 * border, 
			d.height - 2 * border, 
			10, 10);
	g.setColor(g.getColor() == color ? darker : color);
	g.setFont(font);
	FontMetrics fm = g.getFontMetrics(font);
	int w = fm.stringWidth(label); 
	int h = fm.getHeight();
	g.drawString(label, (d.width - w) / 2, 
		     h + (d.height - h) / 2 - 3);
    }

    public void mouseClicked(MouseEvent e) {
    } 

    public void mouseEntered(MouseEvent e) { 
	inside = true;
	repaint();
    } 

    public void mouseExited(MouseEvent e) {
	inside = false;
	repaint(); 
    } 
    
    public void mousePressed(MouseEvent e) {
	pressed = true;
	repaint(); 
    }
    
    public void mouseReleased(MouseEvent e) { 
	pressed = false; 
	repaint(); 
	if (!inside) { 
	    return;
	} 
	for (int i = 0; i < listeners.size(); i++) { 
	    ActionListener listener = (ActionListener) listeners.get(i);
	    listener.actionPerformed(new ActionEvent(this, 
						     ActionEvent.ACTION_PERFORMED, 
						     label)); 
	} 
    }

    public synchronized void addActionListener(ActionListener listener) { 
	listeners.add(listener);
    }
    
    public synchronized void removeActionListener(ActionListener listener) { 
	listeners.remove(listener);
    }
}

To compile the demo


javac -classpath .:/usr/local/personaljava/j2me-pp1.0/lib/personal.jar *.java

To run the demo


/usr/local/personaljava/j2me-pp1.0/bin/cvm PPButtonDemo

Xlets

An ordinary application has a main() method, and is started by calling this method
The life cycle of an application is start - stop
A downloadable application may have further stages
- download from some source
- initialise the application
- start the application
- suspend the application
- restart the application
- stop the application
- discard the files
The life-cycle of a downloadable application should include the environmental aspects in which it appears to "start - stop"
These applications are managed applications
An Xlet is the PBP managed application type

Xlet life-cycle

Xlet interface

An Xlet is informed about each state change, as the management environment calls the methods of the Xlet interface


package javax.microedition.xlet;

public interface Xlet { 

    /**
     * Signals the Xlet to initialize itself and enter the Paused state. 
     * The Xlet shall initialize itself in preparation for providing service. 
     * It should not hold shared resources but should be prepared to provide 
     * service in a reasonable amount of time.
     */
    public void initXlet(XletContext ctx) 
	throws XletStateChangeException;

    /**
     * Signals the Xlet to start providing service and enter the Active state. 
     * In the Active state the Xlet may hold shared resources. 
     */
    public void startXlet() 
	throws XletStateChangeException;

    /**
     * Signals the Xlet to stop providing service and enter the Paused state.
     *  In the Paused state the Xlet must stop providing service, 
     * and might release all shared resources and become quiescent. 
     */
    public void pauseXlet();

    /**
     * Signals the Xlet to terminate and enter the Destroyed state. 
     * In the destroyed state the Xlet must release all resources
     * and save any persistent state. 
     */
    public void destroyXlet(boolean unconditional) 
	throws XletStateChangeException;
}

Xlet example

An example using the PPButton is


import java.awt.*;
import java.awt.event.*;
import  javax.microedition.xlet.*;

public class XletButtonDemo implements ActionListener, javax.microedition.xlet.Xlet {

    private Container rootContainer;
    private PPButton button;

    public XletButtonDemo() {
    }

    public void actionPerformed(ActionEvent e) {
	System.out.println("Button pressed");
    }

    public void initXlet(XletContext context) 
	throws XletStateChangeException {
	try { 
	    button = new PPButton("Hello World");
	    rootContainer = context.getContainer(); 
	    rootContainer.setLayout(new BorderLayout());
	    rootContainer.setLocation(0,0); 
	    rootContainer.add(button, 
			      BorderLayout.CENTER);
	    rootContainer.setSize(button.getSize());
	} catch (Exception e) { 
	    e.printStackTrace();
	}    

}

    public void startXlet() 
	throws XletStateChangeException {
	// Make the container visible. This method calls 
	// the paint method. 
	rootContainer.setVisible(true);
    }

    public void pauseXlet() {
	rootContainer.setVisible(false);   
    }

    public void destroyXlet(boolean unconditional) 
	throws XletStateChangeException {
	rootContainer.remove(button);    
	button = null;
    }
}

To run the Xlet

cvm com.sun.xlet.XletRunner -name XletButtonDemo -path .

Xlet communication

Xlets controlled by the same manager can get references to each other using the IxcRegistry
Xlets can then call methods on each other
e.g. a Timer Xlet running on a TV can ask the current display Xlet to show a different program

Jan Newmarch (http://jan.newmarch.name)

This work is licensed under a Creative Commons License
The moral right of Jan Newmarch to be identified as the author of this page has been asserted.