[Mapserver-dev] Next Generation MapScript API

[Paul Spencer]

is this intended to affect the swig-generated mapscript API and the 
php_mapscript API?  There is a significant push to release 4.2 in the 
very near future and if this change is made, it is unlikely that 
php_mapscript could be rewritten to conform to the new API.

I would rather see the MapScript API NG reserved for the next mapserver 
release (4.4) which would give everyone more time to both implement and 
test for compatibility.  I must admit that I have a large toolkit built 
on php_mapscript that I am trying to release right now and it requires 
4.1/4.2 for many features, so I will have a very significant delay in 
releasing it if this change is implemented for 4.2 :(

Paul

Frank Warmerdam wrote:

> Sean,
> 
> I have been thinking a bit about your "next generation" MapScript API 
> and names
> and what the implications might be for backward compatibility.  For the 
> record,
> let me say that I am a huge fan of backward compatibility ... to a fault no
> doubt.
> 
> I would like to discuss what we can do to progress some of the naming
> conventions towards a "next generation" without undue breaking of backward
> compatibility.
> 
> First I will try to summarize the changes I think you are proposing in the
> next generation API.
> 
> 1) Change names of classes to not include the Obj suffix.  Basically use
>    the MapScript aliases Map, Layer, Class, Style, Image, Point, Line, 
> Shape,
>    OutputFormat, Symbol, Color, Rect, Projection, Shapefile, SymbolSet and
>    FontSet for the C level names map_obj, layer_obj, styleObj, imageObj,
>    pointObj, lineObj, shapeObj, outputFormatObj, symbolObj, colorObj,
>    rectObj, projectionObj, shapefileObj, symbolSetObj and fontSetObj.  The
>    primary effect of this is in constructors which now would look like
>    "x = mapscript.Map('adsf')" instead of "x = mapscript.map_obj('adsf')".
> 
> 2) Change the getShape() method to return the shapeObj (instead of updating
>    a shapeObj in place), and to place the tileindex after the shapeindex in
>    the call list so the tileindex can be left defaulted.
> 
> 3) Changed several methods on the geometry classes to be more specific:
>     lineObj: get -> getPoint
>              add -> addPoint
>              set -> setPoint
>     shapeObj: get -> getLine
>               add -> addLine
> 
> 
> 4) Changed the copy() method on shapeObj to return a new reference 
> instead of
>    updating an existing one in place.
> 
> Does this summarize the proposed changes?  Assuming so, I would like to
> propose some options to allow the update while not generally breaking
> backward compatibility.
> 
> 1) Can we create some sort of stubs under the old constructor names that
>    would allow old code to still make the objects the same way they used 
> to?
>    Even to creating a dummy class for each of the old names with only a
>    a constructor that returns a new style object name?  Or conversely, 
> leave
>    the actual class names with the old values, but create mini constructors
>    with the new names to give nice creation semantics even if the objects
>    thereafter go by their old names?
> 
> 2) This is a hard one.  I hate to change this because I presume getshape()
>    is used alot so the change will cause lots of breakage.  But I can see
>    valid names for the new conventions and it isn't obvious what other name
>    could be used that would make sense.  Though unfortunate, perhaps we 
> could
>    call the new generation form getShapeByIndex()?  This leaves us open 
> to a
>    getShapeNext() iterator at some point.
> 
> 3) I can't see any reason we can't just have both sets of the get/add/set
>    methods.
> 
> 4) I think the old copy() semantics sort of suck and I like the new 
> form.  But
>    to avoid conflicts could we call it clone() instead?  The copy() 
> copies a
>    shapes information into another shape.  The clone() makes a whole new 
> clean
>    instance.
> 
> In each of the above cases I would suggest that the MapScript 
> documentation only
> document the new style names and methods.  What do you think?  I would 
> *like*
> this to be resolved before the 4.2 release if possible so we can issue 
> it with
> new style mapscript documentation and that as the default but without 
> breaking
> old MapScript applications.
> 
> Best regards,

-- 
  -----------------------------------------------------------------
|Paul Spencer                           pspencer at dmsolutions.ca   |
|-----------------------------------------------------------------|
|Applications & Software Development                              |
|DM Solutions Group Inc                 http://www.dmsolutions.ca/|
  -----------------------------------------------------------------