openlayers/lib/OpenLayers/Format.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  * @requires OpenLayers/Util.js
   7  * @requires OpenLayers/Console.js
   8  */
   9
  10 /**
  11  * Class: OpenLayers.Format
  12  * Base class for format reading/writing a variety of formats.  Subclasses
  13  *     of OpenLayers.Format are expected to have read and write methods.
  14  */
  15 OpenLayers.Format = OpenLayers.Class({
  16
  17     /**
  18      * Property: options
  19      * {Object} A reference to options passed to the constructor.
  20      */
  21     options: null,
  22
  23     /**
  24      * APIProperty: externalProjection
  25      * {<OpenLayers.Projection>} When passed a externalProjection and
  26      *     internalProjection, the format will reproject the geometries it
  27      *     reads or writes. The externalProjection is the projection used by
  28      *     the content which is passed into read or which comes out of write.
  29      *     In order to reproject, a projection transformation function for the
  30      *     specified projections must be available. This support may be
  31      *     provided via proj4js or via a custom transformation function. See
  32      *     {<OpenLayers.Projection.addTransform>} for more information on
  33      *     custom transformations.
  34      */
  35     externalProjection: null,
  36
  37     /**
  38      * APIProperty: internalProjection
  39      * {<OpenLayers.Projection>} When passed a externalProjection and
  40      *     internalProjection, the format will reproject the geometries it
  41      *     reads or writes. The internalProjection is the projection used by
  42      *     the geometries which are returned by read or which are passed into
  43      *     write.  In order to reproject, a projection transformation function
  44      *     for the specified projections must be available. This support may be
  45      *     provided via proj4js or via a custom transformation function. See
  46      *     {<OpenLayers.Projection.addTransform>} for more information on
  47      *     custom transformations.
  48      */
  49     internalProjection: null,
  50
  51     /**
  52      * APIProperty: data
  53      * {Object} When <keepData> is true, this is the parsed string sent to
  54      *     <read>.
  55      */
  56     data: null,
  57
  58     /**
  59      * APIProperty: keepData
  60      * {Object} Maintain a reference (<data>) to the most recently read data.
  61      *     Default is false.
  62      */
  63     keepData: false,
  64
  65     /**
  66      * Constructor: OpenLayers.Format
  67      * Instances of this class are not useful.  See one of the subclasses.
  68      *
  69      * Parameters:
  70      * options - {Object} An optional object with properties to set on the
  71      *           format
  72      *
  73      * Valid options:
  74      * keepData - {Boolean} If true, upon <read>, the data property will be
  75      *     set to the parsed object (e.g. the json or xml object).
  76      *
  77      * Returns:
  78      * An instance of OpenLayers.Format
  79      */
  80     initialize: function(options) {
  81         OpenLayers.Util.extend(this, options);
  82         this.options = options;
  83     },
  84
  85     /**
  86      * APIMethod: destroy
  87      * Clean up.
  88      */
  89     destroy: function() {
  90     },
  91
  92     /**
  93      * Method: read
  94      * Read data from a string, and return an object whose type depends on the
  95      * subclass.
  96      *
  97      * Parameters:
  98      * data - {string} Data to read/parse.
  99      *
 100      * Returns:
 101      * Depends on the subclass
 102      */
 103     read: function(data) {
 104         OpenLayers.Console.userError(OpenLayers.i18n("readNotImplemented"));
 105     },
 106
 107     /**
 108      * Method: write
 109      * Accept an object, and return a string.
 110      *
 111      * Parameters:
 112      * object - {Object} Object to be serialized
 113      *
 114      * Returns:
 115      * {String} A string representation of the object.
 116      */
 117     write: function(object) {
 118         OpenLayers.Console.userError(OpenLayers.i18n("writeNotImplemented"));
 119     },
 120
 121     CLASS_NAME: "OpenLayers.Format"
 122 });