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