Java AWT Native Interface: Difference between revisions

Revision as of 02:58, 16 March 2023

Revision as of 00:49, 5 August 2023

Line 1:

{{Multiple issues|{{unreferenced|date=June 2023}}

{{unreferencedoriginal research|date=June 20122023}}

{{original researchtone|date=June 20122023}}}}

{{tone|date=June 2012}}

}}

The definition of Java Standard Edition includes JNI, the Java Native Interface. Most Java developers will never need to use it, but the interface is invaluable in certain situations because it provides the only way for Java byte code to interact directly with application code that has been compiled to the native machine instructions for the host microprocessor. JNI is most often used as an ``escape valve<nowiki>''</nowiki> to enable access to platform functionality not yet supported by the Java programming language. For example, you could use JNI to integrate with native code that communicates with a peripheral device, such as a scanner, connected to a system via a USB port.

'''Java AWT Native Interface''' ('''jawt''') is an interface for the [[Java (programming language)|Java programming language]] that enables [[Rendering (computer graphics)|rendering]] [[library (computer science)|libraries]] compiled to [[native code]] to draw directly to a Java [[Abstract Window Toolkit]] (AWT) {{Javadoc:SE|java/awt|Canvas|module=java.desktop}} [[object (computer science)|object]] drawing surface.

Of course, JNI is general enough to be used to access almost any sort of native library, regardless of whether the task to be accomplished could also be done using pure Java. The major penalty for using it is that code portability suffers, but this may be acceptable or even necessary for business or technical reasons.

The [[Java Native Interface]] (JNI) allows developers to add platform-dependent functionality to Java [[application software|applications]]. The JNI enables developers to add time-critical operations like mathematical calculations and [[3D rendering]]. Previously, native 3D rendering was technically challenging because the native code didn't have access to the graphic context. The AWT Native Interface is designed to give developers access to an AWT <code>Canvas</code> for direct drawing with native code. In fact, the [[Java 3D]] API extension to the standard [[Java SE]] [[JDK]] relies heavily on the AWT Native Interface to render 3D objects in Java. The AWT Native Interface is very similar to the JNI, and, the steps are, in fact, the same as those of the JNI. See the [[Java Native Interface]] article for an explanation of the JNI techniques employed by the AWT Native Interface. The AWT Native Interface was added to the [[Java platform]] with the [[Java Platform, Standard Edition|J2SE]] 1.3 ("Kestrel") version.

Business reasons? Consider the situation where the legacy software you are trying to port to Java uses a third-party library for a critical set of operations. If you do not have source rights to this library and you cannot convince the owner to provide a Java version, you may not be able to use it. Even if you do have the source, the effort needed to port a standard library to Java and test it may be too expensive to consider.

== AWT Native Interface steps ==

{{howto|date=June 2012}}

A complete walkthrough example of this technology is available on Wikibooks (see link below).

Another important reason for leaving the native code alone is related to performance. If you are dealing with a finely crafted piece of code, carefully tuned for performance over the course of years, you probably do not want to convert it to Java and risk a performance penalty. It is usually best to keep it intact until you are satisfied that the benefits of Java portability and code maintainability outweigh the expected performance difference.

=== Create a Java application ===

See the [[Java Native Interface]] article for an explanation of the <code>native</code> [[keyword (computer programming)|keyword]] and the <code>loadLibrary()</code> method. A <code>paint()</code> method will be simply invoked when the AWT [[event dispatching thread]] "repaints" the screen.

A rendering library is a good example of a piece of native code that most developers would just as soon leave alone for performance reasons. Unfortunately, this is the very type of library that has been most difficult to integrate with Java code through JNI. The fundamental problem has been that the rendering code cannot identify where to draw. It needs access to information about a Java drawing surface (such as a handle to the underlying peer of a <code>Canvas</code>), but cannot get it.

=== Create a C++ header file ===

Create the [[C++]] [[header file]] as usual. (See [[Java Native Interface]] for more complete explanations.)

Until now, the Java platform has kept access to this information private — "private" in the sense of undocumented, unsupported, and deprecated. The good news is that this situation will be remedied with the introduction of the "AWT Native Interface" in the Java upgrade release ("Kestrel"). For the first time there will be an official way to obtain all the information you need to know about the peer of a Java <code>Canvas</code> so that you can draw directly to the <code>Canvas</code> from a native code library using the drawing routines provided by the operating system.

=== Implement the C++ native code ===

Type this in a file named "NativeSideCanvas.cpp" and compile into a library. See [[Java Native Interface]] (JNI) for a more complete explanation. (For [[Solaris (operating system)|Solaris]] code and other operating systems see links below.)

=== Run the program ===

One should run the file as usual. One should then see a window with, for example, a rectangle drawn in it. (See [[Java Native Interface]] for complete instructions.)

Note: One can notice that the AWT Native Interface requires the "jawt.dll" (or "jawt.so") to run with the application, so the easiest way to do that is copying the "jawt.dll". (should be in the .../jre/bin [[file path]] of the JDK's installation path.){{citation needed|date=June 2012}}

== Native painting ==

One can paint as if it is a native application. In [[Microsoft Windows|Windows]], the JVM will pass a HWND and other window information to the native application so that the application will "know" where to draw. It could use GDI to draw a Rectangle. The window information the native side needs will be in a <code>JAWT_Win32DrawingSurfaceInfo</code> structure (depending on [[Operating System]]) which can be retrieved with this line: {{code|lang=c|1=dsi_win = (JAWT_Win32DrawingSurfaceInfo*)dsi->platformInfo;}}

== External links ==

{{Portal|Computer programming}}

{{Wikibooks|Java Swings/AWT}}