Java under PowerPlant
Volume Number: 13
Issue Number: 9
Column Tag: Javatech
Putting Java Under PowerPlant
by Danny Swarzman, Stow Lake Software
Building a strategic game application with a C++ engine and
a Java user interface
Preface
develop a Macintosh application which runs Java code. The Java part could be an
applet, an application or neither. MRJ is delivered as shared libraries. The program
interface, JManager, is supplied in the MRJ SDK. Both are available from Apple's Java
website http://appleJava.apple.com/.
With MRJ you create a custom Java runner. It could be general-purpose or, as
described here, designed to run a particular Java program. There are many reasons
why you may want to do this. For example, you may have some legacy code in C or C++,
such as an engine which performs some abstract task. You want to develop a user
interface that will easily migrate. You also would like to deliver an application that
will work on a PPC Macintosh. This article shows how this can be done.
TicTacPPC is an application that runs a particular Java program, TicTacApp.
TicTacApp contains a call to a native function which is defined in C++ in TicTacPPC.
From the perspective of the Java program, the C++ application is virtually the
virtual machine. The application fulfills this role with the help of JManager.
TicTacApp
The CodeWarrior project, TicTacApp.java.n, creates a Java bytecode file,
TicTacApp.zip. This sets up a Tic Tac Toe game on the screen. The user plays X and the
program responds O.
The project has three files:
• TicTacApp.java which contains main().
• TicTacCanvas.java which handles the user interface.
• classes.zip, the Java libraries.
Since it contains a main()function, TicTacApp is a Java application. Since it refers to a
native function, it can run only when that native function is defined and available to
the Java runner.
TicTacPPC
The CodeWarrior project, TicTacPPC.n creates a Macintosh application, TicTacPPC
which will run only if MRJ has been installed in the system. The folder containing
TicTacPPC should also contain TicTacApp.zip.
TicTacPPC.n contains all the usual PowerPlant stuff plus MRJ stuff:
• JMSessionStubs.PPC
• NativeLibSupport.PPC
And the application specific files:
• CTicTacApplication.cp -- the application object calls CJManager.cp to
respond to New command.
• CFrameWindow.cp -- support for Java AWT frames.
• CJManager.cp -- communicates with the virtual machine through a
JManager session and implements the native function.
• CTicTacEngine.cp -- the class so smart that it never loses at TicTacToe.
The focus of this article is the work done by CJManager.cp and CFrameWindow.cp.
CJManager.cp opens the file TicTacApp.zip and supports the native function.
CJManager.cp is specific to this application.
CFrameWindow.cp is relay service passing events between PowerPlant and JManager
without regard for their contents. CFrameWindow.cp is a rudimentary version of a
general class to support Java frames.
Figure 1 shows how the various pieces of this hybrid application fit together.
Figure 1. How the pieces of this hybrid application fit together.
Running Java Programs
Starting up the session
The application starts up the virtual machine by opening a session with JManager. The
session is the structure through which JManager keeps track of the Runtime Instance,
that particular virtual machine which will run our collection of threads of Java
execution.
JManager uses a JMSession data structure to keep track of the session. The application
has no access to the internals of the JMSession. It does provide JManager with a set of
callback functions to handle standard files, stdin, stdout and stderr. The application
also specifies security options, telling JManager how to limit what the Java program
will be able access in the local system.
Since TicTacPPC will run only one Java program, TicTacApp, we don't worrry about
security and don't need to support standard files. All these are set to default values.
CJManager.cp
CJManager
The constructor sets up the JManager session.
CJManager :: CJManager ( LCommander *inSuperCommander )
// Set up a session with JManager. Setup a context for the frames.
{
// This is an app that will run locally so security is not used.
// To run apps, you might want to put sensible values here.
static JMSecurityOptions securityOptions = {
kJMVersion, eCheckRemoteCode,
false, { 0 }, 0, false, { 0 }, 0,
eUnrestrictedAccess, true };
// If you want to implement standard files you must create functions
// for stderr, stdout, stdin and put pointers to the functions into
this
// JMSessionCallbacks structure
static JMSessionCallbacks sessionCallbacks =
{ kJMVersion, nil, nil, nil };
// Create the session
ThrowIfOSErr_ ( JMOpenSession ( &sSession, &securityOptions,
&sessionCallbacks, 0 ) );
// Create the context for frames to support the AWT. These will be
discussed later.
sContext = CFrameWindow :: CreateContext ( sSession,
inSuperCommander );
}
Idling to give Java some time
The application gives the virtual machine time to service its threads by calling JMIdle.
It is recommended that JMIdle be called at each cycle of the event loop. PowerPlant
provides a convenient way to do that by subclassing from LPeriodical and overriding
its SpendTime method.
CJManager.cp
SpendTime
The application calls this at idle time. It gives MRJ a chance to
attend to its threads.
void CJManager :: SpendTime ()
{
JMIdle ( sSession, kDefaultJMTime);
}
Finding Java Entities with JRI
The Java Runtime Interface is the standard for a C++ program to access Java entities
used with MRJ 1.x. It was developed by Netscape to support code that works with their
Navigator(tm) product. JRI allows the C++ program to find Java objects and contains
specifications for conversion from Java types to C++ types.
The runtime stack and other data used by the virtual machine to keep track of the
execution of a thread is the thread's environment. Calls to JRI pass an opaque structure
representing the current environment. Through it, JRI locates objects, classes and
methods.
Calling Java functions from C++
Through JManager calls, the application can virtually call Java functions. First the
application uses JRI to locate the function and then uses JManager to invoke the
function.
In RunApp() JManager is asked to execute the main() function of class TicTacApp in
file TicTacApp.zip. First JManager calls are used to make the file available to the
virtural machine. JRI calls locate the class. Finally the JManager call
JMExecStaticMethodInContext() starts the process.
JRI specifies an encoding scheme to represent Java function signatures as strings.
There are macros in JRI.h to construct them. Search for JRISig. Look at the macro
definitions and the accompanying comments. You can infer the coding scheme, as is done
here, or use the macros.
Actually JMExecStaticMethodInContext() tells the virtual machine to queue a request.
TicTacApp's main() is not interpreted until the virtual machine gets around to it. The
virtual machine runs when it is given time, that is when the application calls
JMIdle().
Don't let your threads get tangled
Because the execution of the Java function is not immediate, the C++ program should
not depend on the results being valid at a particular time. Deadlock will occur if the
C++ program waits for a variable that is changed by the called Java function.
Multi-threaded or concurrent programming presents its own challanges. In this kind