MapServer 4.8 to 4.10 Migration Guide ===================================== This page documents the changes that must be made to MapServer applications when migrating from version 4.8.x (or earlier versions) to 4.10.x (i.e. backwards incompatibilities), as well as information on some of the new features. ---------------------------------------------------- SWIG MapScript (Python, Perl, Csharp, Java) changes ---------------------------------------------------- Immutable internal structures ------------------------------ According `bug 1803`_ setting the following object members were identified as potential unsafe operations causing unexpected access violations and were made immutable (read-only). The members are created by default so there's no need to create those from scratch. :: layerObj.metadata classObj.label classObj.metadata fontSetObj.fonts legendObj.label mapObj.symbolset, mapObj.fontset mapObj.labelcache mapObj.reference mapObj.scalebar mapObj.legend mapObj.querymap mapObj.web mapObj.configoptions webObj.metadata The common characteristic of the members is that those are internal structures (not references to external objects) having subsequent references. By allowing to set these items one could use the following code to set the object. :: mapObj map = new mapObj("mymap.map"); webObj web = new webObj(); web.imagepath = "/tmp/"; web.imageurl = "http://"); map.web = web; Setting the mapObj.web member a shallow copy of the structure takes place. The subsequent references of the webObj are not be copied becoming candidates to be destroyed twice. Instead of creating a new object the already created one should be read and used as: :: mapObj map = new mapObj("mymap.map"); webObj web = map.web; web.imagepath = "/tmp/"; web.imageurl = "http://"); Immutable references to parent objects -------------------------------------- The following object members are references to parent objects and were also made immutable. The values of these members are set internally. It makes no sense to set these items since the parent-child relationship between the objects are set by other member functions like (insertClass). :: classObj.layer legendObj.map webObj.map referenceMapObj.map Setting these members should be avoided. imageObj.format now immutable ----------------------------- imageObj.format is now immutable can can no longer explicitly be set with an assignment operation. shapeObj.initValue and default values ------------------------------------- When constructing a new shapeObj 4 predefined values were implicitly created that could be accessed and modified using getValue and setValue. Using this shape as a parameter of other functions like layerObj.getShape might result in memory leak.So as to allow explicit creation of the values the shapeObj.initValues was introduced. The user can initialize arbitrary number of the values and use getValue and setValue to access them. Beware of using these objects as out parameters. layerObj.labelitemindex, .labelsizeitemindex, .labelangleitemindex ------------------------------------------------------------------ These members were hidden entirely from the SWIG interface since the elements are handled internally. Setting these elements for the interface might cause access violations. (See bug 1906) ---------------------------------------------------- libgd ---------------------------------------------------- 1px Anti-Aliasing and segfaults -------------------------------- libgd has apparently fallen out of maintenance by its primary developer. A release has not been made since 11/03/04 (libgd 2.0.33), and one very significant bug will *always* cause a segfault when using this library without a patch and you attempt to do one pixel wide antialiasing. In gd.c, function gdImageSetAAPixelColor() change: :: int dr,dg,db,p,r,g,b; p = gdImageGetPixel(im,x,y); to :: int dr,dg,db,p,r,g,b; if (!gdImageBoundsSafeMacro (im, x, y)) return; p = gdImageGetPixel(im,x,y); More detail about this patch (if you need any) was described by Steve Lime in a `post to mapserver-users`_. *NOTE*: Windows builds that are built with the buildkit (this includes MS4W) have this patch already and do not need to be updated. Curved label support -------------------- ANGLE FOLLOW, a new feature that allows MapServer to draw curved labels about a linear feature like a road, requires libgd 2.0.29 and TrueType font support. Configure should autodetect if you have a sufficient libgd and TrueType support to be able to use this feature. ---------------------------------------------------- GEOS ---------------------------------------------------- As of version 4.10, MapServer now uses the GEOS C API for doing geometric algebra and predicate operations. All of the operators available to the GEOS C API are available in MapScript. Some operators are available through the MapServer CGI interface. See the `SWIG MapScript`_ for details. Multiple subsystems' use of the GEOS C API ------------------------------------------ It is important to note that both OGR and the Python Cartographic Library (and possibly other applications linked to the GEOS C API within the same process) also can (and often do) take advantage of the GEOS C API. A bug in GEOS 2.2.2 and 2.2.3 will cause a segfault during teardown as a result of the C API keeping its global GeometryFactory around and not properly accounting for it. GEOS 3.0 should do the right thing in this instance. .. _`SWIG MapScript`: http://mapserver.gis.umn.edu/docs/reference/mapscript .. _`bug 1803`: http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=1549 .. _`post to mapserver-users`: http://article.gmane.org/gmane.comp.gis.mapserver.user/17766 ---------------------------------------------------- Java Mapscript and ENUMERATED VALUES ---------------------------------------------------- Since the Java language lacks support for enums (it's been added in version 5, but not everybody uses that) java mapscript historically had enumerated values like MS_IMAGEMODE exposed as static integers in the mapscriptConstants interface or in its implementor, the mapscript class. Starting with Swig 1.3.24 the wrapper *by default* will generate specific classes for named enums and keep anonymous enums in the mapscriptConstants class. This has the side effect that code generated by older versions of swig will not be portable to that generated by swig >= 1.3.24. FIX --- You can instruct swig to revert to the old behaviour by uncommenting line 6 in mapscript/java/javamodule.i List of changed enums --------------------- MS_BITMAP_FONT_SIZES MS_CAPS_JOINS_AND_CORNERS MS_CONNECTION_TYPE MS_FILE_TYPE MS_FONT_TYPE MS_IMAGEMODE MS_JOIN_CONNECTION_TYPE MS_JOIN_TYPE MS_LAYER_TYPE MS_POSITIONS_ENUM MS_QUERYMAP_STYLES MS_REQUEST_TYPE MS_RETURN_VALUE MS_SHAPE_TYPE MS_SYMBOL_TYPE MS_UNITS ---------------------------------------------------- OGC Web Mapping Service (WMS) ---------------------------------------------------- WMS GetFeatureInfo in text/plain format --------------------------------------- Before MapServer 4.10, WMS GetFeatureInfo output in text/plain format used to always return the values of *all* attributes for the selected shapes in a given layer and there was no way to control which attributes would be returned. This was a problem for WMS server administrators who needed to control the list of attributes to return or to hide some attributes from the underlying dataset. Starting with MapServer 4.10, the behavior of text/plain GetFeatureInfo output has been brought in sync with that of GML output: by default no attributes are returned unless the wms_include_items and wms_exclude_items layer-level metadata are used. (See bug 1761) For more details see the gml_include_items and gml_exclude_items layer object metadata docs in the WMS Server HOWTO at http://mapserver.gis.umn.edu/docs/howto/wms_server/#layer-object-metadata The GML output is controlled with gml_include_items and gml_exclude_items. The text/plain output is controlled with wms_include_items and wms_exclude_items. Both GML and text/plain can also be configured using a common pair of ows_include_items and ows_exclude_items layer-level metadata entries. ---------------------------------------------------- OGC Web Feature Service (WFS) ---------------------------------------------------- Requirement for gml_featureid ----------------------------- The WFS 1.0.0 specification states that the 'fid' attribute on GML features returned in response to a GetFeature is required (see bug 1759). Since MapServer 4.8 it was already possible to specify the attribute to use as fid using the "gml_featureid" metadata, but that was not a requirement. MapServer 4.10 has been modified to produce a warning in the GetCapabilities and GetFeature output if the gml_featureid metadata is not set or if the item that it refers to does not exist in the layer (see bugs 1781 and 1782).