lib/diff_reader.rb

   1 ##
   2 # DiffReader reads OSM diffs and applies them to the database.
   3 #
   4 # Uses the streaming LibXML "Reader" interface to cut down on memory
   5 # usage, so hopefully we can process fairly large diffs.
   6 class DiffReader
   7   include ConsistencyValidations
   8
   9   # maps each element type to the model class which handles it
  10   MODELS = {
  11     "node"     => Node,
  12     "way"      => Way,
  13     "relation" => Relation
  14   }
  15
  16   ##
  17   # Construct a diff reader by giving it a bunch of XML +data+ to parse
  18   # in OsmChange format. All diffs must be limited to a single changeset
  19   # given in +changeset+.
  20   def initialize(data, changeset)
  21     @reader = XML::Reader.string(data)
  22     @changeset = changeset
  23   end
  24
  25   ##
  26   # Reads the next element from the XML document. Checks the return value
  27   # and throws an exception if an error occurred.
  28   def read_or_die
  29     # NOTE: XML::Reader#read returns false for EOF and raises an
  30     # exception if an error occurs.
  31     begin
  32       @reader.read
  33     rescue LibXML::XML::Error => ex
  34       raise OSM::APIBadXMLError.new("changeset", xml, ex.message)
  35     end
  36   end
  37
  38   ##
  39   # An element-block mapping for using the LibXML reader interface.
  40   #
  41   # Since a lot of LibXML reader usage is boilerplate iteration through
  42   # elements, it would be better to DRY and do this in a block. This
  43   # could also help with error handling...?
  44   def with_element
  45     # if the start element is empty then don't do any processing, as
  46     # there won't be any child elements to process!
  47     unless @reader.empty_element?
  48       # read the first element
  49       read_or_die
  50
  51       while @reader.node_type != 15 do # end element
  52         # because we read elements in DOM-style to reuse their DOM
  53         # parsing code, we don't always read an element on each pass
  54         # as the call to @reader.next in the innermost loop will take
  55         # care of that for us.
  56         if @reader.node_type == 1 # element
  57           name = @reader.name
  58           attributes =  {}
  59
  60           if @reader.has_attributes?
  61             while @reader.move_to_next_attribute == 1
  62               attributes[@reader.name] = @reader.value
  63             end
  64
  65             @reader.move_to_element
  66           end
  67
  68           yield name, attributes
  69         else
  70           read_or_die
  71         end
  72       end
  73     end
  74     read_or_die
  75   end
  76
  77   ##
  78   # An element-block mapping for using the LibXML reader interface.
  79   #
  80   # Since a lot of LibXML reader usage is boilerplate iteration through
  81   # elements, it would be better to DRY and do this in a block. This
  82   # could also help with error handling...?
  83   def with_model
  84     with_element do |model_name,model_attributes|
  85       model = MODELS[model_name]
  86       raise OSM::APIBadUserInput.new("Unexpected element type #{model_name}, " +
  87                                      "expected node, way or relation.") if model.nil?
  88       yield model, @reader.expand
  89       @reader.next
  90     end
  91   end
  92
  93   ##
  94   # Checks a few invariants. Others are checked in the model methods
  95   # such as save_ and delete_with_history.
  96   def check(model, xml, new)
  97     raise OSM::APIBadXMLError.new(model, xml) if new.nil?
  98     unless new.changeset_id == @changeset.id
  99       raise OSM::APIChangesetMismatchError.new(new.changeset_id, @changeset.id)
 100     end
 101   end
 102
 103   ##
 104   # Consume the XML diff and try to commit it to the database. This code
 105   # is *not* transactional, so code which calls it should ensure that the
 106   # appropriate transaction block is in place.
 107   #
 108   # On a failure to meet preconditions (e.g: optimistic locking fails)
 109   # an exception subclassing OSM::APIError will be thrown.
 110   def commit
 111
 112     # data structure used for mapping placeholder IDs to real IDs
 113     node_ids, way_ids, rel_ids = {}, {}, {}
 114     ids = { :node => node_ids, :way => way_ids, :relation => rel_ids}
 115
 116     # take the first element and check that it is an osmChange element
 117     @reader.read
 118     raise OSM::APIBadUserInput.new("Document element should be 'osmChange'.") if @reader.name != 'osmChange'
 119
 120     result = OSM::API.new.get_xml_doc
 121     result.root.name = "diffResult"
 122
 123     # loop at the top level, within the <osmChange> element
 124     with_element do |action_name,action_attributes|
 125       if action_name == 'create'
 126         # create a new element. this code is agnostic of the element type
 127         # because all the elements support the methods that we're using.
 128         with_model do |model, xml|
 129           new = model.from_xml_node(xml, true)
 130           check(model, xml, new)
 131
 132           # when this element is saved it will get a new ID, so we save it
 133           # to produce the mapping which is sent to other elements.
 134           placeholder_id = xml['id'].to_i
 135           raise OSM::APIBadXMLError.new(model, xml) if placeholder_id.nil?
 136
 137           # check if the placeholder ID has been given before and throw
 138           # an exception if it has - we can't create the same element twice.
 139           model_sym = model.to_s.downcase.to_sym
 140           raise OSM::APIBadUserInput.new("Placeholder IDs must be unique for created elements.") if ids[model_sym].include? placeholder_id
 141
 142           # some elements may have placeholders for other elements in the
 143           # diff, so we must fix these before saving the element.
 144           new.fix_placeholders!(ids, placeholder_id)
 145
 146           # create element given user
 147           new.create_with_history(@changeset.user)
 148
 149           # save placeholder => allocated ID map
 150           ids[model_sym][placeholder_id] = new.id
 151
 152           # add the result to the document we're building for return.
 153           xml_result = XML::Node.new model.to_s.downcase
 154           xml_result["old_id"] = placeholder_id.to_s
 155           xml_result["new_id"] = new.id.to_s
 156           xml_result["new_version"] = new.version.to_s
 157           result.root << xml_result
 158         end
 159
 160       elsif action_name == 'modify'
 161         # modify an existing element. again, this code doesn't directly deal
 162         # with types, but uses duck typing to handle them transparently.
 163         with_model do |model, xml|
 164           # get the new element from the XML payload
 165           new = model.from_xml_node(xml, false)
 166           check(model, xml, new)
 167
 168           # if the ID is a placeholder then map it to the real ID
 169           model_sym = model.to_s.downcase.to_sym
 170           client_id = new.id
 171           is_placeholder = ids[model_sym].include? client_id
 172           id = is_placeholder ? ids[model_sym][client_id] : client_id
 173
 174           # and the old one from the database
 175           old = model.find(id)
 176
 177           # translate any placeholder IDs to their true IDs.
 178           new.fix_placeholders!(ids)
 179           new.id = id
 180
 181           old.update_from(new, @changeset.user)
 182
 183           xml_result = XML::Node.new model.to_s.downcase
 184           xml_result["old_id"] = client_id.to_s
 185           xml_result["new_id"] = id.to_s
 186           # version is updated in "old" through the update, so we must not
 187           # return new.version here but old.version!
 188           xml_result["new_version"] = old.version.to_s
 189           result.root << xml_result
 190         end
 191
 192       elsif action_name == 'delete'
 193         # delete action. this takes a payload in API 0.6, so we need to do
 194         # most of the same checks that are done for the modify.
 195         with_model do |model, xml|
 196           # delete doesn't have to contain a full payload, according to
 197           # the wiki docs, so we just extract the things we need.
 198           new_id = xml['id'].to_i
 199           raise OSM::APIBadXMLError.new(model, xml, "ID attribute is required") if new_id.nil?
 200
 201           # if the ID is a placeholder then map it to the real ID
 202           model_sym = model.to_s.downcase.to_sym
 203           is_placeholder = ids[model_sym].include? new_id
 204           id = is_placeholder ? ids[model_sym][new_id] : new_id
 205
 206           # build the "new" element by modifying the existing one
 207           new = model.find(id)
 208           new.changeset_id = xml['changeset'].to_i
 209           new.version = xml['version'].to_i
 210           check(model, xml, new)
 211
 212           # fetch the matching old element from the DB
 213           old = model.find(id)
 214
 215           # can a delete have placeholders under any circumstances?
 216           # if a way is modified, then deleted is that a valid diff?
 217           new.fix_placeholders!(ids)
 218
 219           xml_result = XML::Node.new model.to_s.downcase
 220           # oh, the irony... the "new" element actually contains the "old" ID
 221           # a better name would have been client/server, but anyway...
 222           xml_result["old_id"] = new_id.to_s
 223
 224           if action_attributes["if-unused"]
 225             begin
 226               old.delete_with_history!(new, @changeset.user)
 227             rescue OSM::APIPreconditionFailedError => ex
 228               xml_result["new_id"] = old.id.to_s
 229               xml_result["new_version"] = old.version.to_s
 230             end
 231           else
 232             old.delete_with_history!(new, @changeset.user)
 233           end
 234
 235           result.root << xml_result
 236         end
 237
 238       else
 239         # no other actions to choose from, so it must be the users fault!
 240         raise OSM::APIChangesetActionInvalid.new(action_name)
 241       end
 242     end
 243
 244     # return the XML document to be rendered back to the client
 245     return result
 246   end
 247
 248 end