Rationalise API error classes by getting of the render_opts method which
[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   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           yield @reader.name
58         else
59           read_or_die
60         end
61       end 
62     end
63     read_or_die
64   end
65
66   ##
67   # An element-block mapping for using the LibXML reader interface. 
68   #
69   # Since a lot of LibXML reader usage is boilerplate iteration through
70   # elements, it would be better to DRY and do this in a block. This
71   # could also help with error handling...?
72   def with_model
73     with_element do |model_name|
74       model = MODELS[model_name]
75       raise OSM::APIBadUserInput.new("Unexpected element type #{model_name}, " +
76                                      "expected node, way or relation.") if model.nil?
77       yield model, @reader.expand
78       @reader.next
79     end
80   end
81
82   ##
83   # Checks a few invariants. Others are checked in the model methods
84   # such as save_ and delete_with_history.
85   def check(model, xml, new)
86     raise OSM::APIBadXMLError.new(model, xml) if new.nil?
87     unless new.changeset_id == @changeset.id 
88       raise OSM::APIChangesetMismatchError.new(new.changeset_id, @changeset.id)
89     end
90   end
91
92   ##
93   # Consume the XML diff and try to commit it to the database. This code
94   # is *not* transactional, so code which calls it should ensure that the
95   # appropriate transaction block is in place.
96   #
97   # On a failure to meet preconditions (e.g: optimistic locking fails) 
98   # an exception subclassing OSM::APIError will be thrown.
99   def commit
100
101     # data structure used for mapping placeholder IDs to real IDs
102     node_ids, way_ids, rel_ids = {}, {}, {}
103     ids = { :node => node_ids, :way => way_ids, :relation => rel_ids}
104
105     # take the first element and check that it is an osmChange element
106     @reader.read
107     raise APIBadUserInput.new("Document element should be 'osmChange'.") if @reader.name != 'osmChange'
108
109     result = OSM::API.new.get_xml_doc
110     result.root.name = "diffResult"
111
112     # loop at the top level, within the <osmChange> element
113     with_element do |action_name|
114       if action_name == 'create'
115         # create a new element. this code is agnostic of the element type
116         # because all the elements support the methods that we're using.
117         with_model do |model, xml|
118           new = model.from_xml_node(xml, true)
119           check(model, xml, new)
120
121           # when this element is saved it will get a new ID, so we save it
122           # to produce the mapping which is sent to other elements.
123           placeholder_id = xml['id'].to_i
124           raise OSM::APIBadXMLError.new(model, xml) if placeholder_id.nil?
125
126           # check if the placeholder ID has been given before and throw
127           # an exception if it has - we can't create the same element twice.
128           model_sym = model.to_s.downcase.to_sym
129           raise OSM::APIBadUserInput.new("Placeholder IDs must be unique for created elements.") if ids[model_sym].include? placeholder_id
130
131           # some elements may have placeholders for other elements in the
132           # diff, so we must fix these before saving the element.
133           new.fix_placeholders!(ids, placeholder_id)
134
135           # create element given user
136           new.create_with_history(@changeset.user)
137           
138           # save placeholder => allocated ID map
139           ids[model_sym][placeholder_id] = new.id
140
141           # add the result to the document we're building for return.
142           xml_result = XML::Node.new model.to_s.downcase
143           xml_result["old_id"] = placeholder_id.to_s
144           xml_result["new_id"] = new.id.to_s
145           xml_result["new_version"] = new.version.to_s
146           result.root << xml_result
147         end
148         
149       elsif action_name == 'modify'
150         # modify an existing element. again, this code doesn't directly deal
151         # with types, but uses duck typing to handle them transparently.
152         with_model do |model, xml|
153           # get the new element from the XML payload
154           new = model.from_xml_node(xml, false)
155           check(model, xml, new)
156
157           # if the ID is a placeholder then map it to the real ID
158           model_sym = model.to_s.downcase.to_sym
159           client_id = new.id
160           is_placeholder = ids[model_sym].include? client_id
161           id = is_placeholder ? ids[model_sym][client_id] : client_id
162
163           # and the old one from the database
164           old = model.find(id)
165
166           # translate any placeholder IDs to their true IDs.
167           new.fix_placeholders!(ids)
168           new.id = id
169
170           old.update_from(new, @changeset.user)
171
172           xml_result = XML::Node.new model.to_s.downcase
173           xml_result["old_id"] = client_id.to_s
174           xml_result["new_id"] = id.to_s 
175           # version is updated in "old" through the update, so we must not
176           # return new.version here but old.version!
177           xml_result["new_version"] = old.version.to_s
178           result.root << xml_result
179         end
180
181       elsif action_name == 'delete'
182         # delete action. this takes a payload in API 0.6, so we need to do
183         # most of the same checks that are done for the modify.
184         with_model do |model, xml|
185           # delete doesn't have to contain a full payload, according to
186           # the wiki docs, so we just extract the things we need.
187           new_id = xml['id'].to_i
188           raise API::APIBadXMLError.new(model, xml, "ID attribute is required") if new_id.nil?
189
190           # if the ID is a placeholder then map it to the real ID
191           model_sym = model.to_s.downcase.to_sym
192           is_placeholder = ids[model_sym].include? new_id
193           id = is_placeholder ? ids[model_sym][new_id] : new_id
194
195           # build the "new" element by modifying the existing one
196           new = model.find(id)
197           new.changeset_id = xml['changeset'].to_i
198           new.version = xml['version'].to_i
199           check(model, xml, new)
200
201           # fetch the matching old element from the DB
202           old = model.find(id)
203
204           # can a delete have placeholders under any circumstances?
205           # if a way is modified, then deleted is that a valid diff?
206           new.fix_placeholders!(ids)
207           old.delete_with_history!(new, @changeset.user)
208
209           xml_result = XML::Node.new model.to_s.downcase
210           # oh, the irony... the "new" element actually contains the "old" ID
211           # a better name would have been client/server, but anyway...
212           xml_result["old_id"] = new_id.to_s
213           result.root << xml_result
214         end
215
216       else
217         # no other actions to choose from, so it must be the users fault!
218         raise OSM::APIChangesetActionInvalid.new(action_name)
219       end
220     end
221
222     # return the XML document to be rendered back to the client
223     return result
224   end
225
226 end