Changes between Version 1 and Version 2 of rfc29_desired_fields


Ignore:
Timestamp:
Jul 29, 2010, 1:22:18 AM (14 years ago)
Author:
wonder
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • rfc29_desired_fields

    v1 v2  
    1 = RFC 29: OGR Set Desired Fields =
     1= RFC 29: OGR Set Ignored Fields =
    22
    33Author: Martin Dobias[[BR]]
    … …  
    77== Summary ==
    88
    9 To improve performance when fetching features, this RFC proposes a way how to tell OGR which fields are going to be required in subsequent GetFeature() / GetNextFeature() calls. Knowing the necessary fields, the OGR driver can decide to leave the rest of the fields null.
     9To improve performance when fetching features, this RFC proposes a way how to tell OGR which fields are going to be required in subsequent GetFeature() / GetNextFeature() calls. Knowing the necessary fields, the OGR driver can decide to leave the rest of the fields null. 
    1010
    1111== Details ==
    1212
    13 A new (non-virtual) function should be added to OGRLayer class to allow the client to set which fields will be fetched:
     13A new function will be added to OGRLayer class to allow the client to set which fields will *not* be fetched:
    1414
    1515{{{
    16 void SetDesiredFields(int nNumFields, int* pabFields);
     16virtual OGRErr OGRLayer::SetIgnoredFields( const char **papszFields );
    1717}}}
    1818
    … …  
    2020
    2121{{{
    22 void CPL_DLL OGR_L_SetDesiredFields( OGRLayerH, int, int* );
     22OGRErr CPL_DLL OGR_L_SetIgnoredFields( OGRLayerH, const char **papszFields );
    2323}}}
    2424
    25 The parameter "pabFields" is an array of booleans, each item specifies whether the field with the same index should be fetched. The length of the array is specified in "nNumFields" parameter and typically it should be the same as the actual number of fields. The SetDesiredFields() function makes a copy of both nNumFields and pabFields (these have to be stored as class member variables of OGRLayer: nDesiredNumFields, pabDesiredFields).
    2625
    27 The parameter "nNumFields" is a bit redundant, but it keeps things safe in case some fields are later added so that there is not access beyond the allocated memory of the array.
     26The argument is a list of fields to be ignored, by name, and the special field names "OGR_GEOMETRY" and "OGR_STYLE" will
     27be interpreted to refer to the geometry and style values of a feature.
    2828
    29 The semantics is as follows: if nNumFields < 0, all fields will be fetched. Otherwise the pabFields array will be copied to an internal one within OGRLayer and only the fields having non-zero value in that array will be fetched.
     29Passing by field name has been chosen so that we could handle OGR_GEOMETRY, OGR_STYLE and possibly some other special
     30fields in the future.  Instead of specifying "desired" fields, it has been decided to specify "ignored" fields
     31so that we wouldn't accidentally drop things like geometry and style just because they weren't explicitly
     32listed in a desired list.
    3033
    31 The implementation of fetching in drivers will usually require only small adjustment, e.g.:
     34Passing NULL for papszFields will clear the ignored list.
     35
     36The method will return OGRERR_NONE as long as all the field names are able to be resolved, even if the method does not
     37support selection of fields.
     38
     39The method will be implemented at the level of OGRLayer class: it will resolve indexes of the fields and set the following new member variables which indicate what should be ignored:
     40{{{m_pabIgnoredFields}}}, {{{m_bIgnoreGeometry}}}, {{{m_bIgnoreStyle}}}.
     41
     42Optionally the method can be overridden in driver implementation if the driver has some special needs.
     43
     44== Implementation in drivers ==
     45
     46The implementation of drivers will require small adjustments in order to support this RFC. Drivers not making use of this addition will simply continue to fetch also fields/geometry/style that are not requested by the caller.
     47
     48The adjustments in driver implementation will look as follows:
    3249
    3350{{{
     51if (!m_bIgnoreGeometry)
     52{
     53  // fetch geometry
     54}
     55if (!m_bIgnoreStyle)
     56{
     57  // fetch style
     58}
     59
    3460for( int iField = 0; iField < poDefn->GetFieldCount(); iField++ )
    3561{
    36   if (nDesiredNumFields >= 0 && iField < nDesiredNumFields && !pabDesiredFields[iField])
     62  if (m_pabIgnoredFields && iField < m_nIgnoredFieldCount && m_pabIgnoredFields[iField])
    3763    continue;
    3864
    … …  
    4167}}}
    4268
     69
    4370== Compatibility ==
    4471
    45 This change is fully backwards compatible: OGR will continue to fetch all fields by default. Only applications using the proposed new API will experience new behavior.
     72This change is fully backwards compatible: OGR will continue to fetch geometry, style and all fields by default. Only applications using the proposed API will experience the new behavior.
    4673
    47 There is no need to modify all existing drivers. Drivers that do not consider the desired fields will still fetch all attributes as before.
     74Initially, only some drivers (Shapefile and few others) will implement this RFC. There is no need to modify all existing drivers when adopting the RFC - drivers that do not consider the ignored fields will simply fetch all attributes as before.
    4875
     76ogr2ogr command line tool will make use of this RFC in cases it receives -select argument with a list of required fields. Other than the specified fields will be ignored.