Darryl Mocek's Blog

phoneME Advanced Peer File Structure

For those interested in creating a phoneME Advanced implementation on other platforms with other windowing toolkits, you may be wondering how and where to start. The first thing you'll want to do is get the CDC VM (CVM) up and running. I won't go into detail about this, but an important point to note is that the CDC (Connected Device Configuration) specifies a set of Java classes that must be present. Besides porting the VM itself, the CDC classes also need to be ported. This, however, should be fairly straightforward. The bulk of the CDC Java code, which is usable across platforms, is in the src/share/classes directory. These Java classes require support of the underlying native code which interfaces with the OS of choice directly. The bulk of the CDC native code can be found in the src/share/native directory. For example, if you look at src/share/classes/java/lang/Object.java, it makes a native call (public final native Class getClass();) which is serviced by src/share/native/java/lang/Object.c. The files in the src/share directory are shared by all implementations, regardless of the hardware/OS. If there are special requirements by the hardware/OS which cannot be serviced by a shared file, you'll find files in src/os<-cpu>. For example, separate code is required to interface with the audio device in Personal Profile. So you'll find audioDevice.c in these places:

The good news is that, as previously stated in this article, the code which is NOT in the shared area is minimized as much as is possible.

Once we get above the configuration to the profiles, things become easier. Sitting atop CDC is the Foundation Profile (FP). Almost all of the code for implementing the FP is in the src/share/foundation directory. And just like the CDC code, there is a src/share/foundation/classes directory for Java code and a src/share/foundation/native directory for the native code which is called by the Java code. There are some files in the src/os<-cpu> directory which support the Foundation Profile. For example, the native PlainSocketImpl_md.c file which supports FP's SocketImpl.java class can be found in the src/os- directories.

Above the FP lies the Personal Basis Profile (PBP). Things get a little more complicated here as the PBP adds windowing code in the form of the Abstract Window Toolkit (AWT). This complicates things because there are different windowing toolkits on different platforms (and even on the same platform!) which can be used. Fortunately, however, the PBP code is isolated to the src/share/basis directory. Again, the common src/share/basis/classes directory contains the Java code and the src/share/basis/native directory contains the supporting native code. If you look in the src/share/basis/classes/awt directory, you'll see the Java classes which support the Microwindows and Qt UI toolkits under the microwindows and qt directories respectively. And of course, under src/share/basis/native/awt are also the microwindows and qt directories containing the supporting native code. The code in these native directories interact directly with the microwindows and qt libraries. This, plus the corresponding Java code is the “porting” layer for PBP.

Above the PBP sits the Personal Profile (PP). PP is a bit different in that it re-implements some of the classes in its underlying layer (PBP). For example, you'll find an AWTEvent.java and Graphics.java file in both PBP and PP. This is necessary to support the differences in PP. PP has yet a different directory structure from PBP underneath. You'll notice in the src/share/personal/classes directory, a directory named common. This directory contains Java classes which are common to the varying PP implementations. For example, there is a file named src/share/personal/classes/common/java/awt/GraphicsDevice.java. The various PP implementations have a GraphicsDevice class of their own which extends this common GraphicsDevice class. There is also an awt directory which contains a peer_based directory. Underneath this is a directory (java/awt) containing files common to all the peer-based PP implementations. The specific peer-based implementations are in the sun/awt/ directories. There, you'll find qt, gtk, and pocketpc implementations.

phoneME Advanced Directory Structure Explained

In this blog entry, I'll be talking about the directory layout of the phoneME Advanced project. You can follow along by browsing the source code here while you're reading this blog. You'll have to join the project to do this.

The start of the phoneME Advanced code is located components/cdc/trunk directory. Underneath the trunk directory are these directories:

build – contains the make files. This is where you want to go to build.
src – contains the source files
test – contains the test files

This is obvious enough.

Once you're at the src directory, you're at the root of the source code for all platforms. You'll notice a listing of several hardware and os/hardware combination directories here as well as a share directory, which I'll talk about later. These directories contain code specific to the os/hardware (except the share directory). Code in these directories are minimized and are mainly native (non-Java) code. The majority of it is cvm code.

Underneath the share directory is the bulk of the phoneME Advanced code.

appmanager – contains the code for the application manager
basis – contains the code for the Personal Basis Profile
cdc – contains demo code for the Connected Device Configuration
classes - contains the code for the Connected Device Configuration<
foundation – contains the code for the Foundation Profile
javavm – contains the code for the cvm
lib – contains Java security files
native – contains shared native code
personal – contains the code for the Personal Profile
tools – contains tools

Each of these directories can be put into categories: basis, foundation, personal, and the src directory in which we're “in”, typically have a classes directory and a native directory. The classes directory contains all of the Java code and the native directory contains supporting native code for the Java classes. The native directories contain JNI code and code which interfaces with other native libraries, like Qt.

appmanager is an all-Java component and contains no native code. cdc contains only a demo file and lib contains two text files relating to Java security, a policy and security file. tools contains both native and Java files, but the directory structure underneath it is slightly different. For now, I'll focus on the profile code.

Underneath the classes directory is, for the most part, the root of the Java packages. So here's where you'll find the java/lang directory.

The CDC profiles build upon each other. So the Personal Basis Profile includes Foundation Profile and the Personal Profile includes the Personal Basis Profile. For the most part, the Foundation Profile code is in the foundation directory, the Personal Basis Profile code is in the basis directory and so forth. There are some cases where you'll find the same file in different profiles. For example, you'll find Toolkit.java in basis: basis/classes/common/java/awt/Toolkit.java and in personal: personal/classes/common/java/awt/Toolkit.java. This is to account for the differences in the various profiles.

Underneath the build directory, you'll find directories similar to the src directory, a share directory, which contains makefiles which are shared across all platforms, and directories specific to each os/hardware platform. Again, the os/hardware-specific makefiles are minimized.

Java Is Now Open Source

No doubt you've heard the news by now (Actually, this news is old by now. This blog was supposed to go out the same day we announced the open sourcing of Java, but, as you can expect, things have been really busy around here and there's been a backlog getting Sun employees setup on java.net...so here's my "Java's Open Source" blog entry anyway), Java has been open sourced under the GPL v2 license. Not just Java SE, but Java ME and Java EE as well.

I work on the Java ME code, particularly CDC stack, the Connected Device Configuration. This is the stack which is designed to run on set-top boxes, PDA's, smart phones, and the like.

If you're interested in looking at the code, you can find it by going to http://mobileandembedded.org (This redirects you to the Mobile & Embedded community on java.net. You'll need to register with java.net first.), selecting 'phoneME' under the Projects section on the left side of the screen, and either downloading the code by selecting 'Download' on the right side of the screen and downloading the 'phoneme_advanced-mr1-rel-src-b06-10_nov_2006.zip' file, or browse the code online by selecting the 'Browse' link on the right side of the screen, and traversing to components, cdc, trunk. This is the root of the CDC code.

Have fun checking out the code.