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