Updated docs and fixed names/params on a few methods

csrc/class_map.cpp

@@ -665,10 +665,10 @@ JNIEXPORT void JNICALL Java_mapnik_MapDefinition_setBackgroundImage
 
 /*
  * Class:     mapnik_MapDefinition
- * Method:    saveMapToFile
+ * Method:    saveMap
  * Signature: (Ljava/lang/String;Z)V
  */
-JNIEXPORT void JNICALL Java_mapnik_MapDefinition_saveMapToFile
+JNIEXPORT void JNICALL Java_mapnik_MapDefinition_saveMap
   (JNIEnv *env, jobject mapobject, jstring filenamej, jboolean explicitDefaults)
 {
 	PREAMBLE;
@@ -686,8 +686,15 @@ JNIEXPORT void JNICALL Java_mapnik_MapDefinition_saveMapToFile
 
 /*
  * Class:     mapnik_MapDefinition
- * Method:    saveMapToBuffer
- * Signature: (Z)[B
+ * Method:    saveMapToString
+ * Signature: (Z)Ljava/lang/String;
  */
-JNIEXPORT jbyteArray JNICALL Java_mapnik_MapDefinition_saveMapToBuffer
-  (JNIEnv *, jobject, jboolean);
+JNIEXPORT jstring JNICALL Java_mapnik_MapDefinition_saveMapToString
+  (JNIEnv *env, jobject mapobject, jboolean explicit_defaults)
+{
+	PREAMBLE;
+	mapnik::Map* map=LOAD_MAP_POINTER(mapobject);
+	std::string s=mapnik::save_map_to_string(*map, explicit_defaults);
+	return env->NewStringUTF(s.c_str());
+	TRAILER(0);
+}

csrc/class_renderer.cpp

@@ -1,21 +1,21 @@
 /*
  * Class:     mapnik_Renderer
  * Method:    renderAgg
- * Signature: (Lmapnik/Map;Lmapnik/Image;)V
+ * Signature: (Lmapnik/MapDefinition;Lmapnik/Image;DII)V
  */
 JNIEXPORT void JNICALL Java_mapnik_Renderer_renderAgg
-  (JNIEnv *env, jclass c, jobject mapobj, jobject imobj)
+  (JNIEnv *env, jclass c, jobject mapobj, jobject imobj, jdouble scale_factor, jint offset_x, jint offset_y)
 {
 	PREAMBLE;
-	if (!mapobj || !imobj) {
+	if (!mapobj || !imobj || offset_x<0 || offset_y<0) {
 		throw_runtime_exception(env, "Illegal arguments in call");
 		return;
 	}
 
 	mapnik::Map* map=LOAD_MAP_POINTER(mapobj);
 	mapnik::image_32* im=LOAD_IMAGE_POINTER(imobj);
 
-	mapnik::agg_renderer<mapnik::image_32> ren(*map, *im);
+	mapnik::agg_renderer<mapnik::image_32> ren(*map, *im, scale_factor, offset_x, offset_y);
 	ren.apply();
 
 	TRAILER_VOID;

src/mapnik/Datasource.java

@@ -1,5 +1,12 @@
 package mapnik;
 
+/**
+ * Wraps a mapnik::datasource object.  Datasources should be created
+ * by passing parameters to DatasourceCache.
+ * 
+ * @author stella
+ *
+ */
 public class Datasource extends NativeObject {
 	// Native pointer: boost::shared_ptr<mapnik::datasource>
 
@@ -13,7 +20,9 @@ private Datasource() {
 	public native int getType();
 	public native void bind();
 	public native Box2d getEnvelope();
+
 	public native FeatureSet features(Query q);
 	public native FeatureSet featuresAtPoint(Coord pt);
+
 	public native LayerDescriptor getDescriptor();
 }

src/mapnik/DatasourceCache.java

@@ -1,5 +1,12 @@
 package mapnik;
 
+/**
+ * Manage the registry of datasources.  To create a Datasource, use the create(...)
+ * method.
+ * 
+ * @author stella
+ *
+ */
 public class DatasourceCache {
 	public static native String[] pluginNames();
 	public static native String pluginDirectories();

src/mapnik/FeatureSet.java

@@ -5,6 +5,11 @@
 /**
  * Wraps a mapnik::featureset_ptr and the current mapnik::feature into a
  * java.sql.ResultSet type interface.
+ * <p>
+ * Note that geometries referenced off of the current feature will become
+ * invalid once the FeatureSet moves to the next feature or the FeatureSet
+ * is disposed.
+ * 
  * @author stella
  *
  */
@@ -22,6 +27,7 @@ public class FeatureSet extends NativeObject {
 	private Geometry[] feature_geometries;
 
 	void dealloc(long ptr) {
+		disposeGeometries();
 		long localFeaturePtr=feature_ptr;
 		feature_ptr=0;
 		dealloc(ptr, localFeaturePtr);
@@ -31,19 +37,23 @@ void dealloc(long ptr) {
 	private native boolean _next();
 	private native Geometry[] _loadGeometries();
 
+	private void disposeGeometries() {
+		if (feature_geometries!=null) {
+			for (int i=0; i<feature_geometries.length; i++) {
+				feature_geometries[i].dispose();
+			}
+			feature_geometries=null;
+		}
+	}
+
 	// -- FeatureSet methods
 	/**
 	 * Moves to the next feature in the set.  Returns true if exists.
 	 * Initially positioned before the first.
 	 */
 	public boolean next() {
 		// First release the geometries
-		if (feature_geometries!=null) {
-			for (int i=0; i<feature_geometries.length; i++) {
-				feature_geometries[i].dispose();
-			}
-			feature_geometries=null;
-		}
+		disposeGeometries();
 		return _next();
 	}
 

src/mapnik/FeatureTypeStyle.java

@@ -3,8 +3,8 @@
 import java.util.Set;
 
 /**
- * Mirrors the feature_type_style in mapnik c++
- *
+ * Wraps the mapnik::feature_type_style value type.
+ * 
  * @author stella
  *
  */
@@ -15,6 +15,7 @@ public class FeatureTypeStyle extends NativeObject {
 	public FeatureTypeStyle() {
 		ptr=alloc();
 	}
+
 	/**
 	 * Collect all attribute names referenced in rules
 	 * @return Set of attributes

src/mapnik/Geometry.java

@@ -1,5 +1,12 @@
 package mapnik;
 
+/**
+ * A mapnik::geometry_type instance.  These instances are always owned
+ * by the corresponding feature.
+ * 
+ * @author stella
+ *
+ */
 public class Geometry extends NativeObject {
 	// mapnik::geometry_type*
 

src/mapnik/Layer.java

@@ -1,6 +1,13 @@
 package mapnik;
 
 
+/**
+ * Wraps the mapnik::Layer value type.  When a Layer is read from or
+ * written to the map, it is copied.
+ * 
+ * @author stella
+ *
+ */
 public class Layer extends NativeObject {
 	private static native long alloc(String name, String srs);
 	native void dealloc(long ptr);

src/mapnik/MapDefinition.java

@@ -3,7 +3,26 @@
 import java.util.Collection;
 
 /**
- * Wrapper around the Mapnik map object and friends
+ * Wrapper around the mapnik::Map object.
+ * <p>
+ * Several methods that are found elsewhere in the C++ code but operate exlusively
+ * on maps are located directly on this class:
+ * <ul>
+ * <li>loadMap
+ * <li>loadMapString
+ * <li>saveMap
+ * <li>saveMapToString
+ * </ul>
+ * <p>
+ * Not all child objects are implemented.
+ * <p>
+ * Note that the following child objects are value types.  When they are added to or
+ * read from a MapDefinition, the caller will be left with a copy.
+ * <ul>
+ * <li>Layer
+ * <li>FeatureTypeStyle
+ * </ul>
+ * 
  * @author stella
  *
  */
@@ -81,12 +100,12 @@ public MapDefinition(MapDefinition other) {
 	public native void setBackgroundImage(String filename);
 
 	// Save map
-	public native void saveMapToFile(String fileName, boolean explicitDefaults);
-	public native byte[] saveMapToBuffer(boolean explicitDefaults);
-	public void saveMapToFile(String fileName) {
-		saveMapToFile(fileName, false);
+	public native void saveMap(String fileName, boolean explicitDefaults);
+	public native String saveMapToString(boolean explicitDefaults);
+	public void saveMap(String fileName) {
+		saveMap(fileName, false);
 	}
-	public byte[] saveMapToBuffer() {
-		return saveMapToBuffer(false);
+	public String saveMapToString() {
+		return saveMapToString(false);
 	}
 }

src/mapnik/Renderer.java

@@ -12,5 +12,14 @@ public class Renderer {
 	 * @param map
 	 * @param image
 	 */
-	public static native void renderAgg(MapDefinition map, Image image);
+	public static native void renderAgg(MapDefinition map, Image image, double scaleFactor, int offsetX, int offsetY);
+
+	/**
+	 * Render the given map to the given image with scaleFactor=1.0, offsetX=0, and offsetY=0
+	 * @param map
+	 * @param image
+	 */
+	public static void renderAgg(MapDefinition map, Image image) {
+		renderAgg(map, image, 1.0, 0, 0);
+	}
 }