bring changes to protocol base class, r=fredj (closes #1677)

git-svn-id: http://svn.openlayers.org/trunk/openlayers@7883 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf

lib/OpenLayers/Protocol.js

@@ -38,6 +38,7 @@ OpenLayers.Protocol = OpenLayers.Class({
      *     instance.
      */
     initialize: function(options) {
+        options = options || {};
         OpenLayers.Util.extend(this, options);
         this.options = options;
     },
@@ -57,6 +58,11 @@ OpenLayers.Protocol = OpenLayers.Class({
      *
      * Parameters:
      * options - {Object} Optional object for configuring the request.
+     *
+     * Returns:
+     * {<OpenLayers.Protocol.Response>} An <OpenLayers.Protocol.Response>
+     * object, the same object will be passed to the callback function passed
+     * if one exists in the options object.
      */
     read: function() {
     },
@@ -70,6 +76,11 @@ OpenLayers.Protocol = OpenLayers.Class({
      * features - {Array({<OpenLayers.Feature.Vector>})} or
      *            {<OpenLayers.Feature.Vector>}
      * options - {Object} Optional object for configuring the request.
+     *
+     * Returns:
+     * {<OpenLayers.Protocol.Response>} An <OpenLayers.Protocol.Response>
+     * object, the same object will be passed to the callback function passed
+     * if one exists in the options object.
      */
     create: function() {
     },
@@ -82,6 +93,11 @@ OpenLayers.Protocol = OpenLayers.Class({
      * features - {Array({<OpenLayers.Feature.Vector>})} or
      *            {<OpenLayers.Feature.Vector>}
      * options - {Object} Optional object for configuring the request.
+     *
+     * Returns:
+     * {<OpenLayers.Protocol.Response>} An <OpenLayers.Protocol.Response>
+     * object, the same object will be passed to the callback function passed
+     * if one exists in the options object.
      */
     update: function() {
     },
@@ -93,6 +109,11 @@ OpenLayers.Protocol = OpenLayers.Class({
      * Parameters:
      * feature - {<OpenLayers.Feature.Vector>}
      * options - {Object} Optional object for configuring the request.
+     *
+     * Returns:
+     * {<OpenLayers.Protocol.Response>} An <OpenLayers.Protocol.Response>
+     * object, the same object will be passed to the callback function passed
+     * if one exists in the options object.
      */
     "delete": function() {
     },
@@ -105,8 +126,16 @@ OpenLayers.Protocol = OpenLayers.Class({
      *
      * Parameters:
      * features - {Array({<OpenLayers.Feature.Vector>})}
-     * options - {Object} Map of options, the keys of the map are
+     * options - {Object} Object whose possible keys are "create", "update",
-     *           'create', 'update', and 'delete'
+     *      "delete", "callback" and "scope", the values referenced by the
+     *      first three are objects as passed to the "create", "update", and
+     *      "delete" methods, the value referenced by the "callback" key is
+     *      a function which is called when the commit operation is complete
+     *      using the scope referenced by the "scope" key.
+     *
+     * Returns:
+     * {Array({<OpenLayers.Protocol.Response>})} An array of
+     * <OpenLayers.Protocol.Response> objects.
      */
     commit: function() {
     },
@@ -118,14 +147,28 @@ OpenLayers.Protocol = OpenLayers.Class({
  * Class: OpenLayers.Protocol.Response
  * Protocols return Response objects to their users.
  */
-OpenLayers.Protocol.Response = new OpenLayers.Class({
+OpenLayers.Protocol.Response = OpenLayers.Class({
     /**
      * Property: code
-     * {Integer} - OpenLayers.Protocol.Response.SUCCESS or
+     * {Number} - OpenLayers.Protocol.Response.SUCCESS or
-     *             OpenLayers.Protocol.Response.FAILURE
+     *            OpenLayers.Protocol.Response.FAILURE
      */
     code: null,
 
+    /**
+     * Property: requestType
+     * {String} The type of request this response corresponds to. Either
+     *      "create", "read", "update" or "delete".
+     */
+    requestType: null,
+
+    /**
+     * Property: last
+     * {Boolean} - true if this is the last response expected in a commit,
+     * false otherwise, defaults to true.
+     */
+    last: true,
+
     /**
      * Property: features
      * {Array({<OpenLayers.Feature.Vector>})} or {<OpenLayers.Feature.Vector>}
@@ -164,14 +207,11 @@ OpenLayers.Protocol.Response = new OpenLayers.Class({
      * {Boolean} - true on success, false otherwise
      */
     success: function() {
-        return !!(this.code & OpenLayers.Protocol.Response.SUCCESS_MASK);
+        return this.code > 0;
     },
 
     CLASS_NAME: "OpenLayers.Protocol.Response"
 });
 
-OpenLayers.Protocol.Response.SUCCESS_MASK    = 0x000000ff;
+OpenLayers.Protocol.Response.SUCCESS = 1;
-OpenLayers.Protocol.Response.SUCCESS         = 0x00000001;
+OpenLayers.Protocol.Response.FAILURE = 0;
-
-OpenLayers.Protocol.Response.FAILURE_MASK    = 0x0000ff00;
-OpenLayers.Protocol.Response.FAILURE         = 0x00000100;