Items not to be exposed to the SWIG mapscript interface

[tbonfort]

Reporter: szekerest Date: 2006/02/12 - 23:59

The items exposed to the mapscript interface should be selected by the
developers will, by using the SWIG define in the MapServer header files. In
practice it involves hiding the items not to be exposed explicitly by using
#ifndef SWIG properly in the headers.

However not all of the developers are interested in (or not aware of) SWIG, not
using theese defines may result many of the items exposed unwantedly (especially
ver 8.6.1 suffers from this issue). This incident may result in at least the
following drawbacks:

1. Items exposed inadvertently may destabilize interface, because the users
might want to use those items causing inconsistent data structure and unexpected
execution flow.
2. The interface may be less perspicuous having myriads of new objects,
constants and functions.
3. By allowing the possibility of using undocumented items, compatibility of the
existing code may be broken unexpectedly.
4. Some of the data types may cause additional objects that could not be mapped
to the target language with the SWIG interface generator making the interface
more unclear.

To reduce the effect mentioned previously the interface should be rewised
carefully and the unwanted elements should be suppressed (by using #ifndef SWIG
directives). At a first sight it could be done by hiding (or changing) the
following items:

1. struct layerVTable map.h (1338, 1052, 1137)
2. struct graticuleObj map.h (1026)
3. struct SVGObj map.h (1291)
4. enum FilterNodeType  map.h (589)
5. struct _FilterNode   map.h (605)
6. mapObj.paletteObj    map.h (1242)
7. mapObj.geotransformObj map.h (1233)
8. hashObj maphash.h  (59)
9. hashTableObj (to be changed) maphash.h  (67)
10. maphash.h static functions 
11. msTiledSHPLayerInfo mapshape.h (182)  (only internally used)
12. vectorObj mapprimitive.h (58)  (only internally used)
13. cgi utility functions cgiutil.h (20)  accessed by OWSRequest

I am not sure about the shapelib items: DBFInfo and DBFFieldType. It seems those
items are intentionally exposed, but the current implementation is unusable by
many of the  languages. At least msDBFOpen and msDBFClose should be exposed as
well. Editing support may be considered by using msDBFCreate, msDBFAddField ..
but in this case the creation of the shape files should be supported accordingly.

The previous list of changes does not contain any constants, however some
constants may fall outside of the scope of the MapScript interface.

To avoid theese situations and make the developers aware of the SWIG issues a
new RFC should be made or existing should be changed (RFC7 is a good candidate
to it).

Tamas Szekeres

[tbonfort]

Author: szekerest Date: 2006/02/13 - 00:13

Added Steve as he indicated his interest of this issue.

[tbonfort]

Author: sgillies@frii.com Date: 2006/02/18 - 21:57

Tamas, I apologize for the delay in responding to this.

Could you please make diffs against the CVS HEAD? We won't be applying these to
MapServer 4.8, which is pretty much frozen except for fixing things that are
broken. The current state of exposed objects in 4.8 is not really broken, but
more of a wart.

Diffs will also make it really easy for us to see what exactly has been changed.

Thanks for the input! Once I have the diffs, I'll poke Steve and see about
making the changes.

[tbonfort]

Author: sdlime Date: 2006/02/22 - 06:15

I've applied the patch (thanks Tamas!) to CVS. Worked fine. Perl MapScript
compiles just fine. Marking as fixed. 

Perhaps we should consider some documentation about properly adding to the
headers and how to hide things from Swig?

Steve

[tbonfort]

Author: szekerest Date: 2006/03/19 - 19:12

Committed to Branch-4-8

Tamas