JavaMapscriptUsing
Many people ask questions about Java Mapscript on mapserver-users. This is an attempt to record my answers to them, my impressions on mapserver and Java Mapscript. Before you proceed I must warn you that the following are my opinions and they might not be endorsed or approved by the mapserver community at all.
Most of this is LINUX specific, but some is general.
Guidelines for building a working Java Mapscript.
Mapserver is really a big piece of software with plenty of functionalities (some say it is the most advanced web
mapping software) and chances are you do need all of them. If you are a newbie to mapserver
or to Java mapscript try to understand what you need and stick with it, removing the unneeded features.
This approach is generally suggested because:
- it reduces the number of lines of code involved and thus reduces the number of possible bugs that could bite
- it makes for a smaller binary which is more efficient
- in case of a crash the number of suspects is lower and will speed up investigation and in some cases resolution
- it requires less software to be installed on your computer which makes it easier to mantain in the long term
- the first three items apply (with recursion) to the previous
- if you ask for help on the mailing list the first general advice is to remove components you don't use: so do it in advance
See below for a example of a basic (but working) mapserver/mapscript build example.
Chances are that even if you do not need tiff or mysql support it will get built in anyway because the configure script detects their libraries. In all cases you should review the output of the configure script and then use the proper command line argument to disable unwanted features.
When running the ./configure program use the --disable-X option. You can get the list of available options by running:
./configure --help
Certain libraries/features are known NOT to work with mapscript because they are not thread-safe.
Be sure not to enable them at compile time or you will get errors that will crash the JVM.
You can review the list of unsafe components 
here.
If you need raster support through GDAL disable tiff (using --without-tiff) because they don't play well with each other.
PDF is supported as an output format, but it is not worth the price of risking a buggy mapscript. A better solution is to incorporate the image in a PDF document by using a pure Java library like the excellent iText.
By doing so you will be able to customize headers, footers, paper format and transparencies will also work as supposed. iText additionally supports PDF encryption to disallow printing, editing or modification.
Also remember that PDF output in mapserver cannot make use of an embedded scalebar because pixmap fonts are not supported.
Connection pooling is locked hence thread safe, but as of version 4.8.x (that is until Feb 2006)
it has known memory leaks. There is an issue on bugzilla that tracks this problem with Oracle.
http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=1662.
Until that is cleared you can use connection pooling, just make sure that once in a while the application is restarted or you will eventually run out of memory. How often this should happen depends on the number of database connections defined in the map and the number of users. Sites with 1 or two database connections and moderate to low use could reboot the application (that is the tomcat process in case of web apps) once a day.
Java Mapscript will NEVER work without the following configure flag: --with-threads. Do not complain about you JVM going belly up on the mailing lists if you do not have enabled this option.
To use mapserver and mapscript you will quite likely need to download and install
many other libraries and this might not particularly easy as most of
them (gdal, for instance) do not have a binary rpm for linux.
You have then to find, download all of them and install one by one, solving
dependencies by hand. If this is not what you want and need a more portable
,reliable and easier to deploy environment you should seriously consider
fwtools. Fwtools is collection of the most popular
libraries used with mapserver already compiled and ready to run on almost
any linux distribution.
This section describes how to compile mapserver
and Java mapscript against fwtools.
The proper way to compile is to carefully select options as described above, then to run make, cd into mapscript/java and run:
make interface
make
make test
Make interface requires that you have swig installed, at least version 1.3.21.
My configure options to build mapscript with support for raster (through gdal), truetype fonts (through freetype), shape files (native, cannot be disabled), projection (through proj) are:
./configure --with-freetype --without-tiff --with-gdal=/opt/gdal/bin/gdal-config --with-proj --without-pdf --with-threads
These are known to work (for me at least :-)) and are used in production sites. Note that proj, even if it not used, is required for good operation of mapserver.
Download fwtools and install it. I usually install it in /opt/FWTools-1.0.0b2.
Cd into the lib subdirectory and run the following two commands:
ln -s libpng.so.2 libpng.so
ln -s libfreetype.so.6 libfreetype.so
This is required for mapserver configure script to find and use the freetype and png libraries shipping with fwtools.
Download latest mapserver and unpack it, then compile it with the following configuration:
./configure --enable-debug --with-threads --without-pdf --without-tiff \
--with-gdal=/opt/FWTools-1.0.0b2/bin/gdal-config --with-proj=/opt/FWTools-1.0.0b2/ \
--with-gd=/opt/FWTools-1.0.0b2 --with-freetype=/opt/FWTools-1.0.0b2 \
--with-png=/opt/FWTools-1.0.0b2 --with-zlib=/opt/FWTools-1.0.0b2 --with-jpeg=/opt/FWTools-1.0.0b2
Before you run mapserver or mapscript make sure you load the fwtools environment by running /opt/FWTools-1.0.0b2/fwtools_env.sh.
When I first used Java mapscript in 2003 running swig was a necessary prerequisite to generate the Java and c wrapper files as the source distribution did not have any. There was a problem though: swig would generate Java methods and c wrappers for all mapserver components (like postgis, wfs or ogr) regardeless of the fact that they were enabled in the configure phase.
Then I submitted bug #876 along with a patch which would
let swig know of which components were enabled and consequently generate Java and c wrappers only for them.
For the patch to work the user had to run make interface.
The problem then was that a rather new version of swig was required, which was not available on all distros
so the developers decided to provide a default version of the Java and c wrappers to help those who
did not have a recent swig (at least 1.3.21). That issue should be overcome by now as all
linux distros should ship with a swig version that is two years old!
So, if you have a recent version of swig (run swig -version to know) you should run make interface
to update your Java and c wrappers, even if the README does not recommend it.
To correctly run any Java Mapscript application (be it a servlet, jsp page or a standalone graphical client) you need to let the Java Virtual Machine know where to find two pieces of software:
-
libmapscript.so whose role is to tie together mapserver and Java
-
mapscript.jar which provides the mapserver Java objects which interface with libmapscript.so
