openlayers/lib/OpenLayers/Protocol.js

   1 /* Copyright (c) 2006-2008 MetaCarta, Inc., published under the Clear BSD
   2  * license.  See http://svn.openlayers.org/trunk/openlayers/license.txt for the
   3  * full text of the license. */
   4
   5 /**
   6  * Class: OpenLayers.Protocol
   7  * Abstract vector layer protocol class.  Not to be instantiated directly.  Use
   8  *     one of the protocol subclasses instead.
   9  */
  10 OpenLayers.Protocol = OpenLayers.Class({
  11
  12     /**
  13      * Property: format
  14      * {<OpenLayers.Format>} The format used by this protocol.
  15      */
  16     format: null,
  17
  18     /**
  19      * Property: options
  20      * {Object} Any options sent to the constructor.
  21      */
  22     options: null,
  23
  24     /**
  25      * Property: autoDestroy
  26      * {Boolean} The creator of the protocol can set autoDestroy to false
  27      *      to fully control when the protocol is destroyed. Defaults to
  28      *      true.
  29      */
  30     autoDestroy: true,
  31
  32     /**
  33      * Constructor: OpenLayers.Protocol
  34      * Abstract class for vector protocols.  Create instances of a subclass.
  35      *
  36      * Parameters:
  37      * options - {Object} Optional object whose properties will be set on the
  38      *     instance.
  39      */
  40     initialize: function(options) {
  41         options = options || {};
  42         OpenLayers.Util.extend(this, options);
  43         this.options = options;
  44     },
  45
  46     /**
  47      * APIMethod: destroy
  48      * Clean up the protocol.
  49      */
  50     destroy: function() {
  51         this.options = null;
  52         this.format = null;
  53     },
  54
  55     /**
  56      * APIMethod: read
  57      * Construct a request for reading new features.
  58      *
  59      * Parameters:
  60      * options - {Object} Optional object for configuring the request.
  61      *
  62      * Returns:
  63      * {<OpenLayers.Protocol.Response>} An <OpenLayers.Protocol.Response>
  64      * object, the same object will be passed to the callback function passed
  65      * if one exists in the options object.
  66      */
  67     read: function() {
  68     },
  69
  70
  71     /**
  72      * APIMethod: create
  73      * Construct a request for writing newly created features.
  74      *
  75      * Parameters:
  76      * features - {Array({<OpenLayers.Feature.Vector>})} or
  77      *            {<OpenLayers.Feature.Vector>}
  78      * options - {Object} Optional object for configuring the request.
  79      *
  80      * Returns:
  81      * {<OpenLayers.Protocol.Response>} An <OpenLayers.Protocol.Response>
  82      * object, the same object will be passed to the callback function passed
  83      * if one exists in the options object.
  84      */
  85     create: function() {
  86     },
  87
  88     /**
  89      * APIMethod: update
  90      * Construct a request updating modified features.
  91      *
  92      * Parameters:
  93      * features - {Array({<OpenLayers.Feature.Vector>})} or
  94      *            {<OpenLayers.Feature.Vector>}
  95      * options - {Object} Optional object for configuring the request.
  96      *
  97      * Returns:
  98      * {<OpenLayers.Protocol.Response>} An <OpenLayers.Protocol.Response>
  99      * object, the same object will be passed to the callback function passed
 100      * if one exists in the options object.
 101      */
 102     update: function() {
 103     },
 104
 105     /**
 106      * APIMethod: delete
 107      * Construct a request deleting a removed feature.
 108      *
 109      * Parameters:
 110      * feature - {<OpenLayers.Feature.Vector>}
 111      * options - {Object} Optional object for configuring the request.
 112      *
 113      * Returns:
 114      * {<OpenLayers.Protocol.Response>} An <OpenLayers.Protocol.Response>
 115      * object, the same object will be passed to the callback function passed
 116      * if one exists in the options object.
 117      */
 118     "delete": function() {
 119     },
 120
 121     /**
 122      * APIMethod: commit
 123      * Go over the features and for each take action
 124      * based on the feature state. Possible actions are create,
 125      * update and delete.
 126      *
 127      * Parameters:
 128      * features - {Array({<OpenLayers.Feature.Vector>})}
 129      * options - {Object} Object whose possible keys are "create", "update",
 130      *      "delete", "callback" and "scope", the values referenced by the
 131      *      first three are objects as passed to the "create", "update", and
 132      *      "delete" methods, the value referenced by the "callback" key is
 133      *      a function which is called when the commit operation is complete
 134      *      using the scope referenced by the "scope" key.
 135      *
 136      * Returns:
 137      * {Array({<OpenLayers.Protocol.Response>})} An array of
 138      * <OpenLayers.Protocol.Response> objects.
 139      */
 140     commit: function() {
 141     },
 142
 143     /**
 144      * Method: abort
 145      * Abort an ongoing request.
 146      *
 147      * Parameters:
 148      * response - {<OpenLayers.Protocol.Response>}
 149      */
 150     abort: function(response) {
 151     },
 152
 153     CLASS_NAME: "OpenLayers.Protocol"
 154 });
 155
 156 /**
 157  * Class: OpenLayers.Protocol.Response
 158  * Protocols return Response objects to their users.
 159  */
 160 OpenLayers.Protocol.Response = OpenLayers.Class({
 161     /**
 162      * Property: code
 163      * {Number} - OpenLayers.Protocol.Response.SUCCESS or
 164      *            OpenLayers.Protocol.Response.FAILURE
 165      */
 166     code: null,
 167
 168     /**
 169      * Property: requestType
 170      * {String} The type of request this response corresponds to. Either
 171      *      "create", "read", "update" or "delete".
 172      */
 173     requestType: null,
 174
 175     /**
 176      * Property: last
 177      * {Boolean} - true if this is the last response expected in a commit,
 178      * false otherwise, defaults to true.
 179      */
 180     last: true,
 181
 182     /**
 183      * Property: features
 184      * {Array({<OpenLayers.Feature.Vector>})} or {<OpenLayers.Feature.Vector>}
 185      * The features returned in the response by the server.
 186      */
 187     features: null,
 188
 189     /**
 190      * Property: reqFeatures
 191      * {Array({<OpenLayers.Feature.Vector>})} or {<OpenLayers.Feature.Vector>}
 192      * The features provided by the user and placed in the request by the
 193      *      protocol.
 194      */
 195     reqFeatures: null,
 196
 197     /**
 198      * Property: priv
 199      */
 200     priv: null,
 201
 202     /**
 203      * Constructor: OpenLayers.Protocol.Response
 204      *
 205      * Parameters:
 206      * options - {Object} Optional object whose properties will be set on the
 207      *     instance.
 208      */
 209     initialize: function(options) {
 210         OpenLayers.Util.extend(this, options);
 211     },
 212
 213     /**
 214      * Method: success
 215      *
 216      * Returns:
 217      * {Boolean} - true on success, false otherwise
 218      */
 219     success: function() {
 220         return this.code > 0;
 221     },
 222
 223     CLASS_NAME: "OpenLayers.Protocol.Response"
 224 });
 225
 226 OpenLayers.Protocol.Response.SUCCESS = 1;
 227 OpenLayers.Protocol.Response.FAILURE = 0;