News Operations
Browse Space | Warning This is an optional installation step that is only required if:
This should be considered under construction - please revise if needed. |
Java Advanced Imaging
Where to get it
The Java Advanced Imaging most complete download page can be found here.
In this small guide I will show how to install JAI using the latest stable discribution (which at moment is 1.1.3).
What we get
It is worth to point out that JAI is a Java library that can use native acceleration through SUN MediaLib on some platforms, namely Windows, Solaris and Linux (yes, there is no native acceleration on Mac at the moment, but it is planned). As a consequence the JAI library is made by a certain number of jar files plus some additional (OPTIONAL) native libs (dlls on Windows and so on Linux); all the jars files shipped with JAI must be installed but one could decide to not install the native libs, being aware that in some cases performances will degrade.
Let's briefly discuss what each single jar or lib will give us.
JAR files
| jai_core.jar | JAR file containing core JAI class files. | required |
| jai_codec.jar | JAR file containing JAI class files for doing I/O on some image formats. It is worth to point out that this so-called CODECS load and store images in various formats are deprecated in favour of using ImageIO extensions. | required |
| mlibwrapper_jai.jar | JNI interfaces for exploiting native mediaLib. | required |
Native Libs
| File name | Decription | Platform | |
|---|---|---|---|
| libmlib_jai.so | mediaLib JNI shared libraries, C version. | Linux | |
| mlib_jai.dll | mediaLib JNI DLL libraries, C version. | Windows | |
| mlib_jai_mmx.dll | mediaLib JNI DLL libraries, MMX version. | Windows | |
| mlib_jai_util.dll | A utility to detect whether MMX is available. | Windows | |
What to download
If you took a quck look at page you might have noticed that for the various platforms there are various options for installations, the ones we are interested in are as follows:
| file | platform | description | Purpose | Native Acceleration | |
|---|---|---|---|---|---|
| jai-1_1_3-lib-*****-jdk.* | ALL | Installation files for the JDK. This files is usually an executable that install the JAI version it ships in the first installed JDK. It usually contains both jars and native libraries for the SUN mediaLib image processing library. This installation should usually allow you to leverage on the native acceleration. | Required for developing with GeoTools | Y | |
| jai-1_1_3-lib-*****-jre.* | ALL | Installation files for the JRE. This files is usually an executable that install the JAI version it ships in the first installed JRE. It usually contains both jars and native libraries for the SUN mediaLib image processing library. This installation should usually allow you to leverage on the native acceleration. | Required for developing with GeoTools | Y | |
| jai-1_1_3-lib.zip | Cross-Platform | Pure Java Installation Files. This bundle contains a pure-Java installation of JAI without native libraries support. It is made up only by JAR files. | Required for developing with GeoTools | N | |
| jai-1_1_3-lib-platform.* | ALL | Installation files for the JDK. This files is usually an executable that install the JAI in the local filesystem without any check for the JDK or the JRE. On Windows for example they should get installed under C:\Program Files\Sun Microsystems\Java Advanced Imaging 1.1.3. | |
If you want to leverage on native acceleration I suggest to download both the JDK and JRE executables or the latter executable. If you want just to try out things and you want to really understand what is going on under the hood of JAI, please, download, the zip bundle.
What to do now
Zip bundle
This zip contains only jar files hence you need to follow instruction here below for placing JAR files.
JDK and JRE executables
In this case you downloaded two executables that should almost automagically install everything at the right place for you. Run them and follow the instructions (crossing your fingers) this should do it.
If you are trying to install on Linux, you'll first have to copye the .bin files into the JDK directory, and then run them. Due to a Solaris dependency the packages may fail to install reporting a checksumming failure. This is not the case, it's just that tail stopped supporting an old syntax.
To have the command run anyways, perform a "export _POSIX2_VERSION=199209" before running the binary scripts.
Standalone Executable
Where things are placed
Here we want to briefly discuss where things should be placed in order for GeoTools to work smoothly with coverages.
JAR files
The jar files, which I remark again are required, should be placed in the classpath for your application. In my opinion the best place where to put them is %JAVA_HOME%/jre/lib/ext where JAVA_HOME is the home of your java installation. However you might even want to bundle them in some other ways directly inside your application. The key thing is that they MUST be in the classpath.
 |
In case you have both JDK and JRE installed I would recommend putting all JAR files from JAI inside the /lib/ext dir of both installations. This is crucial to have GeoTools maven infrastructure (which relies on JRE) working properly |
Native Libs
If you want to leverage on the power of native libraries support the library version that applies to your platform must be reachable throught the PATH variable on your machine. In my opinion the best place where to put them is in %JAVA_HOME%/bin which usually is in the path on most systems with Java installed.
 | Getting strange warning about not loading mediaLib In case you see a warning message like the following when running your application: Error: Could not load mediaLib accelerator wrapper classes. Continuing in pure Java mode. Occurs in: com.sun.media.jai.mlib.MediaLibAccessorcom.sun.media.jai.mlib.MediaLibLoadException This means that you did not install properly the native libraries and then JAI is working in pure JAVA mode. |
 | Forcing Pure-Java mode JAI can be run without its native acceleration layer without loss of functionality. This may be accomplished by setting the JVM switch com.sun.media.jai.disableMediaLib to true, which means starting the JVM adding the following parameters: -Dcom.sun.media.jai.disableMediaLib=true |
Additional Information
Q: Why is mlibwrapper_jai.jar fatal?
A: Your one-click JAI installation already copied this jar for you AND signed it. If you use one provided by jai_imageio (that is not signed) everything will be broken. If this happens to you, uninstall & reinstall jai.
Q: What are the binary packages on the download page for (like jai-1_1_3-lib-windows-i586-jdk.exe )?
A: Most platform bundles for JAI provides prebuilt, all-in-one installation packages. This installation will place the needed files respectevely in the JRE, JDK and under Program Files/Sun Microsystems/JAI, but I would not recommend this approach since it might not fits for you and you cannot control it.
Additional detailed JRE instructions are available from the UDIG project:
Links: