
An API for caffeinating your native application!
by Michael Fraenkel
Date: 4/25/97, Version: 1.1
J-Empower
J-Empower is a developer's tool that provides a simple interface which
allows embedding of Java applets and JavaBeans into your application. J-Empower
is evolving into its second release. The first release addressed applets.
To better service the needs of the Java 1.1 community, JavaBeans support
has been added to release 1.1 of J-Empower.
J-Empower takes the form of a system specific DLL and a collection
of Java .class files. J-Empower provides a simple 'C' interface
which include functions to interact with the Java runtime, and execute
and manipulate Java applets and JavaBeans within a native application.
J-Empower allows native applications to exploit context specific components,
applets in the browser context and JavaBeans in Java applications.
J-Empower was initially built as a result of a practical
need to connect Java to real world applications. Specifically, applications
like Lotus Note, Lotus SmartSuite, OS/2 Netscape Navigator and the OS/2
desktop. As a result of working with an initial clientele, J-Empower deals
particularly well with applets. However, we are starting to see an increasing
demand to go beyond applets. Support for JavaBeans is the next logical
step.
The J-Empower API
The J-Empower API is broken up into 3 categories: Java Environment,
Applets, and Beans. The Java Environment set of APIs deal with
the Java Runtime (Java Virtual Machine). They include functions to start
the Java runtime as well as the processing of console messages generated
by the runtime. This API set also allows you to read and write information
(properties) to an area common to all Java classes. The Applet API
set deals, of course, with either single or sets of applets, include security.
The Bean API set deals with creating and embedding JavaBeans.
Java Environment
Applets
JavaBeans
General Functions
Architecture
JavaSoft's Java is ever evolving. Allowing "native" applications to embed
Java components is the cornerstone of the bigger "inter-operation"
picture. Java 1.1 has introduced a component architecture called Java Beans.
Web browsers however use components called applets. Applets may or may
not be Java Beans. "Embedded Java" is the essence of J-Empower.
The J-Empower API provides a mechanism for establishing the Java virtual
machine (runtime) and interacting with it. The first release of J-Empower
focused on embedding applets in native applications laying the groundwork
needed for tight inter-operation between native applications and Java applets.
The second release of J-Empower focuses on improving the current applet
support and adding new support for JavaBeans.
The Package
J-Empower is packaged as a DLL, containing a little over two dozen
C-API's and a ZIP file, containing the Java support classes. Because
of the portable spirit of Java, it is critical the the JEMPOWER.DLL be
portable. To guarantee a high level of portability, J-Empower uses the
Java Native Interface(JNI) to communicate with Java.
Figure 1 shows the flow of control between "your" application, J-Empower,
the Java runtime and an embedded Java applet or JavaBean.
Communication paradigm
Figure 2 illustrates the communication paradigm used by J-Empower. J-Empower
uses the Java Native Interface (JNI) to communicate between native code
(C/C++) and Java. JNI allows only one Java Virtual Machine (JVM) to be
created within a process. Therefore, J-Empower and the JVM are both executing
as extra threads within the native application.
Since J-Empower and the JVM are within the same process as the native application,
communication between the navtive application and Java is simplified. The
communication between native code and Java can be both bi-directional and
unidirectional with a starting point from either side. This is to allow
support for asynchronous callbacks as well as basic notifications.
J-Empower and JNI
The JNI is a native programming interface. It allows Java
code that runs inside a Java Virtual Machine (VM) to interoperate with
applications and libraries written in other programming languages, such
as C, C++, and assembly [JNI97].
Using JNI from a native application is not as easy as using
JNI in a native method. Java has the concept of garbage collection. JNI
extends the notion into your native application by keeping track of all
references touched through its methods. It becomes the responsibility of
the programmer to remove all unnecessary references. J-Empower does this
for you. It also provides a higher level interface to deal with Java components
in a very simplistic manner.
A Quick Example
The best way to understand the "caffeinating" process of J-Empower is to
examine a simple example.
The following example steps through the creation of a simple Windows95
program starting the Java VM. The program is written in C, but one could
imagine easily adapting the same example to use C++. While "walking" through
the following example the sections pertinent to J-Empower will be explicitly
highlighted. Appendix A contains the complete program listing.
int APIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow)
{
MSG msg;
HANDLE hAccelTable;
if (!hPrevInstance) {
// Perform instance initialization:
if (!InitApplication(hInstance)) {
return (FALSE);
}
}
// Perform application initialization:
if (!InitInstance(hInstance, nCmdShow)) {
return (FALSE);
}
hAccelTable = LoadAccelerators (hInstance, szAppName);
jeInitJavaRuntime();
jeInitAppletRuntime();
jeRegisterShowConsole(MyShowConsole);
// Main message loop:
while (GetMessage(&msg, NULL, 0, 0)) {
if (!TranslateAccelerator (msg.hwnd, hAccelTable, &msg)) {
TranslateMessage(&msg);
DispatchMessage(&msg);
}
}
return (msg.wParam);
}
Figure 3. Initializing J-Empower
We start with WinMain. WinMain has the honor of kicking off all
the typical things needed to correctly start a Windows95 application. These
responsibilities include initializing window data, registering the window
class, creating the main window and loading the window accelerators. All
these tasks are accomplished by using the helper functions InitApplication()
and InitInstance() and the Win32 API LoadAccelerator(). So
far nothing out of the ordinary. It's all straight Win32. Now we introduce
our first J-Empower API. jeInitJavaRuntime() is the API that
"gets it all started". It is responsible for loading and initializing
the virtual machine (runtime). The next J-Empower API to get called is
jeInitAppletRuntime(). The applet framework is loaded and
initialized. The jeRegisterShowConsole() method registers
a function that will receive all Java virtual machine console output message
strings. This particular example passes in the helper function MyShowConsole().
As you will see, our implementation of MyShowConsole isn't very ambitious,
in fact, we don't do anything within this function. So, feel free to use
it as a basis for something more interesting in your own application. Lastly,
WinMain enters the mandatory message dispatch loop. Next stop, Window Proc.
All the remaining "action" in our test program occurs in the Window procedure.
The following WinProc() fragments illustrate many of the Applet
related API's found in J-Empower. Some of the APIs are self explanatory.
For example, we process the ID_SHOWCONSOLE command message by issuing
the J-Empower API jeConsoleSetVisible(TRUE).
LRESULT CALLBACK WndProc(HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam)
{
static JEAPPLETHND hApplet=0;
static JEBEANHND bean = 0;
HWND hwndApplet=0;
static int xPos = 0, yPos = 0;
int wmId;
PAINTSTRUCT ps;
HDC hdc;
switch (message) {
case WM_CREATE:
/*
* Window initialization is performed here in WM_CREATE processing
* WinLoadString loads strings from the resource file.
*/
break;
case WM_COMMAND:
wmId = LOWORD(wParam); // Remember, these are...
//Parse the menu selections:
switch (wmId) {
case ID_SHOWCONSOLE:
jeConsoleSetVisible(TRUE);
break;
case ID_HIDECONSOLE:
jeConsoleSetVisible(FALSE);
break;
case ID_INITAPPLET:
{
HWND hwndApplet;
JEAPPLETWND hApplet;
JECONTEXTID contextID = 1;
char *argv[7]; // holds the 4 applet parameters
long height, width; // applet height and width
height = 160;
width = 460;
argv[0] = "imagesource=images/Beans"; // set the applet parameters
argv[1] = "backgroundcolor=0xc0c0c0";
argv[2] = "endimage=10";
argv[3] = "soundsource=audio";
argv[4] = "soundtrack=spacemusic.au";
argv[5] = "sounds=1.au|2.au|3.au|4.au|5.au|6.au|7.au|8.au|9.au|0.au";
argv[6] = "pause=200";
jeAppletInit(&hApplet, contextID, hwnd,
"file:////java/demo/Animator/","Animator",
NULL, NULL,
width, height, 7, argv);
// get the applet container window from the applet handle
jeMove(hApplet, pt.x, pt.y, width, height, TRUE);
pt.y += height + 10;
// show the applet container window
jeShow(hApplet, TRUE);
// now... start
jeAppletStart(hApplet);
}
break;
case ID_STARTAPPLET:
jeAppletStart(hApplet);
break;
case ID_STOPAPPLET:
jeAppletStop(hApplet);
break;
case ID_DESTROYAPPLET:
jeAppletDestroy(hApplet);
break;
...
Figure 4.Applet WndProc
The most interesting fragment in the figure above is the processing of
the ID_INITAPPLET command message. It is within this "case" that
the Animator applet is created. The J-Empower API used to create the applet
is jeAppletInit(). This API takes several parameters all
of which correspond to the parameters needed to create the APPLET HTML
tag. The trickiest parameter is the argument list parameter. However, after
looking at the example below, the organization of this parameter becomes
quite obvious. One thing to remember is the applet is initially created
hidden. To show an applet, the API, jeShow() is provided.
Previously, the window handle of the applet had to be obtained using jeHWNDfromHandle().
This is one such improvement made in release 2. (See Applets
for a more complete explanation applet window relationships).
Again, the example almost speaks for itself.
We now move on to an example showing the new JavaBean APIs in action.
...
case ID_BEANCREATE:
jeBeanInstantiate(&bean, "test");
break;
case ID_BEANEMBED:
{
HWND bHwnd;
jeBeanEmbed(hwnd, bean);
bHwnd = jeHWNDFromHandle(bean);
SetWindowPos(bHwnd, HWND_TOP, xPos, yPos, 150,150, SWP_SHOWWINDOW);
yPos += 150 + 10;
}
break;
case ID_BEANDISPOSE:
jeBeanDispose(bean);
break;
...
Figure 5. JavaBean WndProc
The example like the previous ones is self-explanatory. It is important
to understand that not all JavaBeans can be embedded. jeBeanEmbed()
will only allow beans which inherit from java.awt.Component
to be embedded.
Java Environment
All applications using J-Empower, must begin by initializing the Java runtime
using the jeInitJavaRuntime() method. However, an application can
start the Java VM prior to calling jeInitJavaRuntime so that different
startup options are used, but jeInitJavaRuntime() must still be
called. Once the Java VM is running, any of the other methods within J-Empower
can now be invoked.
Properties are an important feature of Java since they are used as configuration
parameters for some of the subsystems within Java. Most applications are
interested in setting up either socks or proxy support for applets. JDK
1.1 isolated the proxy support to the HTTP classes which now support HTTP
1.1. The HTTP properties are: http.keepAlive, http.maxConnections, http.nonProxyHosts,
http.proxyHost, and http.proxyPort. The Socks properties are: socksProxyHost,
and socksProxyPort.
Properties are set using the jeSetProperty() method. To configure
socks to use the host socks.ibm.com on port 1081, the following statements
are used:
jeSetProperty("socksProxyHost", "socks.ibm.com");
jeSetProperty("socksProxyPort", "1081");
Applets
The J-Empower API has a complete set of functions dealing with Applets.
The difficulty with Applet support is that both Sun and Netscape have different
implementations of the Java applet classes. This fact is a good example
of the need for a set of APIs to control applet embedding in a consistent
fashion.
The J-Empower implementation of applets place an applet within a sun.awt.windows.EmbeddedFrame.
Sun uses a panel, and Netscape uses a modified java.awt.Frame for
embedding. The EmbeddedFrame was chosen for a very good reason: Sun published
this class specifically for the ability to embed a Java GUI within native
applications. As figure 3 illustrates. this EmbeddedFrame is then placed
within a native window which we call an Applet Container.
An important feature of the J-Empower Applet APIs is to have notification
of completion. Since all applet actions are asynchronous, there needs to
also be asynchronous notification back to the native applications.
Currently, if an applet requests to be resized, the applet is given this
new size. If we embed applets into native applications, the "automagic"
resizing effect could have bad implications. Our implementation, allows
the applet to resize, but the container window will not resize. If the
native application requests a resize, both the container window and the
applet are resized.
The current framework for applet support assumes that applets are grouped
together in a single pool. We have introduced the notion of a context id
which allows the programmer to group applets into an AppletGroup which
are identified by the context id. Applets are restricted to communicating
with only those applets that are (a) in their AppletGroup and (b) cleared
for communication by the SecurityManager rules.
Default Applet Security
As the J-Empower architecture evolved there seemed to be a growing need
for native applications to take a larger part in the Java applet execution.
These areas include security, status information, and native application
support of http/socket calls.
The J-Empower security model allows the application to either set its own
Security Manager or allow the default J-Empower Security Manager to be
installed. The following table defines the default security checks.
Security check J-Empower Default behavior
1
|
classloader creation
|
fail
|
2
|
thread access
|
fail if outside applet's threadgroup
|
3
|
threadgroup access
|
fail if outside applet's threadgroup
|
4
|
system command execution
|
fail
|
5
|
exit VM
|
fail
|
6
|
linked library existance
|
fail
|
7
|
System.properties() access
|
fail
|
8
|
property access
|
if property, a, is requested and
property, a.applet is true, then success else fail
|
9
|
file read access -
|
if file starts with directories
in acl.read/acl.read.default or same directory as the applet then success
else fail
|
10
|
file write access
|
if file starts with directories
in acl.write/acl.write.default then success else fail
|
11
|
file descriptor read access
|
success if through Socket or invalid
fd otherwise fail
|
12
|
file descriptor write access
|
success if through Socket or invalid
fd otherwise fail
|
13
|
listen
|
success if port > 1024 otherwise
fail
|
14
|
accept
|
success if applet is allowed to
connect to the host otherwise fail.
|
15
|
connect
|
based on the network mode (appletviewer.security.mode),
one of three cases occur:
NETWORK_UNRESTRICTED default = success
NETWORK_NONE:default = fail
NETWORK_HOST:default= if hosts match success, else if proxy
trusted (trustProxy) success else fail
|
16
|
top level window warning
|
always display warning
|
17
|
package access
|
if the package, pkg, is being accessed
and the property, package.restrict.access.pkg, is true then fail else succeed.
|
18
|
package definition
|
if the package, pkg, is being defined
and the property, package.restrict.definition.pkg, is true then fail else
succeed
|
19
|
setting factories
|
fail
|
20
|
class member access
|
success for public members on classes
loaded with the same classloader otherwise fail
|
21
|
print job
|
fail
|
22
|
clipboard access
|
fail
|
23
|
event queue access
|
fail
|
24
|
security access
|
fail
|
J-Empower supports other types of callbacks which provide assist in providing
a tight degree of integration between your application and Java applets.
The ground rules for callbacks are as follows: (1) callbacks are invoked
from Java, (2) callbacks are allowed to call into Java, and (3) callbacks
must be re-entrant.
JavaBeans
The J-Empower API has another set of functions dealing with JavaBeans.
The JavaBean APIs support both non-GUI and GUI JavaBeans. There is also
support for saving and reloading beans.
The J-Empower support of JavaBeans allows an application to instantiate
any bean. If the bean is a GUI bean, an application can request the bean
to be embedded. The bean is placed within a sun.awt.window.EmbeddedFrame
and the handle of the frame is returned. If the bean inherits from java.awt.Frame,
then the handle of the window that the bean represents is returned instead.
All beans created with J-Empower must be disposed of. The disposal of a
bean, cleans up internal storage used to keep track of the bean and will
destroy any Java frame associated with the bean either by embedding or
itself.
Persistence storage is a piece of the JavaBean puzzle. Currently, the JavaBeans
specification only supports object serialization. Hence, the JavaBean APIs
only support serialization and deserialization. These APIs allow a native
application to save the state of the object in which they are dealing with
for use at a latter time.
J-Empower API Details
jeInitJavaRuntime
Starts the Java runtime if it has not already been started.
JERESULT jeInitJavaRuntime();
Parameters:
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
JRESULT bSuccess=jeInitJavaRuntime();
if (bSuccess == JE_OK)
printf("Java runtime is up and running...");
}
Note:
This must be called prior to using any J-Empower APIs.
If the Java runtime needs to be started with special options, the native
application should start the JVM using the JNI Invocation APIs [F97][JNI97]
and then call jeInitJavaRuntime().
jeVersion
Returns the version of J-Empower being used
JRESULT jeVersion(
int *majorVersion,
int *minorVersion
);
Parameters:
majorVersion Points to an integer in where major version is
stored
minorVersion Points to an integer in where minor version is stored
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
int majorVersion, minorVersion;
jeVersoin(&majorVersion, &minorVersion);
}
Note:
This API returns the version of J-Empower not the JDK. If you wish
to acquire the version of the underlying JVM, use JNI's GetVersion()
[JNI97].
jeConsoleSetVisible
Show or hide the Java output console window
JERESULT jeConsoleSetVisible(
);
Parameters:
show Specifies how the console should be shown.
The parameter can be:
TRUE show window
FALSE hide window
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
switch (msg) {
case WM_USER_SHOWCONSOLE:
jeConsoleSetVisible(TRUE);
break;
case WM_USER_HIDECONSOLE:
jeConsoleSetVisible(FALSE);
break;
...
}
}
Notes:
The Java Console window is always created when you start the Java runtime.
The console window is initially created hidden.
jeConsoleIsVisible
Retrieves the show state of the console
JERESULT jeConsoleIsVisible(
);
Parameters:
visible Points to an integer that receives the show state.
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
int shown;
jeConsoleIsVisible(&shown);
jeConsoleSetVisible(!shown);
}
jeRegisterShowConsole
Register a function that will be passed all System.out and System.err
messages.
JERESULT jeRegisterShowConsole(
);
Parameters:
fnPtr Points to C function that processes System.out and System.err
messages.
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
int PrintConsoleInfo(const char *pszConsoleString)
{
printf( "Console = %s", pszConsoleString);
return(TRUE); // the console will not display this message. We've handled it.
}
{
jeRegisterShowConsole( &PrintStatusInfo);
}
Note:
The function registered can suppress all messages to the console by
returning TRUE. Although messages can be supressed they cannot be changed.
If FALSE is returned the message is also echo'ed to the console.
jeGetProperty
query the value or length of a given property
JERESULT jeGetProperty (
const char *key,
char *value,
int valueLength,
int *trueLength
);
Parameters:
key Points to a null-terminated string specifying
the property key.
value Points to a null-terminated string that retrieves
the value.
valueLength The length of the value string.
If valueLength is smaller than the actual length
of the value retrieved, the initial valueLength
characters are copied.
If valueLength is 0, the required length is stored
in trueLength.
trueLength Points to an integer that retrieves the
true length of the property.
Returns:
If the function succeeds, the return value is JE_OK, otherwise the function
failed.
Example:
{
const char *key="BOZO"; // property key name
char *value; // property value
int valueLength; // length of property value
jeGetProperty(key, 0, 0, &valueLength); // query length of "BOZO" property
value=malloc(valueLength+1); // add one for null terminator
if (value) {
jeGetProperty(key, value, valueLength+1, &valueLength);
} else {
// memory error
}
}
Note:
Properties are shared across an entire Java runtime.
Therefore, any applet can query/set properties created by other applets
provided that they have the proper security . One must carefully consider
(from a security perspective) how properties are used in applets. Any applet
can get to any other applets property.
This function is very useful if you need to pass variable
information between Java and your C program.
jeSetProperty
Set the value of a given property
JERESULT jeSetProperty (
const char *key,
const char *value
);
Parameters:
key Points to a null-terminated string specifying the property
key.
value Points to a null-terminated string specifying the property
value.
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
const char *key="BOZO"; // property key name
const char *value="A Clown"; // property value
jeSetProperty(key, value);
}
Note:
See Note for jeGetProperty.
jeInitAppletRuntime
Initializes the applet runtime.
JERESULT jeInitAppletRuntime();
Parameters:
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
jeInitAppletRuntime();
}
jeAppletInit
Creates and initializes an applet.
JERESULT jeAppletInit(
JEAPPLETHND *appHnd,
JECONTEXTID contextID,
JENATIVEWND parent,
const char *documentURL,
const char *code,
const char *object,
const char *codebase,
long width,
long height,
int parmCount,
const char **parms
);
Parameters:
appHnd Points to an JEAPPLETHND structure that retrieves the
applet handle.
contextID The context to which the applet belongs to.
parent The parent window handle.
documentURL The base document URL.
code The java applet class.
object The serialized version of the applet.
codebase The java applet codebase.
width The width of the applet.
height The height of the applet.
parmCount The number of parameters
parms An array of parameter strings
Returns:
If the function succeeds, the return value is JE_OK, otherwise the function
failed.
Some possible error values are:
JE_INVALID_PARENT invalid parent parameter
JE_INVALID_PARAMETER invalid parameter passed
Example:
{
JENATIVEWND hwndParent = (JENATIVEWND)WinQueryDesktopWindow(0);
JEAPPLETWND hApplet;
JECONTEXTID contextID = 1;
char *argv[7]; // holds the 4 applet parameters
long height, width; // applet height and width
height = 160;
width = 460;
argv[0] = "imagesource=images/Beans"; // set the applet parameters
argv[1] = "backgroundcolor=0xc0c0c0";
argv[2] = "endimage=10";
argv[3] = "soundsource=audio";
argv[4] = "soundtrack=spacemusic.au";
argv[5] = "sounds=1.au|2.au|3.au|4.au|5.au|6.au|7.au|8.au|9.au|0.au";
argv[6] = "pause=200";
jeAppletInit(&hApplet, contextID, hwnd,
file:////java/demo/Animator/","Animator",
NULL, NULL,
width, height, 7, argv);
}
Notes:
Either code or object must be present.
If object is present, the init() method of the applet will not be
invoked, but the start() method will.
The ARCHIVE tag can be passed as a parameter.
The documentURL must end with a trailing "/" if a directory is specified.
The code parameter can optionally contain ".class" as the suffix.
The applet window created is initially invisible.
jeAppletStart
Starts an applet that has been stopped or initialized.
JERESULT jeAppletStart(
);
Parameters:
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Some possible error values are:
JE_INVALID_CONTEXT the context which this applet belonged to no longer
exists
Example:
{
if (hApplet) {
jeAppletStart(hApplet);
}
}
jeAppletStop
Stops a started applet.
JEREUSLT jeAppletStop(
);
Parameters:
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Some possible error values are:
JE_INVALID_CONTEXT the context which this applet belonged to no longer
exists
Example:
{
if (hApplet) {
jeAppletStop(hApplet);
}
}
jeAppletDestroy
Destroys an applet.
JERESULT jeAppletDestroy(
);
Parameters:
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Some possible error values are:
JE_INVALID_CONTEXT the context which this applet belonged to no longer
exists
Example:
{
if (hApplet) {
jeAppletDestroy(hApplet);
}
}
jeAppletGetStatus
Retrieves the status of an applet.
JERESULT jeAppletGetStatus (
JEAPPLETHND applet,
int *status
);
Parameters:
applet An applet handle.
status Points to an integer that retrieves the status.
Possible values are:
JE_APPLET_STATUS_DISPOSED the applet is disposed
JE_APPLET_STATUS_LOADING the applet is loading
JE_APPLET_STATUS_INITED the applet is initialized
JE_APPLET_STATUS_STARTED the applet is started
JE_APPLET_STATUS_STOPPED the applet is stopped
JE_APPLET_STATUS_DESTROYED the applet is destroyed
JE_APPLET_STATUS_ERROR an error occurred with applet initialization.
jeAppletsIconify
Notify all applets within a context that your application has been
minimized. All applets in the given context are stopped.
JERESULT jeAppletsIconify (
);
Parameters:
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Some possible error values are:
JE_INVALID_CONTEXT the context which this applet belonged to no longer
exists
Example:
case WM_MINMAXFRAME:
{
PSWP pswp=(PSWP)mp1;
LONG flags=pswp->fl;
if (flags & SWP_MINIMIZE)
jeAppletsIconify(contextID);
}
break;
jeAppletsUniconify
Notify all applets within a context that your application has been
restored . All applets in the given context are started.
JERESULT jeAppletsUniconify (
);
Parameters:
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Some possible error values are:
JE_INVALID_CONTEXT the context which this applet belonged to no longer
exists
Example:
case WM_MINMAXFRAME:
{
PSWP pswp=(PSWP)mp1;
LONG flags=pswp->fl;
if (flags & SWP_RESTORE)
jeAppletsUniconify(contextID);
}
break;
jeAppletsDestroy
Destroy all applets within a given context.
JERESULT jeAppletsDestroy (
);
Parameters:
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Some possible error values are:
JE_INVALID_CONTEXT the context which this applet belonged to no longer
exists
Example:
case WM_DESTROY:
jeAppletsDestroy(contextID);
break;
jeRegisterShowDocument
Register a function that will follow a URL link.
JERESULT jeRegisterShowDocument (
jeShowDocumentFnPtr fnPtr
);
Parameters:
fnPtr Points to a C function to process URL link.
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
void BrowserFollowURL( JECONTEXTID id, const char *pszURL, const char *target)
{
...
}
{
jeRegisterShowDocument( &BrowserFollowURL);
}
Note:
This function will register a procedure that understands how to follow
URL links. For example, a Java applet might contain a hyperlink to a web
page. If this link is selected, your registered function will be called
upon to "follow the URL link". In this case, "follow the URL link" might
mean render the web page.
The function registered by jeRegisterShowDocument is invoked when an applet
invokes the AppletContext.showDocument(URL) or AppletContext.showDocument(URL,
String target). This allows the application to show a new document
in the target window or frame. The "valid" targets are located in the Java
API document under AppletContext, which are _self, _parent, _top, and _blank.
jeRegisterShowStatus
Register a function that will be passed all applet status information.
JERESULT jeRegisterShowStatus (
);
Parameters:
fnPtr Points to a C function to process status messages
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
int PrintStatusInfo(JECONTEXTID id, const char *pszStatusString)
{
printf( "Status = %s", pszStatusString);
}
{
jeRegisterShowStatus( &PrintStatusInfo);
}
Note:
This function will allow you to intercept status messages that an applet
sends to the Java console.
The function registered can suppress all messages to the console by returning
TRUE. Although messages can be supressed they cannot be changed. If FALSE
is returned the message is also echo'ed to the console status area.
jeBeanInstantiate
Instantiate a bean.
JERESULT jeBeanInstanitate (
JEBEANHND *bean,
const char *beanName
);
Parameters:
bean Points to a JEBEANHND that retrieves the handle to a bean.
beanName Points to a null-terminated string that represents the
name of a serialized object or a class name.
The name of the bean should be a dot-separated name such as "a.b.c".
When using the bean name as a serialized object, the suffix ".ser" is added
to the bean name.
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
JEBEANHND bean;
...
case WM_CREATEBEAN:
jeBeanInstantiate(&bean, "java.awt.Frame");
break;
}
jeBeanEmbed
Embed a GUI bean within a window.
JERESULT jeBeanEmbed (
JENATIVEWND parent,
JEBEANHND bean
);
Parameters:
parent The parent window handle.
bean A bean handle.
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
case WM_EMBEDBEAN:
jeBeanEmbed(hwnd, bean);
break;
}
Note:
Only GUI beans may be embedded. An error is returned if the bean does
not inherit from java.awt.Component.
If a bean inherits from java.awt.Frame, the bean is not embedded
within a new frame.
jeBeanDispose
Destroys a bean.
JERESULT jeBeanDispose (
);
Parameters:
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
case WM_DESTROYBEAN:
jeBeanDispose(bean);
break;
}
Note:
This must be called for every bean created with jeBeanInstantiate().
If the bean is embedded, the embedding window will be destroyed. The embedding
window should not be destroyed directly.
jeBeanSerialize
Save a bean to a file.
JERESULT jeBeanSerialize(
JEBEANHND bean,
const char *filename
);
Parameters:
bean A bean handle.
filename Points to a null-terminated string that represents the
filename.
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
case WM_SAVEBEAN:
jeBeanSerialize(bean, "bean.sav");
break;
}
jeBeanDeserialize
Load a bean from a file.
JERESULT jeBeanSerialize(
JEBEANHND *bean,
const char *filename
);
Parameters:
bean Points to a bean handle that retrieves the bean.
filename Points to a null-terminated string that represents the
filename.
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
case WM_LOADBEAN:
jeBeanDeserialize(&bean, "bean.sav");
break;
}
jeObjectFromBean
Retrieve the global jobject reference of a bean
jobject jeObjectFromBean (
);
Parameters:
Returns:
If the function succeeds, the return value is the jobject representing
the bean.
Example:
{
if (bean) {
jobject jBean = jeObjectFromBean(bean);
}
}
jeMove
Move and resize an applet/bean.
JERESULT jeAppletMove (
JEHND handle,
long x,
long y,
long width,
long height,
int repaint
);
Parameters:
handle An applet/bean handle.
x The new x position.
y The new y position.
width The new width.
height The new height.
repaint Specifies whether the applet is to be repainted.
If this parameter is TRUE, the window receives a
WM_PAINT message. If the parameter is FALSE, no repainting
of any kind occurs.
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
// resize applet to client window size.
if (hApplet) {
jeMove( hApplet, 100, 100, 150, 150, TRUE);
}
}
jeShow
Show or hide an applet/bean.
JERESULTjeShow (
);
Parameters:
handle An applet/bean handle
show Specifies how the applet should be shown.
The parameter can be:
TRUE show applet
FALSE hide applet
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
{
switch (msg) {
case WM_USER_SHOWAPPLET:
jeShow(hApplet, TRUE);
break;
case WM_USER_HIDEAPPLET:
jeShow(hApplet, FALSE);
break;
}
}
jeResize
Change an applet's/bean's dimensions.
JERESULT jeResize (
JEHND handle,
long width,
long height
);
Parameters:
handle An applet/bean handle.
width The new width.
height The new height.
Returns:
If the function succeeds, the return value is JE_OK, otherwise the
function failed.
Example:
case WM_SIZE:
// resize applet to client window size.
if (hApplet) {
jeResize( hApplet, SHORT1FROMMP(mp2), SHORT2FROMMP(mp2));
}
break;
jeHWNDFromHandle
Retrieve the native HWND (window handle) of the J-Empower container
from an applet/bean handle.
JENATIVEWND jeHWNDFromHandle (
);
Parameters:
Returns:
If the function succeeds, the return value is the window handle.
If the applet/bean has no window handle, the return value
is NULL
Example:
{
if (hApplet) {
JENATIVEWND hwnd=jeHWNDFromHandle(hApplet);
SetWindowPos((HWND)hwnd, HWND_TOP, 0,0,0,0,SWP_NOSIZE);
}
}
Notes:
JENATIVEWND is the type used for window handles in the native operating
system. For example, it is an HWND on WIN32 and OS2, an X Window under
UNIX, etc. To avoid having to load os2.h, windows.h, etc in this header
file, we are declaring as an opaque pointer to a struct. When using the
functions that take an JENATIVEWND (jeAppletInit and jeHWNDFromHandle),
explicitly cast to and from HWND, Window, or whatever.
References
[G+96] G. Cuomo, M. Fraenkel, R. Redpath and J. Eisen. "4/25/97J-Empower:
An API for caffeinating your native application!." Version 1.0, May 1996
[F97] M. Fraenkel. "An Example using the Java Native Interface(JNI) in
a Native Application." TR 29.2226, January 1997
[JB96] Sun Microsystems Inc. "Java Beans 1.0." Version 1.00-A, December
1996
[JNI97] Sun Microsystems Inc. "Java Native Interface Specification." Release
1.1, February 1997