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_rotate() \n
274 * svn_editor_setcb_complete() \n
275 * svn_editor_setcb_abort()
277 * - @b Drive: The driver is provided with the completed #svn_editor_t
278 * instance. (It is typically passed to a generic driving
279 * API, which could receive the driving editor calls over the network
280 * by providing a proxy #svn_editor_t on the remote side.)
281 * The driver invokes the #svn_editor_t instance's callback functions
282 * according to the restrictions defined below, in order to describe the
283 * entire set of operations necessary to transform the receiver's tree
284 * into the desired target. The callbacks can be invoked using the
285 * svn_editor_*() functions, i.e.: \n
286 * svn_editor_add_directory() \n
287 * svn_editor_add_file() \n
288 * svn_editor_add_symlink() \n
289 * svn_editor_add_absent() \n
290 * svn_editor_alter_directory() \n
291 * svn_editor_alter_file() \n
292 * svn_editor_alter_symlink() \n
293 * svn_editor_delete() \n
294 * svn_editor_copy() \n
295 * svn_editor_move() \n
296 * svn_editor_rotate()
298 * Just before each callback invocation is carried out, the @a cancel_func
299 * that was passed to svn_editor_create() is invoked to poll any
300 * external reasons to cancel the sequence of operations. Unless it
301 * overrides the cancellation (denoted by #SVN_ERR_CANCELLED), the driver
302 * aborts the transmission by invoking the svn_editor_abort() callback.
303 * Exceptions to this are calls to svn_editor_complete() and
304 * svn_editor_abort(), which cannot be canceled externally.
306 * - @b Receive: While the driver invokes operations upon the editor, the
307 * receiver finds its callback functions called with the information
308 * to operate on its tree. Each actual callback function receives those
309 * arguments that the driver passed to the "driving" functions, plus these:
310 * - @a baton: This is the @a editor_baton pointer originally passed to
311 * svn_editor_create(). It may be freely used by the callback
312 * implementation to store information across all callbacks.
313 * - @a scratch_pool: This temporary pool is cleared directly after
314 * each callback returns. See "Pool Usage".
316 * If the receiver encounters an error within a callback, it returns an
317 * #svn_error_t*. The driver receives this and aborts transmission.
319 * - @b Complete/Abort: The driver will end transmission by calling \n
320 * svn_editor_complete() if successful, or \n
321 * svn_editor_abort() if an error or cancellation occurred.
324 * <h3>Driving Order Restrictions</h3>
325 * In order to reduce complexity of callback receivers, the editor callbacks
326 * must be driven in adherence to these rules:
328 * - If any path is added (with add_*) or deleted/moved/rotated, then
329 * an svn_editor_alter_directory() call must be made for its parent
330 * directory with the target/eventual set of children.
332 * - svn_editor_add_directory() -- Another svn_editor_add_*() call must
333 * follow for each child mentioned in the @a children argument of any
334 * svn_editor_add_directory() call.
336 * - For each node created with add_*, if its parent was created using
337 * svn_editor_add_directory(), then the new child node MUST have been
338 * mentioned in the @a children parameter of the parent's creation.
339 * This allows the parent directory to properly mark the child as
340 * "incomplete" until the child's add_* call arrives.
342 * - A path should never be referenced more than once by the add_*, alter_*,
343 * and delete operations (the "Once Rule"). The source path of a copy (and
344 * its children, if a directory) may be copied many times, and are
345 * otherwise subject to the Once Rule. The destination path of a copy
346 * or move may have alter_* operations applied, but not add_* or delete.
347 * If the destination path of a copy, move, or rotate is a directory,
348 * then its children are subject to the Once Rule. The source path of
349 * a move (and its child paths) may be referenced in add_*, or as the
350 * destination of a copy (where these new or copied nodes are subject
351 * to the Once Rule). Paths listed in a rotation are both sources and
352 * destinations, so they may not be referenced again in an add_* or a
353 * deletion; these paths may have alter_* operations applied.
355 * - The ancestor of an added, copied-here, moved-here, rotated, or
356 * modified node may not be deleted. The ancestor may not be moved
357 * (instead: perform the move, *then* the edits).
359 * - svn_editor_delete() must not be used to replace a path -- i.e.
360 * svn_editor_delete() must not be followed by an svn_editor_add_*() on
361 * the same path, nor by an svn_editor_copy() or svn_editor_move() with
362 * the same path as the copy/move target.
364 * Instead of a prior delete call, the add/copy/move callbacks should be
365 * called with the @a replaces_rev argument set to the revision number of
366 * the node at this path that is being replaced. Note that the path and
367 * revision number are the key to finding any other information about the
368 * replaced node, like node kind, etc.
369 * @todo say which function(s) to use.
371 * - svn_editor_delete() must not be used to move a path -- i.e.
372 * svn_editor_delete() must not delete the source path of a previous
373 * svn_editor_copy() call. Instead, svn_editor_move() must be used.
374 * Note: if the desired semantics is one (or more) copies, followed
375 * by a delete... that is fine. It is simply that svn_editor_move()
376 * should be used to describe a semantic move.
378 * - Paths mentioned in svn_editor_rotate() may have their properties
379 * and contents edited (via alter_* calls) by a previous or later call,
380 * but they may not be subject to a later move, rotate, or deletion.
382 * - One of svn_editor_complete() or svn_editor_abort() must be called
383 * exactly once, which must be the final call the driver invokes.
384 * Invoking svn_editor_complete() must imply that the set of changes has
385 * been transmitted completely and without errors, and invoking
386 * svn_editor_abort() must imply that the transformation was not completed
389 * - If any callback invocation (besides svn_editor_complete()) returns
390 * with an error, the driver must invoke svn_editor_abort() and stop
391 * transmitting operations.
394 * <h3>Receiving Restrictions</h3>
396 * All callbacks must complete their handling of a path before they return.
397 * Since future callbacks will never reference this path again (due to the
398 * Once Rule), the changes can and should be completed.
400 * This restriction is not recursive -- a directory's children may remain
401 * incomplete until later callback calls are received.
403 * For example, an svn_editor_add_directory() call during an 'update'
404 * operation will create the directory itself, including its properties,
405 * and will complete any client notification for the directory itself.
406 * The immediate children of the added directory, given in @a children,
407 * will be recorded in the WC as 'incomplete' and will be completed in the
408 * course of the same operation sequence, when the corresponding callbacks
409 * for these items are invoked.
412 * <h3>Timing and State</h3>
413 * The calls made by the driver to alter the state in the receiver are
414 * based on the receiver's *current* state, which includes all prior changes
415 * made during the edit.
417 * Example: copy A to B; set-props on A; copy A to C. The props on C
418 * should reflect the updated properties of A.
420 * Example: mv A@N to B; mv C@M to A. The second move cannot be marked as
421 * a "replacing" move since it is not replacing A. The node at A was moved
422 * away. The second operation is simply moving C to the now-empty path
426 * Each driver/receiver implementation of this editor interface must
427 * establish the expected root for all the paths sent and received via
428 * the callbacks' @a relpath arguments.
430 * For example, during an "update", the driver is the repository, as a
431 * whole. The receiver may have just a portion of that repository. Here,
432 * the receiver could tell the driver which repository URL the working
433 * copy refers to, and thus the driver could send @a relpath arguments
434 * that are relative to the receiver's working copy.
436 * @note Because the source of a copy may be located *anywhere* in the
437 * repository, editor drives should typically use the repository root
438 * as the negotiated root. This allows the @a src_relpath argument in
439 * svn_editor_copy() to specify any possible source.
442 * <h3>Pool Usage</h3>
443 * The @a result_pool passed to svn_editor_create() is used to allocate
444 * the #svn_editor_t instance, and thus it must not be cleared before the
445 * driver has finished driving the editor.
447 * The @a scratch_pool passed to each callback invocation is derived from
448 * the @a result_pool that was passed to svn_editor_create(). It is
449 * cleared directly after each single callback invocation.
450 * To allocate memory with a longer lifetime from within a callback
451 * function, you may use your own pool kept in the @a editor_baton.
453 * The @a scratch_pool passed to svn_editor_create() may be used to help
454 * during construction of the #svn_editor_t instance, but it is assumed to
455 * live only until svn_editor_create() returns.
458 * <h3>Cancellation</h3>
459 * To allow graceful interruption by external events (like a user abort),
460 * svn_editor_create() can be passed an #svn_cancel_func_t that is
461 * polled every time the driver invokes a callback, just before the
462 * actual editor callback implementation is invoked. If this function
463 * decides to return with an error, the driver will receive this error
464 * as if the callback function had returned it, i.e. as the result from
465 * calling any of the driving functions (e.g. svn_editor_add_directory()).
466 * As with any other error, the driver must then invoke svn_editor_abort()
467 * and abort the transformation sequence. See #svn_cancel_func_t.
469 * The @a cancel_baton argument to svn_editor_create() is passed
470 * unchanged to each poll of @a cancel_func.
472 * The cancellation function and baton are typically provided by the client
476 * @todo ### TODO anything missing?
480 typedef struct svn_editor_t svn_editor_t;
482 /** The kind of the checksum to be used throughout the #svn_editor_t APIs.
484 * @note ### This may change before Ev2 is official released, so just like
485 * everything else in this file, please don't rely upon it until then.
487 #define SVN_EDITOR_CHECKSUM_KIND svn_checksum_sha1
490 /** These function types define the callback functions a tree delta consumer
493 * Each of these "receiving" function types matches a "driving" function,
494 * which has the same arguments with these differences:
496 * - These "receiving" functions have a @a baton argument, which is the
497 * @a editor_baton originally passed to svn_editor_create(), as well as
498 * a @a scratch_pool argument.
500 * - The "driving" functions have an #svn_editor_t* argument, in order to
501 * call the implementations of the function types defined here that are
502 * registered with the given #svn_editor_t instance.
504 * Note that any remaining arguments for these function types are explained
505 * in the comment for the "driving" functions. Each function type links to
506 * its corresponding "driver".
508 * @see svn_editor_t, svn_editor_cb_many_t.
510 * @defgroup svn_editor_callbacks Editor callback definitions
514 /** @see svn_editor_add_directory(), svn_editor_t.
517 typedef svn_error_t *(*svn_editor_cb_add_directory_t)(
520 const apr_array_header_t *children,
522 svn_revnum_t replaces_rev,
523 apr_pool_t *scratch_pool);
525 /** @see svn_editor_add_file(), svn_editor_t.
528 typedef svn_error_t *(*svn_editor_cb_add_file_t)(
531 const svn_checksum_t *checksum,
532 svn_stream_t *contents,
534 svn_revnum_t replaces_rev,
535 apr_pool_t *scratch_pool);
537 /** @see svn_editor_add_symlink(), svn_editor_t.
540 typedef svn_error_t *(*svn_editor_cb_add_symlink_t)(
545 svn_revnum_t replaces_rev,
546 apr_pool_t *scratch_pool);
548 /** @see svn_editor_add_absent(), svn_editor_t.
551 typedef svn_error_t *(*svn_editor_cb_add_absent_t)(
554 svn_node_kind_t kind,
555 svn_revnum_t replaces_rev,
556 apr_pool_t *scratch_pool);
558 /** @see svn_editor_alter_directory(), svn_editor_t.
561 typedef svn_error_t *(*svn_editor_cb_alter_directory_t)(
564 svn_revnum_t revision,
565 const apr_array_header_t *children,
567 apr_pool_t *scratch_pool);
569 /** @see svn_editor_alter_file(), svn_editor_t.
572 typedef svn_error_t *(*svn_editor_cb_alter_file_t)(
575 svn_revnum_t revision,
577 const svn_checksum_t *checksum,
578 svn_stream_t *contents,
579 apr_pool_t *scratch_pool);
581 /** @see svn_editor_alter_symlink(), svn_editor_t.
584 typedef svn_error_t *(*svn_editor_cb_alter_symlink_t)(
587 svn_revnum_t revision,
590 apr_pool_t *scratch_pool);
592 /** @see svn_editor_delete(), svn_editor_t.
595 typedef svn_error_t *(*svn_editor_cb_delete_t)(
598 svn_revnum_t revision,
599 apr_pool_t *scratch_pool);
601 /** @see svn_editor_copy(), svn_editor_t.
604 typedef svn_error_t *(*svn_editor_cb_copy_t)(
606 const char *src_relpath,
607 svn_revnum_t src_revision,
608 const char *dst_relpath,
609 svn_revnum_t replaces_rev,
610 apr_pool_t *scratch_pool);
612 /** @see svn_editor_move(), svn_editor_t.
615 typedef svn_error_t *(*svn_editor_cb_move_t)(
617 const char *src_relpath,
618 svn_revnum_t src_revision,
619 const char *dst_relpath,
620 svn_revnum_t replaces_rev,
621 apr_pool_t *scratch_pool);
623 /** @see svn_editor_rotate(), svn_editor_t.
626 typedef svn_error_t *(*svn_editor_cb_rotate_t)(
628 const apr_array_header_t *relpaths,
629 const apr_array_header_t *revisions,
630 apr_pool_t *scratch_pool);
632 /** @see svn_editor_complete(), svn_editor_t.
635 typedef svn_error_t *(*svn_editor_cb_complete_t)(
637 apr_pool_t *scratch_pool);
639 /** @see svn_editor_abort(), svn_editor_t.
642 typedef svn_error_t *(*svn_editor_cb_abort_t)(
644 apr_pool_t *scratch_pool);
649 /** These functions create an editor instance so that it can be driven.
651 * @defgroup svn_editor_create Editor creation
655 /** Allocate an #svn_editor_t instance from @a result_pool, store
656 * @a editor_baton, @a cancel_func and @a cancel_baton in the new instance
657 * and return it in @a editor.
658 * @a scratch_pool is used for temporary allocations (if any). Note that
659 * this is NOT the same @a scratch_pool that is passed to callback functions.
664 svn_editor_create(svn_editor_t **editor,
666 svn_cancel_func_t cancel_func,
668 apr_pool_t *result_pool,
669 apr_pool_t *scratch_pool);
672 /** Return an editor's private baton.
674 * In some cases, the baton is required outside of the callbacks. This
675 * function returns the private baton for use.
680 svn_editor_get_baton(const svn_editor_t *editor);
683 /** Sets the #svn_editor_cb_add_directory_t callback in @a editor
685 * @a scratch_pool is used for temporary allocations (if any).
686 * @see also svn_editor_setcb_many().
690 svn_editor_setcb_add_directory(svn_editor_t *editor,
691 svn_editor_cb_add_directory_t callback,
692 apr_pool_t *scratch_pool);
694 /** Sets the #svn_editor_cb_add_file_t callback in @a editor
696 * @a scratch_pool is used for temporary allocations (if any).
697 * @see also svn_editor_setcb_many().
701 svn_editor_setcb_add_file(svn_editor_t *editor,
702 svn_editor_cb_add_file_t callback,
703 apr_pool_t *scratch_pool);
705 /** Sets the #svn_editor_cb_add_symlink_t callback in @a editor
707 * @a scratch_pool is used for temporary allocations (if any).
708 * @see also svn_editor_setcb_many().
712 svn_editor_setcb_add_symlink(svn_editor_t *editor,
713 svn_editor_cb_add_symlink_t callback,
714 apr_pool_t *scratch_pool);
716 /** Sets the #svn_editor_cb_add_absent_t callback in @a editor
718 * @a scratch_pool is used for temporary allocations (if any).
719 * @see also svn_editor_setcb_many().
723 svn_editor_setcb_add_absent(svn_editor_t *editor,
724 svn_editor_cb_add_absent_t callback,
725 apr_pool_t *scratch_pool);
727 /** Sets the #svn_editor_cb_alter_directory_t callback in @a editor
729 * @a scratch_pool is used for temporary allocations (if any).
730 * @see also svn_editor_setcb_many().
734 svn_editor_setcb_alter_directory(svn_editor_t *editor,
735 svn_editor_cb_alter_directory_t callback,
736 apr_pool_t *scratch_pool);
738 /** Sets the #svn_editor_cb_alter_file_t callback in @a editor
740 * @a scratch_pool is used for temporary allocations (if any).
741 * @see also svn_editor_setcb_many().
745 svn_editor_setcb_alter_file(svn_editor_t *editor,
746 svn_editor_cb_alter_file_t callback,
747 apr_pool_t *scratch_pool);
749 /** Sets the #svn_editor_cb_alter_symlink_t callback in @a editor
751 * @a scratch_pool is used for temporary allocations (if any).
752 * @see also svn_editor_setcb_many().
756 svn_editor_setcb_alter_symlink(svn_editor_t *editor,
757 svn_editor_cb_alter_symlink_t callback,
758 apr_pool_t *scratch_pool);
760 /** Sets the #svn_editor_cb_delete_t callback in @a editor
762 * @a scratch_pool is used for temporary allocations (if any).
763 * @see also svn_editor_setcb_many().
767 svn_editor_setcb_delete(svn_editor_t *editor,
768 svn_editor_cb_delete_t callback,
769 apr_pool_t *scratch_pool);
771 /** Sets the #svn_editor_cb_copy_t callback in @a editor
773 * @a scratch_pool is used for temporary allocations (if any).
774 * @see also svn_editor_setcb_many().
778 svn_editor_setcb_copy(svn_editor_t *editor,
779 svn_editor_cb_copy_t callback,
780 apr_pool_t *scratch_pool);
782 /** Sets the #svn_editor_cb_move_t callback in @a editor
784 * @a scratch_pool is used for temporary allocations (if any).
785 * @see also svn_editor_setcb_many().
789 svn_editor_setcb_move(svn_editor_t *editor,
790 svn_editor_cb_move_t callback,
791 apr_pool_t *scratch_pool);
793 /** Sets the #svn_editor_cb_rotate_t callback in @a editor
795 * @a scratch_pool is used for temporary allocations (if any).
796 * @see also svn_editor_setcb_many().
800 svn_editor_setcb_rotate(svn_editor_t *editor,
801 svn_editor_cb_rotate_t callback,
802 apr_pool_t *scratch_pool);
804 /** Sets the #svn_editor_cb_complete_t callback in @a editor
806 * @a scratch_pool is used for temporary allocations (if any).
807 * @see also svn_editor_setcb_many().
811 svn_editor_setcb_complete(svn_editor_t *editor,
812 svn_editor_cb_complete_t callback,
813 apr_pool_t *scratch_pool);
815 /** Sets the #svn_editor_cb_abort_t callback in @a editor
817 * @a scratch_pool is used for temporary allocations (if any).
818 * @see also svn_editor_setcb_many().
822 svn_editor_setcb_abort(svn_editor_t *editor,
823 svn_editor_cb_abort_t callback,
824 apr_pool_t *scratch_pool);
827 /** Lists a complete set of editor callbacks.
828 * This is a convenience structure.
829 * @see svn_editor_setcb_many(), svn_editor_create(), svn_editor_t.
832 typedef struct svn_editor_cb_many_t
834 svn_editor_cb_add_directory_t cb_add_directory;
835 svn_editor_cb_add_file_t cb_add_file;
836 svn_editor_cb_add_symlink_t cb_add_symlink;
837 svn_editor_cb_add_absent_t cb_add_absent;
838 svn_editor_cb_alter_directory_t cb_alter_directory;
839 svn_editor_cb_alter_file_t cb_alter_file;
840 svn_editor_cb_alter_symlink_t cb_alter_symlink;
841 svn_editor_cb_delete_t cb_delete;
842 svn_editor_cb_copy_t cb_copy;
843 svn_editor_cb_move_t cb_move;
844 svn_editor_cb_rotate_t cb_rotate;
845 svn_editor_cb_complete_t cb_complete;
846 svn_editor_cb_abort_t cb_abort;
848 } svn_editor_cb_many_t;
850 /** Sets all the callback functions in @a editor at once, according to the
851 * callback functions stored in @a many.
852 * @a scratch_pool is used for temporary allocations (if any).
856 svn_editor_setcb_many(svn_editor_t *editor,
857 const svn_editor_cb_many_t *many,
858 apr_pool_t *scratch_pool);
863 /** These functions are called by the tree delta driver to edit the target.
867 * @defgroup svn_editor_drive Driving the editor
871 /** Drive @a editor's #svn_editor_cb_add_directory_t callback.
873 * Create a new directory at @a relpath. The immediate parent of @a relpath
874 * is expected to exist.
876 * For descriptions of @a props and @a replaces_rev, see
877 * svn_editor_add_file().
879 * A complete listing of the immediate children of @a relpath that will be
880 * added subsequently is given in @a children. @a children is an array of
881 * const char*s, each giving the basename of an immediate child. It is an
882 * error to pass NULL for @a children; use an empty array to indicate
883 * the new directory will have no children.
885 * For all restrictions on driving the editor, see #svn_editor_t.
888 svn_editor_add_directory(svn_editor_t *editor,
890 const apr_array_header_t *children,
892 svn_revnum_t replaces_rev);
894 /** Drive @a editor's #svn_editor_cb_add_file_t callback.
896 * Create a new file at @a relpath. The immediate parent of @a relpath
897 * is expected to exist.
899 * The file's contents are specified in @a contents which has a checksum
900 * matching @a checksum. Both values must be non-NULL.
902 * Set the properties of the new file to @a props, which is an
903 * apr_hash_t holding key-value pairs. Each key is a const char* of a
904 * property name, each value is a const svn_string_t*. If no properties are
905 * being set on the new file, @a props must be the empty hash. It is an
906 * error to pass NULL for @a props.
908 * If this add is expected to replace a previously existing file, symlink or
909 * directory at @a relpath, the revision number of the node to be replaced
910 * must be given in @a replaces_rev. Otherwise, @a replaces_rev must be
911 * #SVN_INVALID_REVNUM. Note: it is not allowed to call a "delete" followed
912 * by an "add" on the same path. Instead, an "add" with @a replaces_rev set
913 * accordingly MUST be used.
915 * For all restrictions on driving the editor, see #svn_editor_t.
919 svn_editor_add_file(svn_editor_t *editor,
921 const svn_checksum_t *checksum,
922 svn_stream_t *contents,
924 svn_revnum_t replaces_rev);
926 /** Drive @a editor's #svn_editor_cb_add_symlink_t callback.
928 * Create a new symbolic link at @a relpath, with a link target of @a
929 * target. The immediate parent of @a relpath is expected to exist.
931 * For descriptions of @a props and @a replaces_rev, see
932 * svn_editor_add_file().
934 * For all restrictions on driving the editor, see #svn_editor_t.
938 svn_editor_add_symlink(svn_editor_t *editor,
942 svn_revnum_t replaces_rev);
944 /** Drive @a editor's #svn_editor_cb_add_absent_t callback.
946 * Create an "absent" node of kind @a kind at @a relpath. The immediate
947 * parent of @a relpath is expected to exist.
948 * ### TODO @todo explain "absent".
949 * ### JAF: What are the allowed values of 'kind'?
951 * For a description of @a replaces_rev, see svn_editor_add_file().
953 * For all restrictions on driving the editor, see #svn_editor_t.
957 svn_editor_add_absent(svn_editor_t *editor,
959 svn_node_kind_t kind,
960 svn_revnum_t replaces_rev);
962 /** Drive @a editor's #svn_editor_cb_alter_directory_t callback.
964 * Alter the properties of the directory at @a relpath.
966 * @a revision specifies the revision at which the receiver should
967 * expect to find this node. That is, @a relpath at the start of the
968 * whole edit and @a relpath at @a revision must lie within the same
969 * node-rev (aka location history segment). This information may be used
970 * to catch an attempt to alter and out-of-date directory. If the
971 * directory does not have a corresponding revision in the repository
972 * (e.g. it has not yet been committed), then @a revision should be
973 * #SVN_INVALID_REVNUM.
975 * If any changes to the set of children will be made in the future of
976 * the edit drive, then @a children MUST specify the resulting set of
977 * children. See svn_editor_add_directory() for the format of @a children.
978 * If not changes will be made, then NULL may be specified.
980 * For a description of @a props, see svn_editor_add_file(). If no changes
981 * to the properties will be made (ie. only future changes to the set of
982 * children), then @a props may be NULL.
984 * It is an error to pass NULL for both @a children and @a props.
986 * For all restrictions on driving the editor, see #svn_editor_t.
990 svn_editor_alter_directory(svn_editor_t *editor,
992 svn_revnum_t revision,
993 const apr_array_header_t *children,
996 /** Drive @a editor's #svn_editor_cb_alter_file_t callback.
998 * Alter the properties and/or the contents of the file at @a relpath
999 * with @a revision as its expected revision. See svn_editor_alter_directory()
1000 * for more information about @a revision.
1002 * If @a props is non-NULL, then the properties will be applied.
1004 * If @a contents is non-NULL, then the stream will be copied to
1005 * the file, and its checksum must match @a checksum (which must also
1006 * be non-NULL). If @a contents is NULL, then @a checksum must also
1007 * be NULL, and no change will be applied to the file's contents.
1009 * The properties and/or the contents must be changed. It is an error to
1010 * pass NULL for @a props, @a checksum, and @a contents.
1012 * For a description of @a checksum and @a contents see
1013 * svn_editor_add_file(). This function allows @a props to be NULL, but
1014 * the parameter is otherwise described by svn_editor_add_file().
1016 * For all restrictions on driving the editor, see #svn_editor_t.
1017 * @since New in 1.8.
1020 svn_editor_alter_file(svn_editor_t *editor,
1021 const char *relpath,
1022 svn_revnum_t revision,
1024 const svn_checksum_t *checksum,
1025 svn_stream_t *contents);
1027 /** Drive @a editor's #svn_editor_cb_alter_symlink_t callback.
1029 * Alter the properties and/or the target of the symlink at @a relpath
1030 * with @a revision as its expected revision. See svn_editor_alter_directory()
1031 * for more information about @a revision.
1033 * If @a props is non-NULL, then the properties will be applied.
1035 * If @a target is non-NULL, then the symlink's target will be updated.
1037 * The properties and/or the target must be changed. It is an error to
1038 * pass NULL for @a props and @a target.
1040 * This function allows @a props to be NULL, but the parameter is
1041 * otherwise described by svn_editor_add_file().
1043 * For all restrictions on driving the editor, see #svn_editor_t.
1044 * @since New in 1.8.
1047 svn_editor_alter_symlink(svn_editor_t *editor,
1048 const char *relpath,
1049 svn_revnum_t revision,
1051 const char *target);
1053 /** Drive @a editor's #svn_editor_cb_delete_t callback.
1055 * Delete the existing node at @a relpath, expected to be identical to
1056 * revision @a revision of that path.
1058 * For all restrictions on driving the editor, see #svn_editor_t.
1059 * @since New in 1.8.
1062 svn_editor_delete(svn_editor_t *editor,
1063 const char *relpath,
1064 svn_revnum_t revision);
1066 /** Drive @a editor's #svn_editor_cb_copy_t callback.
1068 * Copy the node at @a src_relpath, expected to be identical to revision @a
1069 * src_revision of that path, to @a dst_relpath.
1071 * For a description of @a replaces_rev, see svn_editor_add_file().
1073 * @note See the general instructions on paths for this API. Since the
1074 * @a src_relpath argument must generally be able to reference any node
1075 * in the repository, the implication is that the editor's root must be
1076 * the repository root.
1078 * For all restrictions on driving the editor, see #svn_editor_t.
1079 * @since New in 1.8.
1082 svn_editor_copy(svn_editor_t *editor,
1083 const char *src_relpath,
1084 svn_revnum_t src_revision,
1085 const char *dst_relpath,
1086 svn_revnum_t replaces_rev);
1088 /** Drive @a editor's #svn_editor_cb_move_t callback.
1090 * Move the node at @a src_relpath to @a dst_relpath.
1092 * @a src_revision specifies the revision at which the receiver should
1093 * expect to find this node. That is, @a src_relpath at the start of
1094 * the whole edit and @a src_relpath at @a src_revision must lie within
1095 * the same node-rev (aka history-segment). This is just like the
1096 * revisions specified to svn_editor_delete() and svn_editor_rotate().
1098 * For a description of @a replaces_rev, see svn_editor_add_file().
1100 * ### what happens if one side of this move is not "within" the receiver's
1103 * For all restrictions on driving the editor, see #svn_editor_t.
1104 * @since New in 1.8.
1107 svn_editor_move(svn_editor_t *editor,
1108 const char *src_relpath,
1109 svn_revnum_t src_revision,
1110 const char *dst_relpath,
1111 svn_revnum_t replaces_rev);
1113 /** Drive @a editor's #svn_editor_cb_rotate_t callback.
1115 * Perform a rotation among multiple nodes in the target tree.
1117 * The @a relpaths and @a revisions arrays (pair-wise) specify nodes in the
1118 * tree which are located at a path and expected to be at a specific
1119 * revision. These nodes are simultaneously moved in a rotation pattern.
1120 * For example, the node at index 0 of @a relpaths and @a revisions will
1121 * be moved to the relpath specified at index 1 of @a relpaths. The node
1122 * at index 1 will be moved to the location at index 2. The node at index
1123 * N-1 will be moved to the relpath specified at index 0.
1125 * The simplest form of this operation is to swap nodes A and B. One may
1126 * think to move A to a temporary location T, then move B to A, then move
1127 * T to B. However, this last move violations the Once Rule by moving T
1128 * (which had already by edited by the move from A). In order to keep the
1129 * restrictions against multiple moves of a single node, the rotation
1130 * operation is needed for certain types of tree edits.
1132 * ### what happens if one of the paths of the rotation is not "within" the
1133 * ### receiver's set of paths?
1135 * For all restrictions on driving the editor, see #svn_editor_t.
1136 * @since New in 1.8.
1139 svn_editor_rotate(svn_editor_t *editor,
1140 const apr_array_header_t *relpaths,
1141 const apr_array_header_t *revisions);
1143 /** Drive @a editor's #svn_editor_cb_complete_t callback.
1145 * Send word that the edit has been completed successfully.
1147 * For all restrictions on driving the editor, see #svn_editor_t.
1148 * @since New in 1.8.
1151 svn_editor_complete(svn_editor_t *editor);
1153 /** Drive @a editor's #svn_editor_cb_abort_t callback.
1155 * Notify that the edit transmission was not successful.
1156 * ### TODO @todo Shouldn't we add a reason-for-aborting argument?
1158 * For all restrictions on driving the editor, see #svn_editor_t.
1159 * @since New in 1.8.
1162 svn_editor_abort(svn_editor_t *editor);
1168 /** A temporary API which conditionally inserts a double editor shim
1169 * into the chain of delta editors. Used for testing Editor v2.
1171 * Whether or not the shims are inserted is controlled by a compile-time
1172 * option in libsvn_delta/compat.c.
1174 * @note The use of these shims and this API will likely cause all kinds
1175 * of performance degredation. (Which is actually a moot point since they
1176 * don't even work properly yet anyway.)
1179 svn_editor__insert_shims(const svn_delta_editor_t **deditor_out,
1180 void **dedit_baton_out,
1181 const svn_delta_editor_t *deditor_in,
1182 void *dedit_baton_in,
1183 const char *repos_root,
1184 const char *base_dir,
1185 svn_delta_shim_callbacks_t *shim_callbacks,
1186 apr_pool_t *result_pool,
1187 apr_pool_t *scratch_pool);
1192 #endif /* __cplusplus */
1194 #endif /* SVN_EDITOR_H */