Package org.tmatesoft.svn.core.wc

## Class SVNCopyClient

- java.lang.Object
- - org.tmatesoft.svn.core.wc.SVNBasicClient
  - - org.tmatesoft.svn.core.wc.SVNCopyClient

-     public class SVNCopyClient
      extends SVNBasicClient

  The SVNCopyClient provides methods to perform any kinds of copying and moving that SVN supports - operating on both Working Copies (WC) and URLs.

  Copy operations allow a user to copy versioned files and directories with all their previous history in several ways.

  Supported copy operations are:

  - Working Copy to Working Copy (WC-to-WC) copying - this operation copies the source Working Copy item to the destination one and schedules the source copy for addition with history.
  - Working Copy to URL (WC-to-URL) copying - this operation commits to the repository (exactly to that repository location that is specified by URL) a copy of the Working Copy item.
  - URL to Working Copy (URL-to-WC) copying - this operation will copy the source item from the repository to the Working Copy item and schedule the source copy for addition with history.
  - URL to URL (URL-to-URL) copying - this is a fully repository-side operation, it commits a copy of the source item to a specified repository location (within the same repository, of course).

  Besides just copying SVNCopyClient also is able to move a versioned item - that is first making a copy of the source item and then scheduling the source item for deletion when operating on a Working Copy, or right committing the deletion of the source item when operating immediately on the repository.

  Supported move operations are:

  - Working Copy to Working Copy (WC-to-WC) moving - this operation copies the source Working Copy item to the destination one and schedules the source item for deletion.
  - URL to URL (URL-to-URL) moving - this is a fully repository-side operation, it commits a copy of the source item to a specified repository location and deletes the source item.

  Overloaded doCopy() methods of SVNCopyClient are similar to `'svn copy'` and `'svn move'` commands of the SVN command line client.

  Since:
    1.2
  Version:
    1.3
  Author:
    TMate Software Ltd.
  See Also:
    Examples

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SVNCopyClient​(ISVNAuthenticationManager authManager, ISVNOptions options)` | Constructs and initializes an SVNCopyClient object with the specified run-time configuration and authentication drivers.
    `SVNCopyClient​(ISVNRepositoryPool repositoryPool, ISVNOptions options)` | Constructs and initializes an SVNCopyClient object with the specified run-time configuration and repository pool object.
    `SVNCopyClient​(SvnOperationFactory of)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `doCopy​(java.io.File nestedWC)` | Converts a disjoint working copy to a copied one.
    `void` | `doCopy​(SVNCopySource[] sources, java.io.File dst, boolean isMove, boolean makeParents, boolean failWhenDstExists)` | Copies each source in `sources` to `dst`.
    `void` | `doCopy​(SVNCopySource[] sources, java.io.File dst, boolean isMove, boolean makeParents, boolean failWhenDstExists, boolean allowMixedRevisions, boolean metadataOnly)` | Copies each source in `sources` to `dst`.
    `void` | `doCopy​(SVNCopySource[] sources, java.io.File dst, boolean isMove, boolean makeParents, boolean failWhenDstExists, boolean pinExternals, java.util.Map<SvnTarget,​java.util.List<org.tmatesoft.svn.core.internal.wc.SVNExternal>> externalsToPin)` |
    `SVNCommitInfo` | `doCopy​(SVNCopySource[] sources, SVNURL dst, boolean isMove, boolean makeParents, boolean failWhenDstExists, java.lang.String commitMessage, SVNProperties revisionProperties)` | Copies each source in `sources` to `dst`.
    `SVNCommitInfo` | `doCopy​(SVNCopySource[] sources, SVNURL dst, boolean isMove, boolean makeParents, boolean failWhenDstExists, java.lang.String commitMessage, SVNProperties revisionProperties, boolean pinExternals, java.util.Map<SvnTarget,​java.util.List<org.tmatesoft.svn.core.internal.wc.SVNExternal>> externalsToPin)` |
    `ISVNCommitHandler` | `getCommitHandler()` | Returns the specified commit handler (if set) being in use or a default one (DefaultSVNCommitHandler) if no special implementations of ISVNCommitHandler were previousely provided.
    `ISVNCommitParameters` | `getCommitParameters()` | Returns commit parameters.
    `ISVNExternalsHandler` | `getExternalsHandler()` | Returns an externals handler used by this update client.
    `protected void` | `initDefaults()` |
    `void` | `setCommitHandler​(ISVNCommitHandler handler)` | Sets an implementation of ISVNCommitHandler to the commit handler that will be used during commit operations to handle commit log messages.
    `void` | `setCommitParameters​(ISVNCommitParameters parameters)` | Sets commit parameters to use.
    `void` | `setDisableLocalModificationCopying​(boolean disable)` |
    `void` | `setExternalsHandler​(ISVNExternalsHandler externalsHandler)` | Sets an externals handler to be used by this client object.

    - ### Methods inherited from class org.tmatesoft.svn.core.wc.SVNBasicClient

      `dontWC17Support, getDebugLog, getOperationsFactory, getOptions, getPathListHandler, getReposRoot, getReposRoot, isIgnoreExternals, isLeaveConflictsUnresolved, isWC17Supported, setDebugLog, setEventHandler, setEventPathPrefix, setIgnoreExternals, setLeaveConflictsUnresolved, setOptions, setPathListHandler`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SVNCopyClient

          public SVNCopyClient​(ISVNAuthenticationManager authManager,
                               ISVNOptions options)

      Constructs and initializes an SVNCopyClient object with the specified run-time configuration and authentication drivers.

      If `options` is null, then this SVNCopyClient will be using a default run-time configuration driver which takes client-side settings from the default SVN's run-time configuration area but is not able to change those settings (read more on `ISVNOptions` and `SVNWCUtil`).

      If `authManager` is null, then this SVNCopyClient will be using a default authentication and network layers driver (see `SVNWCUtil.createDefaultAuthenticationManager()`) which uses server-side settings and auth storage from the default SVN's run-time configuration area (or system properties if that area is not found).

      Parameters:
        `authManager` - an authentication and network layers driver
        `options` - a run-time configuration options driver

    - #### SVNCopyClient

          public SVNCopyClient​(ISVNRepositoryPool repositoryPool,
                               ISVNOptions options)

      Constructs and initializes an SVNCopyClient object with the specified run-time configuration and repository pool object.

      If `options` is null, then this SVNCopyClient will be using a default run-time configuration driver which takes client-side settings from the default SVN's run-time configuration area but is not able to change those settings (read more on `ISVNOptions` and `SVNWCUtil`).

      If `repositoryPool` is null, then `SVNRepositoryFactory` will be used to create `repository access objects`.
      Parameters:
        `repositoryPool` - a repository pool object
        `options` - a run-time configuration options driver

    - #### SVNCopyClient

          public SVNCopyClient​(SvnOperationFactory of)

  - ### Method Detail

    - #### initDefaults

          protected void initDefaults()

      Overrides:
        `initDefaults` in class `SVNBasicClient`

    - #### setCommitHandler

          public void setCommitHandler​(ISVNCommitHandler handler)

      Sets an implementation of ISVNCommitHandler to the commit handler that will be used during commit operations to handle commit log messages. The handler will receive a clien's log message and items (represented as SVNCommitItem objects) that will be committed. Depending on implementor's aims the initial log message can be modified (or something else) and returned back.

      If using SVNCopyClient without specifying any commit handler then a default one will be used - `DefaultSVNCommitHandler`.

      Parameters:
        `handler` - an implementor's handler that will be used to handle commit log messages
      See Also:
        `getCommitHandler()`, `SVNCommitItem`

    - #### getCommitHandler

          public ISVNCommitHandler getCommitHandler()

      Returns the specified commit handler (if set) being in use or a default one (DefaultSVNCommitHandler) if no special implementations of ISVNCommitHandler were previousely provided.
      Returns:
        the commit handler being in use or a default one
      See Also:
        `setCommitHandler(ISVNCommitHandler)`, `DefaultSVNCommitHandler`

    - #### setCommitParameters

          public void setCommitParameters​(ISVNCommitParameters parameters)

      Sets commit parameters to use.

      When no parameters are set `default` ones are used.

      Parameters:
        `parameters` - commit parameters
      See Also:
        `getCommitParameters()`

    - #### getCommitParameters

          public ISVNCommitParameters getCommitParameters()

      Returns commit parameters.

      If no user parameters were previously specified, once creates and returns `default` ones.

      Returns:
        commit parameters
      See Also:
        `setCommitParameters(ISVNCommitParameters)`

    - #### setExternalsHandler

          public void setExternalsHandler​(ISVNExternalsHandler externalsHandler)

      Sets an externals handler to be used by this client object.
      Parameters:
        `externalsHandler` - user's implementation of `ISVNExternalsHandler`
      Since:
        1.2
      See Also:
        `getExternalsHandler()`

    - #### setDisableLocalModificationCopying

          public void setDisableLocalModificationCopying​(boolean disable)

    - #### getExternalsHandler

          public ISVNExternalsHandler getExternalsHandler()

      Returns an externals handler used by this update client.

      If no user's handler is provided then `ISVNExternalsHandler.DEFAULT` is returned and used by this client object by default.

      For more information what externals handlers are for, please, refer to `ISVNExternalsHandler` and `doCopy(SVNCopySource[], SVNURL, boolean, boolean, boolean, String, SVNProperties)`.
      Returns:
        externals handler being in use
      Since:
        1.2
      See Also:
        `setExternalsHandler(ISVNExternalsHandler)`

    - #### doCopy

          public void doCopy​(SVNCopySource[] sources,
                             java.io.File dst,
                             boolean isMove,
                             boolean makeParents,
                             boolean failWhenDstExists)
                      throws SVNException

      Copies each source in `sources` to `dst`.

      If multiple `sources` are given, `dst` must be a directory, and `sources` will be copied as children of `dst`.

      Each `src` in `sources` must be files or directories under version control, or URLs of a versioned item in the repository. If `sources` has multiple items, they must be all repository URLs or all working copy paths.

      The parent of `dst` must already exist.

      If `sources` has only one item, attempts to copy it to `dst`. If `failWhenDstExists` is false and `dst` already exists, attempts to copy the item as a child of `dst`. If `failWhenDstExists` is true and `dst` already exists, throws an `SVNException` with the `SVNErrorCode.ENTRY_EXISTS` error code.

      If `sources` has multiple items, and `failWhenDstExists` is false, all `sources` are copied as children of `dst`. If any child of `dst` already exists with the same name any item in `sources`, throws an `SVNException` with the `SVNErrorCode.ENTRY_EXISTS` error code.

      If `sources` has multiple items, and `failWhenDstExists` is true, throws an `SVNException` with the `SVNErrorCode.CLIENT_MULTIPLE_SOURCES_DISALLOWED`.

      This method is just a variant of a local add operation, where `sources` are scheduled for addition as copies. No changes will happen to the repository until a commit occurs. This scheduling can be removed with `SVNWCClient.doRevert(File[], SVNDepth, Collection)`.

      If `makeParents is true, creates any non-existent parent directories also.

      If the caller's `ISVNEventHandler` is non-null, invokes it for each item added at the new location.

      Note: this routine requires repository access only when sources are urls.`
      Parameters:
        `sources` - array of copy sources
        `dst` - destination working copy path
        `isMove` - if true, then it will be a move operation (delete, then add with history)
        `makeParents` - if true, creates non-existent parent directories as well
        `failWhenDstExists` - controls whether to fail or not if `dst` already exists
      Throws:
        `SVNException`
      Since:
        1.2, SVN 1.5

    - #### doCopy

          public void doCopy​(SVNCopySource[] sources,
                             java.io.File dst,
                             boolean isMove,
                             boolean makeParents,
                             boolean failWhenDstExists,
                             boolean pinExternals,
                             java.util.Map<SvnTarget,​java.util.List<org.tmatesoft.svn.core.internal.wc.SVNExternal>> externalsToPin)
                      throws SVNException

      Throws:
        `SVNException`

    - #### doCopy

          public void doCopy​(SVNCopySource[] sources,
                             java.io.File dst,
                             boolean isMove,
                             boolean makeParents,
                             boolean failWhenDstExists,
                             boolean allowMixedRevisions,
                             boolean metadataOnly)
                      throws SVNException

      Copies each source in `sources` to `dst`.

      If multiple `sources` are given, `dst` must be a directory, and `sources` will be copied as children of `dst`.

      Each `src` in `sources` must be files or directories under version control, or URLs of a versioned item in the repository. If `sources` has multiple items, they must be all repository URLs or all working copy paths.

      The parent of `dst` must already exist.

      If `sources` has only one item, attempts to copy it to `dst`. If `failWhenDstExists` is false and `dst` already exists, attempts to copy the item as a child of `dst`. If `failWhenDstExists` is true and `dst` already exists, throws an `SVNException` with the `SVNErrorCode.ENTRY_EXISTS` error code.

      If `sources` has multiple items, and `failWhenDstExists` is false, all `sources` are copied as children of `dst`. If any child of `dst` already exists with the same name any item in `sources`, throws an `SVNException` with the `SVNErrorCode.ENTRY_EXISTS` error code.

      If `sources` has multiple items, and `failWhenDstExists` is true, throws an `SVNException` with the `SVNErrorCode.CLIENT_MULTIPLE_SOURCES_DISALLOWED`.

      This method is just a variant of a local add operation, where `sources` are scheduled for addition as copies. No changes will happen to the repository until a commit occurs. This scheduling can be removed with `SVNWCClient.doRevert(File[], SVNDepth, Collection)`.

      If `makeParents is true, creates any non-existent parent directories also.

      If the caller's `ISVNEventHandler` is non-null, invokes it for each item added at the new location.

      Note: this routine requires repository access only when sources are urls.`
      Parameters:
        `sources` - array of copy sources
        `dst` - destination working copy path
        `isMove` - if true, then it will be a move operation (delete, then add with history)
        `makeParents` - if true, creates non-existent parent directories as well
        `failWhenDstExists` - controls whether to fail or not if `dst` already exists
        `allowMixedRevisions` - allow to move directories with nodes with mixed revisions in it
        `metadataOnly` - don't copy physical files
      Throws:
        `SVNException`
      Since:
        1.8, SVN 1.8

    - #### doCopy

          public SVNCommitInfo doCopy​(SVNCopySource[] sources,
                                      SVNURL dst,
                                      boolean isMove,
                                      boolean makeParents,
                                      boolean failWhenDstExists,
                                      java.lang.String commitMessage,
                                      SVNProperties revisionProperties)
                               throws SVNException

      Copies each source in `sources` to `dst`.

      If multiple `sources` are given, `dst` must be a directory, and `sources` will be copied as children of `dst`.

      Each `src` in `sources` must be files or directories under version control, or URLs of a versioned item in the repository. If `sources` has multiple items, they must be all repository URLs or all working copy paths.

      The parent of `dst` must already exist.

      If `sources` has only one item, attempts to copy it to `dst`. If `failWhenDstExists` is false and `dst` already exists, attempts to copy the item as a child of `dst`. If `failWhenDstExists` is true and `dst` already exists, throws an `SVNException` with the `SVNErrorCode.FS_ALREADY_EXISTS` error code.

      If `sources` has multiple items, and `failWhenDstExists` is false, all `sources` are copied as children of `dst`. If any child of `dst` already exists with the same name any item in `sources`, throws an `SVNException` with the `SVNErrorCode.FS_ALREADY_EXISTS` error code.

      If `sources` has multiple items, and `failWhenDstExists` is true, throws an `SVNException` with the `SVNErrorCode.CLIENT_MULTIPLE_SOURCES_DISALLOWED`.

      `Authentication manager` (whether provided directly through the appropriate constructor or in an `ISVNRepositoryPool` instance) and `commit handler` are used to immediately attempt to commit the copy action in the repository.

      If `makeParents is true, creates any non-existent parent directories also.

      If non-null, `revisionProperties` is an object holding additional, custom revision properties ( `String` to `SVNPropertyValue` mappings) to be set on the new revision. This table cannot contain any standard Subversion properties.

      If the caller's `ISVNEventHandler` is non-null, invokes it for each item added at the new location.

      When performing a wc-to-url copy (tagging|branching from a working copy) it's possible to fix revisions of external working copies (if any) which are located within the working copy being copied. For example, imagine you have a working copy and on one of its subdirecotries you set an "svn:externals" property which does not contain a revision number. Suppose you have made a tag from your working copy and in some period of time a user checks out that tag. It could have happened that the external project has evolved since the tag creation moment and the tag version is nomore compatible with it. So, the user has a broken project since it will not compile because of the API incompatibility between the two versions of the external project: the HEAD one and the one existed in the moment of the tag creation. That is why it appears useful to fix externals revisions during a wc-to-url copy. To enable externals revision fixing a user should implement `ISVNExternalsHandler`. The user's implementation `ISVNExternalsHandler.handleExternal(File, SVNURL, SVNRevision, SVNRevision, String, SVNRevision)` method will be called on every external that will be met in the working copy. If the user's implementation returns non-null external revision, it's compared with the revisions fetched from the external definition. If they are different, the user's revision will be written in the external definition of the tag. Otherwise if the returned revision is equal to the revision from the external definition or if the user's implementation returns null for that external, it will be skipped (i.e. left as is, unprocessed).

      Note: this routine requires repository access.`
      Parameters:
        `sources` - array of copy sources
        `dst` - destination url
        `isMove` - if true, then it will be a move operation (delete, then add with history)
        `makeParents` - if true, creates non-existent parent directories as well
        `failWhenDstExists` - controls whether to fail or not if `dst` already exists
        `commitMessage` - commit log message
        `revisionProperties` - custom revision properties
      Returns:
        information about the new committed revision
      Throws:
        `SVNException`
      Since:
        1.2, SVN 1.5

    - #### doCopy

          public SVNCommitInfo doCopy​(SVNCopySource[] sources,
                                      SVNURL dst,
                                      boolean isMove,
                                      boolean makeParents,
                                      boolean failWhenDstExists,
                                      java.lang.String commitMessage,
                                      SVNProperties revisionProperties,
                                      boolean pinExternals,
                                      java.util.Map<SvnTarget,​java.util.List<org.tmatesoft.svn.core.internal.wc.SVNExternal>> externalsToPin)
                               throws SVNException

      Throws:
        `SVNException`

    - #### doCopy

          public void doCopy​(java.io.File nestedWC)
                      throws SVNException

      Converts a disjoint working copy to a copied one.

      Note: this routine does not require repository access. However if it's performed on an old format working copy where repository root urls were not written, the routine will connect to the repository to fetch the repository root url.
      Parameters:
        `nestedWC` - the root of the working copy located in another working copy (disjoint wc)
      Throws:
        `SVNException` - in the following cases:
        exception with `SVNErrorCode.UNSUPPORTED_FEATURE` error code - if `nestedWC` is either not a directory, or has no parent at all; if the current local filesystem parent of `nestedWC` is actually a child of it in the repository
        exception with `SVNErrorCode.ENTRY_EXISTS` error code - if `nestedWC` is not a disjoint working copy, i.e. there is already a versioned item under the parent path of `nestedWC`; if `nestedWC` is not in the repository yet (has got a schedule for addition flag)
        exception with `SVNErrorCode.WC_INVALID_SCHEDULE` error code - if `nestedWC` is not from the same repository as the parent directory; if the parent of `nestedWC` is scheduled for deletion; if `nestedWC` is scheduled for deletion
      Since:
        1.2.0