3 * ====================================================================
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
20 * ====================================================================
24 * @brief Tree editing functions and structures
30 #include <apr_pools.h>
32 #include "svn_types.h"
33 #include "svn_error.h"
34 #include "svn_io.h" /* for svn_stream_t */
35 #include "svn_delta.h"
39 #endif /* __cplusplus */
42 /*** Temporarily private stuff (should move to svn_delta.h when Editor
43 V2 is made public) ***/
45 /** Callback to retrieve a node's entire set of properties. This is
46 * needed by the various editor shims in order to effect backwards
49 * Implementations should set @a *props to the hash of properties
50 * associated with @a path in @a base_revision, allocating that hash
51 * and its contents in @a result_pool, and should use @a scratch_pool
52 * for temporary allocations.
54 * @a baton is an implementation-specific closure.
56 typedef svn_error_t *(*svn_delta_fetch_props_func_t)(
60 svn_revnum_t base_revision,
61 apr_pool_t *result_pool,
62 apr_pool_t *scratch_pool
65 /** Callback to retrieve a node's kind. This is needed by the various
66 * editor shims in order to effect backwards compatibility.
68 * Implementations should set @a *kind to the node kind of @a path in
69 * @a base_revision, using @a scratch_pool for temporary allocations.
71 * @a baton is an implementation-specific closure.
73 typedef svn_error_t *(*svn_delta_fetch_kind_func_t)(
74 svn_node_kind_t *kind,
77 svn_revnum_t base_revision,
78 apr_pool_t *scratch_pool
81 /** Callback to fetch the name of a file to use as a delta base.
83 * Implementations should set @a *filename to the name of a file
84 * suitable for use as a delta base for @a path in @a base_revision
85 * (allocating @a *filename from @a result_pool), or to @c NULL if the
86 * base stream is empty. @a scratch_pool is provided for temporary
89 * @a baton is an implementation-specific closure.
91 typedef svn_error_t *(*svn_delta_fetch_base_func_t)(
92 const char **filename,
95 svn_revnum_t base_revision,
96 apr_pool_t *result_pool,
97 apr_pool_t *scratch_pool
100 /** Collection of callbacks used for the shim code. This structure
101 * may grow additional fields in the future. Therefore, always use
102 * svn_delta_shim_callbacks_default() to allocate new instances of it.
104 typedef struct svn_delta_shim_callbacks_t
106 svn_delta_fetch_props_func_t fetch_props_func;
107 svn_delta_fetch_kind_func_t fetch_kind_func;
108 svn_delta_fetch_base_func_t fetch_base_func;
110 } svn_delta_shim_callbacks_t;
112 /** Return a collection of default shim functions in @a result_pool.
114 svn_delta_shim_callbacks_t *
115 svn_delta_shim_callbacks_default(apr_pool_t *result_pool);
119 /** Transforming trees ("editing").
121 * In Subversion, we have a number of occasions where we transform a tree
122 * from one state into another. This process is called "editing" a tree.
124 * In processing a `commit' command:
125 * - The client examines its working copy data to determine the set of
126 * changes necessary to transform its base tree into the desired target.
127 * - The client networking library delivers that set of changes/operations
128 * across the wire as an equivalent series of network requests (for
129 * example, to svnserve as an ra_svn protocol stream, or to an
130 * Apache httpd server as WebDAV commands)
131 * - The server receives those requests and applies the sequence of
132 * operations on a revision, producing a transaction representing the
134 * - The Subversion server then commits the transaction to the filesystem.
136 * In processing an `update' command, the process is reversed:
137 * - The Subversion server module talks to the filesystem and computes a
138 * set of changes necessary to bring the client's working copy up to date.
139 * - The server serializes this description of changes, and delivers it to
141 * - The client networking library receives that reply, producing a set
142 * of changes/operations to alter the working copy into the revision
143 * requested by the update command.
144 * - The working copy library applies those operations to the working copy
145 * to align it with the requested update target.
147 * The series of changes (or operations) necessary to transform a tree from
148 * one state into another is passed between subsystems using this "editor"
149 * interface. The "receiver" edits its tree according to the operations
150 * described by the "driver".
152 * Note that the driver must have a perfect understanding of the tree which
153 * the receiver will be applying edits upon. There is no room for error here,
154 * and the interface embodies assumptions/requirements that the driver has
155 * about the targeted tree. As a result, this interface is a standardized
156 * mechanism of *describing* those change operations, but the intimate
157 * knowledge between the driver and the receiver implies some level of
158 * coupling between those subsystems.
160 * The set of changes, and the data necessary to describe it entirely, is
161 * completely unbounded. An addition of one simple 20 GB file might be well
162 * past the available memory of a machine processing these operations.
163 * As a result, the API to describe the changes is designed to be applied
164 * in a sequential (and relatively random-access) model. The operations
165 * can be streamed from the driver to the receiver, resulting in the
166 * receiver editing its tree to the target state defined by the driver.
171 * Classically, Subversion had a notion of a "tree delta" which could be
172 * passed around as an independent entity. Theory implied this delta was an
173 * entity in its own right, to be used when and where necessary.
174 * Unfortunately, this theory did not work well in practice. The producer
175 * and consumer of these tree deltas were (and are) tightly coupled. As noted
176 * above, the tree delta producer needed to be *totally* aware of the tree
177 * that it needed to edit. So rather than telling the delta consumer how to
178 * edit its tree, the classic #svn_delta_editor_t interface focused
179 * entirely on the tree delta, an intermediate (logical) data structure
180 * which was unusable outside of the particular, coupled pairing of producer
181 * and consumer. This generation of the API forgoes the logical tree delta
182 * entity and directly passes the necessary edits/changes/operations from
183 * the producer to the consumer. In our new parlance, one subsystem "drives"
184 * a set of operations describing the change, and a "receiver" accepts and
185 * applies them to its tree.
187 * The classic interface was named #svn_delta_editor_t and was described
188 * idiomatically as the "editor interface". This generation of the interface
189 * retains the "editor" name for that reason. All notions of a "tree delta"
190 * structure are no longer part of this interface.
192 * The old interface was purely vtable-based and used a number of special
193 * editors which could be interposed between the driver and receiver. Those
194 * editors provided cancellation, debugging, and other various operations.
195 * While the "interposition" pattern is still possible with this interface,
196 * the most common functionality (cancellation and debugging) have been
197 * integrated directly into this new editor system.
200 * <h3>Implementation Plan</h3>
201 * @note This section can be removed after Ev2 is fully implemented.
203 * The delta editor is pretty engrained throughout Subversion, so attempting
204 * to replace it in situ is somewhat akin to performing open heart surgery
205 * while the patient is running a marathon. However, a viable plan should
206 * make things a bit easier, and help parallelize the work.
208 * In short, the following items need to be done:
209 * -# Implement backward compatibility wrappers ("shims")
210 * -# Use shims to update editor consumers to Ev2
211 * -# Update editor producers to drive Ev2
212 * - This will largely involve rewriting the RA layers to accept and
214 * -# Optimize consumers and producers to leverage the features of Ev2
216 * The shims are largely self-contained, and as of this writing, are almost
217 * complete. They can be released without much ado. However, they do add
218 * <em>significant</em> performance regressions, which make releasing code
219 * which is half-delta-editor and half-Ev2 inadvisable. As such, the updating
220 * of producers and consumers to Ev2 will probably need to wait until 1.9,
221 * though it could be largely parallelized.
224 * @defgroup svn_editor The editor interface
228 /** An abstract object that edits a target tree.
230 * @note The term "follow" means at any later time in the editor drive.
231 * Terms such as "must", "must not", "required", "shall", "shall not",
232 * "should", "should not", "recommended", "may", and "optional" in this
233 * document are to be interpreted as described in RFC 2119.
235 * @note The editor objects are *not* reentrant. The receiver should not
236 * directly or indirectly invoke an editor API with the same object unless
237 * it has been marked as explicitly supporting reentrancy during a
238 * receiver's callback. This limitation extends to the cancellation
239 * callback, too. (This limitation is due to the scratch_pool shared by
240 * all callbacks, and cleared after each callback; a reentrant call could
241 * clear the outer call's pool). Note that the code itself is reentrant, so
242 * there is no problem using the APIs on different editor objects.
245 * <h3>Life-Cycle</h3>
247 * - @b Create: A receiver uses svn_editor_create() to create an
248 * "empty" svn_editor_t. It cannot be used yet, since it still lacks
249 * actual callback functions. svn_editor_create() sets the
250 * #svn_editor_t's callback baton and scratch pool that the callback
251 * functions receive, as well as a cancellation callback and baton
252 * (see "Cancellation" below).
254 * - @b Set callbacks: The receiver calls svn_editor_setcb_many() or a
255 * succession of the other svn_editor_setcb_*() functions to tell
256 * #svn_editor_t which functions to call when driven by the various
257 * operations. Callback functions are implemented by the receiver and must
258 * adhere to the @c svn_editor_cb_*_t function types as expected by the
259 * svn_editor_setcb_*() functions. See: \n
260 * svn_editor_cb_many_t \n
261 * svn_editor_setcb_many() \n
263 * svn_editor_setcb_add_directory() \n
264 * svn_editor_setcb_add_file() \n
265 * svn_editor_setcb_add_symlink() \n
266 * svn_editor_setcb_add_absent() \n
267 * svn_editor_setcb_alter_directory() \n
268 * svn_editor_setcb_alter_file() \n
269 * svn_editor_setcb_alter_symlink() \n
270 * svn_editor_setcb_delete() \n
271 * svn_editor_setcb_copy() \n
272 * svn_editor_setcb_move() \n
273 * svn_editor_setcb_complete() \n
274 * svn_editor_setcb_abort()
276 * - @b Drive: The driver is provided with the completed #svn_editor_t
277 * instance. (It is typically passed to a generic driving
278 * API, which could receive the driving editor calls over the network
279 * by providing a proxy #svn_editor_t on the remote side.)
280 * The driver invokes the #svn_editor_t instance's callback functions
281 * according to the restrictions defined below, in order to describe the
282 * entire set of operations necessary to transform the receiver's tree
283 * into the desired target. The callbacks can be invoked using the
284 * svn_editor_*() functions, i.e.: \n
285 * svn_editor_add_directory() \n
286 * svn_editor_add_file() \n
287 * svn_editor_add_symlink() \n
288 * svn_editor_add_absent() \n
289 * svn_editor_alter_directory() \n
290 * svn_editor_alter_file() \n
291 * svn_editor_alter_symlink() \n
292 * svn_editor_delete() \n
293 * svn_editor_copy() \n
294 * svn_editor_move() \n
296 * Just before each callback invocation is carried out, the @a cancel_func
297 * that was passed to svn_editor_create() is invoked to poll any
298 * external reasons to cancel the sequence of operations. Unless it
299 * overrides the cancellation (denoted by #SVN_ERR_CANCELLED), the driver
300 * aborts the transmission by invoking the svn_editor_abort() callback.
301 * Exceptions to this are calls to svn_editor_complete() and
302 * svn_editor_abort(), which cannot be canceled externally.
304 * - @b Receive: While the driver invokes operations upon the editor, the
305 * receiver finds its callback functions called with the information
306 * to operate on its tree. Each actual callback function receives those
307 * arguments that the driver passed to the "driving" functions, plus these:
308 * - @a baton: This is the @a editor_baton pointer originally passed to
309 * svn_editor_create(). It may be freely used by the callback
310 * implementation to store information across all callbacks.
311 * - @a scratch_pool: This temporary pool is cleared directly after
312 * each callback returns. See "Pool Usage".
314 * If the receiver encounters an error within a callback, it returns an
315 * #svn_error_t*. The driver receives this and aborts transmission.
317 * - @b Complete/Abort: The driver will end transmission by calling \n
318 * svn_editor_complete() if successful, or \n
319 * svn_editor_abort() if an error or cancellation occurred.
322 * <h3>Driving Order Restrictions</h3>
323 * In order to reduce complexity of callback receivers, the editor callbacks
324 * must be driven in adherence to these rules:
326 * - If any path is added (with add_*) or deleted/moved, then
327 * an svn_editor_alter_directory() call must be made for its parent
328 * directory with the target/eventual set of children.
330 * - svn_editor_add_directory() -- Another svn_editor_add_*() call must
331 * follow for each child mentioned in the @a children argument of any
332 * svn_editor_add_directory() call.
334 * - For each node created with add_*, if its parent was created using
335 * svn_editor_add_directory(), then the new child node MUST have been
336 * mentioned in the @a children parameter of the parent's creation.
337 * This allows the parent directory to properly mark the child as
338 * "incomplete" until the child's add_* call arrives.
340 * - A path should never be referenced more than once by the add_*, alter_*,
341 * and delete operations (the "Once Rule"). The source path of a copy (and
342 * its children, if a directory) may be copied many times, and are
343 * otherwise subject to the Once Rule. The destination path of a copy
344 * or move may have alter_* operations applied, but not add_* or delete.
345 * If the destination path of a copy or move is a directory,
346 * then its children are subject to the Once Rule. The source path of
347 * a move (and its child paths) may be referenced in add_*, or as the
348 * destination of a copy (where these new or copied nodes are subject
351 * - The ancestor of an added, copied-here, moved-here, or
352 * modified node may not be deleted. The ancestor may not be moved
353 * (instead: perform the move, *then* the edits).
355 * - svn_editor_delete() must not be used to replace a path -- i.e.
356 * svn_editor_delete() must not be followed by an svn_editor_add_*() on
357 * the same path, nor by an svn_editor_copy() or svn_editor_move() with
358 * the same path as the copy/move target.
360 * Instead of a prior delete call, the add/copy/move callbacks should be
361 * called with the @a replaces_rev argument set to the revision number of
362 * the node at this path that is being replaced. Note that the path and
363 * revision number are the key to finding any other information about the
364 * replaced node, like node kind, etc.
365 * @todo say which function(s) to use.
367 * - svn_editor_delete() must not be used to move a path -- i.e.
368 * svn_editor_delete() must not delete the source path of a previous
369 * svn_editor_copy() call. Instead, svn_editor_move() must be used.
370 * Note: if the desired semantics is one (or more) copies, followed
371 * by a delete... that is fine. It is simply that svn_editor_move()
372 * should be used to describe a semantic move.
374 * - One of svn_editor_complete() or svn_editor_abort() must be called
375 * exactly once, which must be the final call the driver invokes.
376 * Invoking svn_editor_complete() must imply that the set of changes has
377 * been transmitted completely and without errors, and invoking
378 * svn_editor_abort() must imply that the transformation was not completed
381 * - If any callback invocation (besides svn_editor_complete()) returns
382 * with an error, the driver must invoke svn_editor_abort() and stop
383 * transmitting operations.
386 * <h3>Receiving Restrictions</h3>
388 * All callbacks must complete their handling of a path before they return.
389 * Since future callbacks will never reference this path again (due to the
390 * Once Rule), the changes can and should be completed.
392 * This restriction is not recursive -- a directory's children may remain
393 * incomplete until later callback calls are received.
395 * For example, an svn_editor_add_directory() call during an 'update'
396 * operation will create the directory itself, including its properties,
397 * and will complete any client notification for the directory itself.
398 * The immediate children of the added directory, given in @a children,
399 * will be recorded in the WC as 'incomplete' and will be completed in the
400 * course of the same operation sequence, when the corresponding callbacks
401 * for these items are invoked.
404 * <h3>Timing and State</h3>
405 * The calls made by the driver to alter the state in the receiver are
406 * based on the receiver's *current* state, which includes all prior changes
407 * made during the edit.
409 * Example: copy A to B; set-props on A; copy A to C. The props on C
410 * should reflect the updated properties of A.
412 * Example: mv A@N to B; mv C@M to A. The second move cannot be marked as
413 * a "replacing" move since it is not replacing A. The node at A was moved
414 * away. The second operation is simply moving C to the now-empty path
418 * Each driver/receiver implementation of this editor interface must
419 * establish the expected root for all the paths sent and received via
420 * the callbacks' @a relpath arguments.
422 * For example, during an "update", the driver is the repository, as a
423 * whole. The receiver may have just a portion of that repository. Here,
424 * the receiver could tell the driver which repository URL the working
425 * copy refers to, and thus the driver could send @a relpath arguments
426 * that are relative to the receiver's working copy.
428 * @note Because the source of a copy may be located *anywhere* in the
429 * repository, editor drives should typically use the repository root
430 * as the negotiated root. This allows the @a src_relpath argument in
431 * svn_editor_copy() to specify any possible source.
434 * <h3>Pool Usage</h3>
435 * The @a result_pool passed to svn_editor_create() is used to allocate
436 * the #svn_editor_t instance, and thus it must not be cleared before the
437 * driver has finished driving the editor.
439 * The @a scratch_pool passed to each callback invocation is derived from
440 * the @a result_pool that was passed to svn_editor_create(). It is
441 * cleared directly after each single callback invocation.
442 * To allocate memory with a longer lifetime from within a callback
443 * function, you may use your own pool kept in the @a editor_baton.
445 * The @a scratch_pool passed to svn_editor_create() may be used to help
446 * during construction of the #svn_editor_t instance, but it is assumed to
447 * live only until svn_editor_create() returns.
450 * <h3>Cancellation</h3>
451 * To allow graceful interruption by external events (like a user abort),
452 * svn_editor_create() can be passed an #svn_cancel_func_t that is
453 * polled every time the driver invokes a callback, just before the
454 * actual editor callback implementation is invoked. If this function
455 * decides to return with an error, the driver will receive this error
456 * as if the callback function had returned it, i.e. as the result from
457 * calling any of the driving functions (e.g. svn_editor_add_directory()).
458 * As with any other error, the driver must then invoke svn_editor_abort()
459 * and abort the transformation sequence. See #svn_cancel_func_t.
461 * The @a cancel_baton argument to svn_editor_create() is passed
462 * unchanged to each poll of @a cancel_func.
464 * The cancellation function and baton are typically provided by the client
468 * @todo ### TODO anything missing?
472 typedef struct svn_editor_t svn_editor_t;
474 /** The kind of the checksum to be used throughout the #svn_editor_t APIs.
476 * @note ### This may change before Ev2 is official released, so just like
477 * everything else in this file, please don't rely upon it until then.
479 #define SVN_EDITOR_CHECKSUM_KIND svn_checksum_sha1
482 /** These function types define the callback functions a tree delta consumer
485 * Each of these "receiving" function types matches a "driving" function,
486 * which has the same arguments with these differences:
488 * - These "receiving" functions have a @a baton argument, which is the
489 * @a editor_baton originally passed to svn_editor_create(), as well as
490 * a @a scratch_pool argument.
492 * - The "driving" functions have an #svn_editor_t* argument, in order to
493 * call the implementations of the function types defined here that are
494 * registered with the given #svn_editor_t instance.
496 * Note that any remaining arguments for these function types are explained
497 * in the comment for the "driving" functions. Each function type links to
498 * its corresponding "driver".
500 * @see svn_editor_t, svn_editor_cb_many_t.
502 * @defgroup svn_editor_callbacks Editor callback definitions
506 /** @see svn_editor_add_directory(), svn_editor_t.
509 typedef svn_error_t *(*svn_editor_cb_add_directory_t)(
512 const apr_array_header_t *children,
514 svn_revnum_t replaces_rev,
515 apr_pool_t *scratch_pool);
517 /** @see svn_editor_add_file(), svn_editor_t.
520 typedef svn_error_t *(*svn_editor_cb_add_file_t)(
523 const svn_checksum_t *checksum,
524 svn_stream_t *contents,
526 svn_revnum_t replaces_rev,
527 apr_pool_t *scratch_pool);
529 /** @see svn_editor_add_symlink(), svn_editor_t.
532 typedef svn_error_t *(*svn_editor_cb_add_symlink_t)(
537 svn_revnum_t replaces_rev,
538 apr_pool_t *scratch_pool);
540 /** @see svn_editor_add_absent(), svn_editor_t.
543 typedef svn_error_t *(*svn_editor_cb_add_absent_t)(
546 svn_node_kind_t kind,
547 svn_revnum_t replaces_rev,
548 apr_pool_t *scratch_pool);
550 /** @see svn_editor_alter_directory(), svn_editor_t.
553 typedef svn_error_t *(*svn_editor_cb_alter_directory_t)(
556 svn_revnum_t revision,
557 const apr_array_header_t *children,
559 apr_pool_t *scratch_pool);
561 /** @see svn_editor_alter_file(), svn_editor_t.
564 typedef svn_error_t *(*svn_editor_cb_alter_file_t)(
567 svn_revnum_t revision,
568 const svn_checksum_t *checksum,
569 svn_stream_t *contents,
571 apr_pool_t *scratch_pool);
573 /** @see svn_editor_alter_symlink(), svn_editor_t.
576 typedef svn_error_t *(*svn_editor_cb_alter_symlink_t)(
579 svn_revnum_t revision,
582 apr_pool_t *scratch_pool);
584 /** @see svn_editor_delete(), svn_editor_t.
587 typedef svn_error_t *(*svn_editor_cb_delete_t)(
590 svn_revnum_t revision,
591 apr_pool_t *scratch_pool);
593 /** @see svn_editor_copy(), svn_editor_t.
596 typedef svn_error_t *(*svn_editor_cb_copy_t)(
598 const char *src_relpath,
599 svn_revnum_t src_revision,
600 const char *dst_relpath,
601 svn_revnum_t replaces_rev,
602 apr_pool_t *scratch_pool);
604 /** @see svn_editor_move(), svn_editor_t.
607 typedef svn_error_t *(*svn_editor_cb_move_t)(
609 const char *src_relpath,
610 svn_revnum_t src_revision,
611 const char *dst_relpath,
612 svn_revnum_t replaces_rev,
613 apr_pool_t *scratch_pool);
615 /** @see svn_editor_complete(), svn_editor_t.
618 typedef svn_error_t *(*svn_editor_cb_complete_t)(
620 apr_pool_t *scratch_pool);
622 /** @see svn_editor_abort(), svn_editor_t.
625 typedef svn_error_t *(*svn_editor_cb_abort_t)(
627 apr_pool_t *scratch_pool);
632 /** These functions create an editor instance so that it can be driven.
634 * @defgroup svn_editor_create Editor creation
638 /** Allocate an #svn_editor_t instance from @a result_pool, store
639 * @a editor_baton, @a cancel_func and @a cancel_baton in the new instance
640 * and return it in @a editor.
641 * @a scratch_pool is used for temporary allocations (if any). Note that
642 * this is NOT the same @a scratch_pool that is passed to callback functions.
647 svn_editor_create(svn_editor_t **editor,
649 svn_cancel_func_t cancel_func,
651 apr_pool_t *result_pool,
652 apr_pool_t *scratch_pool);
655 /** Return an editor's private baton.
657 * In some cases, the baton is required outside of the callbacks. This
658 * function returns the private baton for use.
663 svn_editor_get_baton(const svn_editor_t *editor);
666 /** Sets the #svn_editor_cb_add_directory_t callback in @a editor
668 * @a scratch_pool is used for temporary allocations (if any).
669 * @see also svn_editor_setcb_many().
673 svn_editor_setcb_add_directory(svn_editor_t *editor,
674 svn_editor_cb_add_directory_t callback,
675 apr_pool_t *scratch_pool);
677 /** Sets the #svn_editor_cb_add_file_t callback in @a editor
679 * @a scratch_pool is used for temporary allocations (if any).
680 * @see also svn_editor_setcb_many().
684 svn_editor_setcb_add_file(svn_editor_t *editor,
685 svn_editor_cb_add_file_t callback,
686 apr_pool_t *scratch_pool);
688 /** Sets the #svn_editor_cb_add_symlink_t callback in @a editor
690 * @a scratch_pool is used for temporary allocations (if any).
691 * @see also svn_editor_setcb_many().
695 svn_editor_setcb_add_symlink(svn_editor_t *editor,
696 svn_editor_cb_add_symlink_t callback,
697 apr_pool_t *scratch_pool);
699 /** Sets the #svn_editor_cb_add_absent_t callback in @a editor
701 * @a scratch_pool is used for temporary allocations (if any).
702 * @see also svn_editor_setcb_many().
706 svn_editor_setcb_add_absent(svn_editor_t *editor,
707 svn_editor_cb_add_absent_t callback,
708 apr_pool_t *scratch_pool);
710 /** Sets the #svn_editor_cb_alter_directory_t callback in @a editor
712 * @a scratch_pool is used for temporary allocations (if any).
713 * @see also svn_editor_setcb_many().
717 svn_editor_setcb_alter_directory(svn_editor_t *editor,
718 svn_editor_cb_alter_directory_t callback,
719 apr_pool_t *scratch_pool);
721 /** Sets the #svn_editor_cb_alter_file_t callback in @a editor
723 * @a scratch_pool is used for temporary allocations (if any).
724 * @see also svn_editor_setcb_many().
728 svn_editor_setcb_alter_file(svn_editor_t *editor,
729 svn_editor_cb_alter_file_t callback,
730 apr_pool_t *scratch_pool);
732 /** Sets the #svn_editor_cb_alter_symlink_t callback in @a editor
734 * @a scratch_pool is used for temporary allocations (if any).
735 * @see also svn_editor_setcb_many().
739 svn_editor_setcb_alter_symlink(svn_editor_t *editor,
740 svn_editor_cb_alter_symlink_t callback,
741 apr_pool_t *scratch_pool);
743 /** Sets the #svn_editor_cb_delete_t callback in @a editor
745 * @a scratch_pool is used for temporary allocations (if any).
746 * @see also svn_editor_setcb_many().
750 svn_editor_setcb_delete(svn_editor_t *editor,
751 svn_editor_cb_delete_t callback,
752 apr_pool_t *scratch_pool);
754 /** Sets the #svn_editor_cb_copy_t callback in @a editor
756 * @a scratch_pool is used for temporary allocations (if any).
757 * @see also svn_editor_setcb_many().
761 svn_editor_setcb_copy(svn_editor_t *editor,
762 svn_editor_cb_copy_t callback,
763 apr_pool_t *scratch_pool);
765 /** Sets the #svn_editor_cb_move_t callback in @a editor
767 * @a scratch_pool is used for temporary allocations (if any).
768 * @see also svn_editor_setcb_many().
772 svn_editor_setcb_move(svn_editor_t *editor,
773 svn_editor_cb_move_t callback,
774 apr_pool_t *scratch_pool);
776 /** Sets the #svn_editor_cb_complete_t callback in @a editor
778 * @a scratch_pool is used for temporary allocations (if any).
779 * @see also svn_editor_setcb_many().
783 svn_editor_setcb_complete(svn_editor_t *editor,
784 svn_editor_cb_complete_t callback,
785 apr_pool_t *scratch_pool);
787 /** Sets the #svn_editor_cb_abort_t callback in @a editor
789 * @a scratch_pool is used for temporary allocations (if any).
790 * @see also svn_editor_setcb_many().
794 svn_editor_setcb_abort(svn_editor_t *editor,
795 svn_editor_cb_abort_t callback,
796 apr_pool_t *scratch_pool);
799 /** Lists a complete set of editor callbacks.
800 * This is a convenience structure.
801 * @see svn_editor_setcb_many(), svn_editor_create(), svn_editor_t.
804 typedef struct svn_editor_cb_many_t
806 svn_editor_cb_add_directory_t cb_add_directory;
807 svn_editor_cb_add_file_t cb_add_file;
808 svn_editor_cb_add_symlink_t cb_add_symlink;
809 svn_editor_cb_add_absent_t cb_add_absent;
810 svn_editor_cb_alter_directory_t cb_alter_directory;
811 svn_editor_cb_alter_file_t cb_alter_file;
812 svn_editor_cb_alter_symlink_t cb_alter_symlink;
813 svn_editor_cb_delete_t cb_delete;
814 svn_editor_cb_copy_t cb_copy;
815 svn_editor_cb_move_t cb_move;
816 svn_editor_cb_complete_t cb_complete;
817 svn_editor_cb_abort_t cb_abort;
819 } svn_editor_cb_many_t;
821 /** Sets all the callback functions in @a editor at once, according to the
822 * callback functions stored in @a many.
823 * @a scratch_pool is used for temporary allocations (if any).
827 svn_editor_setcb_many(svn_editor_t *editor,
828 const svn_editor_cb_many_t *many,
829 apr_pool_t *scratch_pool);
834 /** These functions are called by the tree delta driver to edit the target.
838 * @defgroup svn_editor_drive Driving the editor
842 /** Drive @a editor's #svn_editor_cb_add_directory_t callback.
844 * Create a new directory at @a relpath. The immediate parent of @a relpath
845 * is expected to exist.
847 * For descriptions of @a props and @a replaces_rev, see
848 * svn_editor_add_file().
850 * A complete listing of the immediate children of @a relpath that will be
851 * added subsequently is given in @a children. @a children is an array of
852 * const char*s, each giving the basename of an immediate child. It is an
853 * error to pass NULL for @a children; use an empty array to indicate
854 * the new directory will have no children.
856 * For all restrictions on driving the editor, see #svn_editor_t.
859 svn_editor_add_directory(svn_editor_t *editor,
861 const apr_array_header_t *children,
863 svn_revnum_t replaces_rev);
865 /** Drive @a editor's #svn_editor_cb_add_file_t callback.
867 * Create a new file at @a relpath. The immediate parent of @a relpath
868 * is expected to exist.
870 * The file's contents are specified in @a contents which has a checksum
871 * matching @a checksum. Both values must be non-NULL.
873 * Set the properties of the new file to @a props, which is an
874 * apr_hash_t holding key-value pairs. Each key is a const char* of a
875 * property name, each value is a const svn_string_t*. If no properties are
876 * being set on the new file, @a props must be the empty hash. It is an
877 * error to pass NULL for @a props.
879 * If this add is expected to replace a previously existing file, symlink or
880 * directory at @a relpath, the revision number of the node to be replaced
881 * must be given in @a replaces_rev. Otherwise, @a replaces_rev must be
882 * #SVN_INVALID_REVNUM. Note: it is not allowed to call a "delete" followed
883 * by an "add" on the same path. Instead, an "add" with @a replaces_rev set
884 * accordingly MUST be used.
886 * For all restrictions on driving the editor, see #svn_editor_t.
890 svn_editor_add_file(svn_editor_t *editor,
892 const svn_checksum_t *checksum,
893 svn_stream_t *contents,
895 svn_revnum_t replaces_rev);
897 /** Drive @a editor's #svn_editor_cb_add_symlink_t callback.
899 * Create a new symbolic link at @a relpath, with a link target of @a
900 * target. The immediate parent of @a relpath is expected to exist.
902 * For descriptions of @a props and @a replaces_rev, see
903 * svn_editor_add_file().
905 * For all restrictions on driving the editor, see #svn_editor_t.
909 svn_editor_add_symlink(svn_editor_t *editor,
913 svn_revnum_t replaces_rev);
915 /** Drive @a editor's #svn_editor_cb_add_absent_t callback.
917 * Create an "absent" node of kind @a kind at @a relpath. The immediate
918 * parent of @a relpath is expected to exist.
919 * ### TODO @todo explain "absent".
920 * ### JAF: What are the allowed values of 'kind'?
922 * For a description of @a replaces_rev, see svn_editor_add_file().
924 * For all restrictions on driving the editor, see #svn_editor_t.
928 svn_editor_add_absent(svn_editor_t *editor,
930 svn_node_kind_t kind,
931 svn_revnum_t replaces_rev);
933 /** Drive @a editor's #svn_editor_cb_alter_directory_t callback.
935 * Alter the properties of the directory at @a relpath.
937 * @a revision specifies the revision at which the receiver should
938 * expect to find this node. That is, @a relpath at the start of the
939 * whole edit and @a relpath at @a revision must lie within the same
940 * node-rev (aka location history segment). This information may be used
941 * to catch an attempt to alter and out-of-date directory. If the
942 * directory does not have a corresponding revision in the repository
943 * (e.g. it has not yet been committed), then @a revision should be
944 * #SVN_INVALID_REVNUM.
946 * If any changes to the set of children will be made in the future of
947 * the edit drive, then @a children MUST specify the resulting set of
948 * children. See svn_editor_add_directory() for the format of @a children.
949 * If not changes will be made, then NULL may be specified.
951 * For a description of @a props, see svn_editor_add_file(). If no changes
952 * to the properties will be made (ie. only future changes to the set of
953 * children), then @a props may be NULL.
955 * It is an error to pass NULL for both @a children and @a props.
957 * For all restrictions on driving the editor, see #svn_editor_t.
961 svn_editor_alter_directory(svn_editor_t *editor,
963 svn_revnum_t revision,
964 const apr_array_header_t *children,
967 /** Drive @a editor's #svn_editor_cb_alter_file_t callback.
969 * Alter the properties and/or the contents of the file at @a relpath
970 * with @a revision as its expected revision. See svn_editor_alter_directory()
971 * for more information about @a revision.
973 * If @a props is non-NULL, then the properties will be applied.
975 * If @a contents is non-NULL, then the stream will be copied to
976 * the file, and its checksum must match @a checksum (which must also
977 * be non-NULL). If @a contents is NULL, then @a checksum must also
978 * be NULL, and no change will be applied to the file's contents.
980 * The properties and/or the contents must be changed. It is an error to
981 * pass NULL for @a props, @a checksum, and @a contents.
983 * For a description of @a checksum and @a contents see
984 * svn_editor_add_file(). This function allows @a props to be NULL, but
985 * the parameter is otherwise described by svn_editor_add_file().
987 * For all restrictions on driving the editor, see #svn_editor_t.
991 svn_editor_alter_file(svn_editor_t *editor,
993 svn_revnum_t revision,
994 const svn_checksum_t *checksum,
995 svn_stream_t *contents,
998 /** Drive @a editor's #svn_editor_cb_alter_symlink_t callback.
1000 * Alter the properties and/or the target of the symlink at @a relpath
1001 * with @a revision as its expected revision. See svn_editor_alter_directory()
1002 * for more information about @a revision.
1004 * If @a props is non-NULL, then the properties will be applied.
1006 * If @a target is non-NULL, then the symlink's target will be updated.
1008 * The properties and/or the target must be changed. It is an error to
1009 * pass NULL for @a props and @a target.
1011 * This function allows @a props to be NULL, but the parameter is
1012 * otherwise described by svn_editor_add_file().
1014 * For all restrictions on driving the editor, see #svn_editor_t.
1015 * @since New in 1.8.
1018 svn_editor_alter_symlink(svn_editor_t *editor,
1019 const char *relpath,
1020 svn_revnum_t revision,
1024 /** Drive @a editor's #svn_editor_cb_delete_t callback.
1026 * Delete the existing node at @a relpath, expected to be identical to
1027 * revision @a revision of that path.
1029 * For all restrictions on driving the editor, see #svn_editor_t.
1030 * @since New in 1.8.
1033 svn_editor_delete(svn_editor_t *editor,
1034 const char *relpath,
1035 svn_revnum_t revision);
1037 /** Drive @a editor's #svn_editor_cb_copy_t callback.
1039 * Copy the node at @a src_relpath, expected to be identical to revision @a
1040 * src_revision of that path, to @a dst_relpath.
1042 * For a description of @a replaces_rev, see svn_editor_add_file().
1044 * @note See the general instructions on paths for this API. Since the
1045 * @a src_relpath argument must generally be able to reference any node
1046 * in the repository, the implication is that the editor's root must be
1047 * the repository root.
1049 * For all restrictions on driving the editor, see #svn_editor_t.
1050 * @since New in 1.8.
1053 svn_editor_copy(svn_editor_t *editor,
1054 const char *src_relpath,
1055 svn_revnum_t src_revision,
1056 const char *dst_relpath,
1057 svn_revnum_t replaces_rev);
1059 /** Drive @a editor's #svn_editor_cb_move_t callback.
1061 * Move the node at @a src_relpath to @a dst_relpath.
1063 * @a src_revision specifies the revision at which the receiver should
1064 * expect to find this node. That is, @a src_relpath at the start of
1065 * the whole edit and @a src_relpath at @a src_revision must lie within
1066 * the same node-rev (aka history-segment). This is just like the
1067 * revisions specified to svn_editor_delete().
1069 * For a description of @a replaces_rev, see svn_editor_add_file().
1071 * ### what happens if one side of this move is not "within" the receiver's
1074 * For all restrictions on driving the editor, see #svn_editor_t.
1075 * @since New in 1.8.
1078 svn_editor_move(svn_editor_t *editor,
1079 const char *src_relpath,
1080 svn_revnum_t src_revision,
1081 const char *dst_relpath,
1082 svn_revnum_t replaces_rev);
1084 /** Drive @a editor's #svn_editor_cb_complete_t callback.
1086 * Send word that the edit has been completed successfully.
1088 * For all restrictions on driving the editor, see #svn_editor_t.
1089 * @since New in 1.8.
1092 svn_editor_complete(svn_editor_t *editor);
1094 /** Drive @a editor's #svn_editor_cb_abort_t callback.
1096 * Notify that the edit transmission was not successful.
1097 * ### TODO @todo Shouldn't we add a reason-for-aborting argument?
1099 * For all restrictions on driving the editor, see #svn_editor_t.
1100 * @since New in 1.8.
1103 svn_editor_abort(svn_editor_t *editor);
1109 /** A temporary API which conditionally inserts a double editor shim
1110 * into the chain of delta editors. Used for testing Editor v2.
1112 * Whether or not the shims are inserted is controlled by a compile-time
1113 * option in libsvn_delta/compat.c.
1115 * @note The use of these shims and this API will likely cause all kinds
1116 * of performance degredation. (Which is actually a moot point since they
1117 * don't even work properly yet anyway.)
1120 svn_editor__insert_shims(const svn_delta_editor_t **deditor_out,
1121 void **dedit_baton_out,
1122 const svn_delta_editor_t *deditor_in,
1123 void *dedit_baton_in,
1124 const char *repos_root,
1125 const char *base_dir,
1126 svn_delta_shim_callbacks_t *shim_callbacks,
1127 apr_pool_t *result_pool,
1128 apr_pool_t *scratch_pool);
1133 #endif /* __cplusplus */
1135 #endif /* SVN_EDITOR_H */