org.tmatesoft.svn.core.io

## Class SVNRepository

- java.lang.Object
- - org.tmatesoft.svn.core.io.SVNRepository

-     public abstract class SVNRepository
      extends java.lang.Object

  The abstract class SVNRepository provides an interface for protocol specific drivers used for direct working with a Subversion repository. SVNRepository joins all low-level API methods needed for repository access operations.

  In particular this low-level protocol driver is used by the high-level API (represented by the org.tmatesoft.svn.core.wc package) when an access to a repository is needed.

  It is important to say that before using the library it must be configured according to implimentations to be used. That is if a repository is assumed to be accessed either via the WebDAV protocol (`http://` or `https://`), or a custom svn one (`svn://` or `svn+ssh://`) or immediately on the local machine (`file:///`) a user must initialize the library in a proper way:

       //import neccessary classes
       import org.tmatesoft.svn.core.internal.io.fs.FSRepositoryFactory;
       import org.tmatesoft.svn.core.internal.io.dav.DAVRepositoryFactory;
       import org.tmatesoft.svn.core.internal.io.svn.SVNRepositoryFactoryImpl;
       import org.tmatesoft.svn.core.SVNURL;
       import org.tmatesoft.svn.core.io.SVNRepository;
       import org.tmatesoft.svn.core.io.SVNRepositoryFactory;
       import import org.tmatesoft.svn.core.wc.SVNWCUtil;
       import import org.tmatesoft.svn.core.SVNException;
       ...

       //Set up connection protocols support:
       //http:// and https://
       DAVRepositoryFactory.setup();
       //svn://, svn+xxx:// (svn+ssh:// in particular)
       SVNRepositoryFactoryImpl.setup();
       //file:///
       FSRepositoryFactory.setup();

  `svn+xxx://` can be any tunnel scheme for tunneled working with a repository. `xxx` URL scheme is looked up in the section `tunnels` of the standard Subversion `config` file.

  So, only after these setup steps the client can create http | svn | file protocol implementations of the `SVNRepository` abstract class to access the repository.

  This is a general way how a user creates an SVNRepository driver object:

       String url="http://svn.collab.net/svn/trunk";
       String name="my name";
       String password="my password";
       repository = null;
       try {
           repository = SVNRepositoryFactory.create(SVNURL.parseURIDecoded(url));
           ISVNAuthenticationManager authManager =
                        SVNWCUtil.createDefaultAuthenticationManager(name, password);
           repository.setAuthenticationManager(authManager);
           ...
       } catch (SVNException e){
           e.printStackTrace();
           System.exit(1);
       }
       //work with the repository
       ...

  SVNRepository objects are not thread-safe, we're strongly recommend you not to use one SVNRepository object from within multiple threads.

  Also methods of SVNRepository objects are not reenterable - that is, you can not call operation methods of an SVNRepository driver neither from within those handlers that are passed to some of the driver's methods, nor during committing with the help of a commit editor (until the editor's `closeEdit()` method is called).

  To authenticate a user over network SVNRepository drivers use ISVNAuthenticationManager auth drivers.

  Since:
    1.2
  Version:
    1.3
  Author:
    TMate Software Ltd.
  See Also:
    `SVNRepositoryFactory`, `ISVNAuthenticationManager`, Examples

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `INVALID_REVISION` Is used as an initialization value in cases, when revision is not defined, often represents HEAD revision
    `protected SVNURL` | `myLocation`
    `protected SVNURL` | `myRepositoryRoot`
    `protected java.lang.String` | `myRepositoryUUID`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `SVNRepository(SVNURL location, ISVNSession options)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addConnectionListener(ISVNConnectionListener listener)` Adds a connection listener to this object.
    `void` | `assertServerIsMergeInfoCapable(java.lang.String pathOrURL)` Checks that this object is connected to a mergeinfo capable repository.
    `protected static void` | `assertValidRevision(long revision)`
    `void` | `checkout(long revision, java.lang.String target, boolean recursive, ISVNEditor editor)` Checks out a directory from a repository.
    `void` | `checkout(long revision, java.lang.String target, SVNDepth depth, ISVNEditor editor)` Checks out a directory from a repository to define `depth`.
    `void` | `checkoutFiles(long revision, java.lang.String[] paths, ISVNFileCheckoutTarget fileCheckoutHandler)` Recursively checks out only files from the repository at `revision` invoking `fileCheckoutHandler` on every file received.
    `abstract SVNNodeKind` | `checkPath(java.lang.String path, long revision)` Returns the kind of an item located at the specified path in a particular revision.
    `abstract void` | `closeSession()` Closes the current session closing a socket connection used by this object.
    `void` | `diff(SVNURL url, long targetRevision, long revision, java.lang.String target, boolean ignoreAncestry, boolean recursive, boolean getContents, ISVNReporterBaton reporter, ISVNEditor editor)` Deprecated. use `diff(SVNURL, long, long, String, boolean, SVNDepth, boolean, ISVNReporterBaton, ISVNEditor)` instead
    `void` | `diff(SVNURL url, long targetRevision, long revision, java.lang.String target, boolean ignoreAncestry, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)` Deprecated. use `diff(SVNURL, long, long, String, boolean, SVNDepth, boolean, ISVNReporterBaton, ISVNEditor)` instead
    `abstract void` | `diff(SVNURL url, long targetRevision, long revision, java.lang.String target, boolean ignoreAncestry, SVNDepth depth, boolean getContents, ISVNReporterBaton reporter, ISVNEditor editor)` Asks this repository access object to 'diff' a working copy against `targetRevision`.
    `void` | `diff(SVNURL url, long revision, java.lang.String target, boolean ignoreAncestry, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)` Deprecated. use `diff(SVNURL, long, long, String, boolean, SVNDepth, boolean, ISVNReporterBaton, ISVNEditor)` instead
    `protected void` | `fireConnectionClosed()`
    `protected void` | `fireConnectionOpened()`
    `ISVNAuthenticationManager` | `getAuthenticationManager()` Returns the authentication driver registered for this object.
    `ISVNCanceller` | `getCanceller()` Returns the canceller, stored in this object.
    `ISVNEditor` | `getCommitEditor(java.lang.String logMessage, ISVNWorkspaceMediator mediator)` Gets an editor for committing changes to a repository.
    `abstract ISVNEditor` | `getCommitEditor(java.lang.String logMessage, java.util.Map locks, boolean keepLocks, ISVNWorkspaceMediator mediator)` Gets an editor for committing changes to a repository.
    `ISVNEditor` | `getCommitEditor(java.lang.String logMessage, java.util.Map locks, boolean keepLocks, SVNProperties revisionProperties, ISVNWorkspaceMediator mediator)` Returns an editor for committing changes to the repository ession, setting the revision properties from `revisionProperties` table.
    `protected abstract ISVNEditor` | `getCommitEditorInternal(java.util.Map locks, boolean keepLocks, SVNProperties revProps, ISVNWorkspaceMediator mediator)`
    `abstract long` | `getDatedRevision(java.util.Date date)` Returns the recent repository revision number for the particular moment in time - the closest one before or at the specified datestamp.
    `org.tmatesoft.svn.util.ISVNDebugLog` | `getDebugLog()` Returns the debug logger currently in use.
    `long` | `getDeletedRevision(java.lang.String path, long pegRevision, long endRevision)` Returns the revision where the path was first deleted within the inclusive revision range defined by `pegRevision` and `endRevision`.
    `protected abstract long` | `getDeletedRevisionImpl(java.lang.String path, long pegRevision, long endRevision)`
    `abstract SVNDirEntry` | `getDir(java.lang.String path, long revision, boolean includeCommitMessages, java.util.Collection entries)` Fetches the contents of a directory into the provided collection object and returns the directory entry itself.
    `java.util.Collection` | `getDir(java.lang.String path, long revision, SVNProperties properties, java.util.Collection dirEntries)` Fetches the contents and properties of a directory located at the specified path in a particular revision.
    `java.util.Collection` | `getDir(java.lang.String path, long revision, SVNProperties properties, int entryFields, java.util.Collection dirEntries)` Fetches the contents and properties of a directory located at the specified path in a particular revision with the possibility to specify fields of the entry to fetch.
    `abstract long` | `getDir(java.lang.String path, long revision, SVNProperties properties, int entryFields, ISVNDirEntryHandler handler)` Fetches the contents and/or properties of a directory located at the specified path in a particular revision with the possibility to specify fields of the entry to fetch.
    `abstract long` | `getDir(java.lang.String path, long revision, SVNProperties properties, ISVNDirEntryHandler handler)` Fetches the contents and/or properties of a directory located at the specified path in a particular revision.
    `abstract long` | `getFile(java.lang.String path, long revision, SVNProperties properties, java.io.OutputStream contents)` Fetches the contents and/or properties of a file located at the specified path in a particular revision.
    `java.util.Collection` | `getFileRevisions(java.lang.String path, java.util.Collection revisions, long sRevision, long eRevision)` Retrieves and returns interesting file revisions for the specified file.
    `int` | `getFileRevisions(java.lang.String path, long startRevision, long endRevision, boolean includeMergedRevisions, ISVNFileRevisionHandler handler)` Retrieves interesting file revisions for the specified file with possibility to include merged revisions.
    `int` | `getFileRevisions(java.lang.String path, long startRevision, long endRevision, ISVNFileRevisionHandler handler)` Retrieves interesting file revisions for the specified file.
    `protected abstract int` | `getFileRevisionsImpl(java.lang.String path, long startRevision, long endRevision, boolean includeMergedRevisions, ISVNFileRevisionHandler handler)`
    `java.lang.String` | `getFullPath(java.lang.String relativeOrRepositoryPath)` Resolves a path, relative either to the location to which this driver object is set or to the repository root directory, to a path, relative to the host.
    `abstract long` | `getLatestRevision()` Returns the number of the latest revision of the repository this driver is working with.
    `SVNURL` | `getLocation()` Returns the repository location to which this object is set.
    `java.util.Collection` | `getLocations(java.lang.String path, java.util.Collection entries, long pegRevision, long[] revisions)` Gets entry locations in time.
    `int` | `getLocations(java.lang.String path, long pegRevision, long[] revisions, ISVNLocationEntryHandler handler)` Gets entry locations in time.
    `java.util.Map` | `getLocations(java.lang.String path, java.util.Map entries, long pegRevision, long[] revisions)` Gets entry locations in time.
    `java.util.List` | `getLocationSegments(java.lang.String path, long pegRevision, long startRevision, long endRevision)` Calls `handler` for each segment in the location history of `path` in `pegRevision`, working backwards in time from `startRevision` to `endRevision`.
    `long` | `getLocationSegments(java.lang.String path, long pegRevision, long startRevision, long endRevision, ISVNLocationSegmentHandler handler)` Calls `handler` for each segment in the location history of `path` in `pegRevision`, working backwards in time from `startRevision` to `endRevision`.
    `protected abstract long` | `getLocationSegmentsImpl(java.lang.String path, long pegRevision, long startRevision, long endRevision, ISVNLocationSegmentHandler handler)`
    `protected abstract int` | `getLocationsImpl(java.lang.String path, long pegRevision, long[] revisions, ISVNLocationEntryHandler handler)`
    `abstract SVNLock` | `getLock(java.lang.String path)` Gets the lock for the file located at the specified path.
    `abstract SVNLock[]` | `getLocks(java.lang.String path)` Gets all locks on or below the `path`, that is if the repository entry (located at the `path`) is a directory then the method returns locks of all locked files (if any) in it.
    `java.util.Map` | `getMergeInfo(java.lang.String[] paths, long revision, SVNMergeInfoInheritance inherit, boolean includeDescendants)` Returns merge information for the repository entries in `paths` for paricular `revision`, if the repository supports merge-tracking information
    `protected abstract java.util.Map` | `getMergeInfoImpl(java.lang.String[] paths, long revision, SVNMergeInfoInheritance inherit, boolean includeDescendants)`
    `ISVNSession` | `getOptions()` Returns the session options object this driver is using.
    `java.lang.String` | `getRepositoryPath(java.lang.String relativePath)` Returns a path relative to the repository root directory given a path relative to the location to which this driver object is set.
    `SVNURL` | `getRepositoryRoot()` Deprecated. use #getRepositoryRoot(boolean) instead
    `SVNURL` | `getRepositoryRoot(boolean forceConnection)` Gets a repository's root directory location.
    `java.lang.String` | `getRepositoryUUID()` Deprecated. use `getRepositoryUUID(boolean)` instead
    `java.lang.String` | `getRepositoryUUID(boolean forceConnection)` Gets the Universal Unique IDentifier (UUID) of the repository this driver is created for.
    `protected static java.lang.Long` | `getRevisionObject(long revision)`
    `abstract SVNProperties` | `getRevisionProperties(long revision, SVNProperties properties)` Returns unversioned revision properties for a particular revision.
    `abstract SVNPropertyValue` | `getRevisionPropertyValue(long revision, java.lang.String propertyName)` Gets the value of an unversioned property.
    `ISVNTunnelProvider` | `getTunnelProvider()` Returns a tunnel provider.
    `abstract boolean` | `hasCapability(SVNCapability capability)` Returns `true` if the repository has specified `capability`.
    `protected static boolean` | `hasSVNProperties(SVNProperties props)`
    `abstract SVNDirEntry` | `info(java.lang.String path, long revision)` Gives information about an entry located at the specified path in a particular revision.
    `protected static boolean` | `isInvalidRevision(long revision)`
    `protected static boolean` | `isValidRevision(long revision)`
    `protected void` | `lock()`
    `protected void` | `lock(boolean force)`
    `abstract void` | `lock(java.util.Map pathsToRevisions, java.lang.String comment, boolean force, ISVNLockHandler handler)` Locks path(s) at definite revision(s).
    `java.util.Collection` | `log(java.lang.String[] targetPaths, java.util.Collection entries, long startRevision, long endRevision, boolean changedPath, boolean strictNode)` Traverses revisions history and returns a collection of log entries.
    `long` | `log(java.lang.String[] targetPaths, long startRevision, long endRevision, boolean changedPath, boolean strictNode, ISVNLogEntryHandler handler)` Traverses revisions history.
    `long` | `log(java.lang.String[] targetPaths, long startRevision, long endRevision, boolean discoverChangedPaths, boolean strictNodeHistory, long limit, boolean includeMergedRevisions, java.lang.String[] revisionProperties, ISVNLogEntryHandler handler)` Invokes `handler` on each log message from `startRevision` to `endRevision`.
    `long` | `log(java.lang.String[] targetPaths, long startRevision, long endRevision, boolean changedPath, boolean strictNode, long limit, ISVNLogEntryHandler handler)` Traverses revisions history.
    `protected abstract long` | `logImpl(java.lang.String[] targetPaths, long startRevision, long endRevision, boolean changedPath, boolean strictNode, long limit, boolean includeMergedRevisions, java.lang.String[] revisionProperties, ISVNLogEntryHandler handler)`
    `void` | `removeConnectionListener(ISVNConnectionListener listener)` Removes the specified connection listener from the collection of connection listeners held by this object.
    `abstract void` | `replay(long lowRevision, long revision, boolean sendDeltas, ISVNEditor editor)` Replays the changes from the specified revision through the given editor.
    `void` | `replayRange(long startRevision, long endRevision, long lowRevision, boolean sendDeltas, ISVNReplayHandler handler)` Replays the changes from a range of revisions between `startRevision` and `endRevision`.
    `protected abstract void` | `replayRangeImpl(long startRevision, long endRevision, long lowRevision, boolean sendDeltas, ISVNReplayHandler handler)`
    `void` | `setAuthenticationManager(ISVNAuthenticationManager authManager)` Sets an authentication driver for this object.
    `void` | `setCanceller(ISVNCanceller canceller)` Sets a canceller to this object.
    `void` | `setDebugLog(org.tmatesoft.svn.util.ISVNDebugLog log)` Sets a logger to write debug log information to.
    `void` | `setLocation(SVNURL url, boolean forceReconnect)` Sets a new repository location for this object.
    `protected void` | `setRepositoryCredentials(java.lang.String uuid, SVNURL rootURL)` Caches identification parameters (UUID, rood directory location) of the repository with which this driver is working.
    `abstract void` | `setRevisionPropertyValue(long revision, java.lang.String propertyName, SVNPropertyValue propertyValue)` Sets a revision property with the specified name to a new value.
    `void` | `setTunnelProvider(ISVNTunnelProvider tunnelProvider)` Sets a tunnel provider.
    `void` | `status(long revision, java.lang.String target, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)` Gets status of a path.
    `abstract void` | `status(long revision, java.lang.String target, SVNDepth depth, ISVNReporterBaton reporter, ISVNEditor editor)` Gets status of a path to the particular `depth` as a scope.
    `abstract void` | `testConnection()` Tries to access a repository.
    `protected void` | `unlock()`
    `abstract void` | `unlock(java.util.Map pathToTokens, boolean force, ISVNLockHandler handler)` Removes lock(s) from the file(s).
    `void` | `update(long revision, java.lang.String target, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)` Updates a path receiving changes from a repository.
    `abstract void` | `update(long revision, java.lang.String target, SVNDepth depth, boolean sendCopyFromArgs, ISVNReporterBaton reporter, ISVNEditor editor)` Updates a path receiving changes from a repository.
    `void` | `update(SVNURL url, long revision, java.lang.String target, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)` Deprecated. use `update(SVNURL, long, String, SVNDepth, ISVNReporterBaton, ISVNEditor)` instead
    `abstract void` | `update(SVNURL url, long revision, java.lang.String target, SVNDepth depth, ISVNReporterBaton reporter, ISVNEditor editor)` Asks this repository access object to 'switch' a versioned tree to a new `url`.

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

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

- - ### Field Detail

    - #### INVALID_REVISION

          public static final long INVALID_REVISION

      Is used as an initialization value in cases, when revision is not defined, often represents HEAD revision
      See Also:
        Constant Field Values

    - #### myRepositoryUUID

          protected java.lang.String myRepositoryUUID

    - #### myRepositoryRoot

          protected SVNURL myRepositoryRoot

    - #### myLocation

          protected SVNURL myLocation

  - ### Constructor Detail

    - #### SVNRepository

          protected SVNRepository(SVNURL location,
                       ISVNSession options)

  - ### Method Detail

    - #### getLocation

          public SVNURL getLocation()

      Returns the repository location to which this object is set. It may be the location that was used to create this object (see `SVNRepositoryFactory.create(SVNURL)`), or the recent one the object was set to.
      Returns:
        a repository location set for this driver
      See Also:
        `setLocation(SVNURL, boolean)`

    - #### setLocation

          public void setLocation(SVNURL url,
                         boolean forceReconnect)
                           throws SVNException

      Sets a new repository location for this object. The ability to reset an old repository location to a new one (to switch the working location) lets a developer to use the same SVNRepository object instead of creating a new object per each repository location. This advantage gives memory & coding efforts economy.

      But you can not specify a new repository location url with a protocol different from the one used for the previous (essentially, the current) repository location, since SVNRepository objects are protocol dependent.

      If a new `url` is located within the same repository, this object just switches to that `url` not closing the current session (i.e. not calling `closeSession()`).

      If either a new `url` refers to the same host (including a port number), or refers to an absolutely different host, or this object has got no repository root location cached (hasn't ever accessed a repository yet), or `forceReconnect` is true, then the current session is closed, cached repository credentials (UUID and repository root directory location ) are reset and this object is switched to a new repository location.

      Parameters:
        `url` - a new repository location url
        `forceReconnect` - if true then forces to close the current session, resets the cached repository credentials and switches this object to a new location (doesn't matter whether it's on the same host or not)
      Throws:
        `SVNException` - if the old url and a new one has got different protocols

    - #### getRepositoryUUID

          public java.lang.String getRepositoryUUID()

      Deprecated. use `getRepositoryUUID(boolean)` instead
      Returns:
        the UUID of a repository

    - #### getRepositoryUUID

          public java.lang.String getRepositoryUUID(boolean forceConnection)
                                             throws SVNException

      Gets the Universal Unique IDentifier (UUID) of the repository this driver is created for.
      Parameters:
        `forceConnection` - if true then forces this driver to test a connection - try to access a repository
      Returns:
        the UUID of a repository
      Throws:
        `SVNException` - in case the repository could not be connected
        `SVNAuthenticationException` - in case of authentication problems

    - #### getRepositoryRoot

          public SVNURL getRepositoryRoot()

      Deprecated. use #getRepositoryRoot(boolean) instead
      Returns:
        the repository root directory location url
      See Also:
        `getRepositoryRoot(boolean)`

    - #### getRepositoryRoot

          public SVNURL getRepositoryRoot(boolean forceConnection)
                                   throws SVNException

      Gets a repository's root directory location. If this driver object is switched to a different repository location during runtime (probably to an absolutely different repository, see `setLocation()`), the root directory location may be changed. This method may need to establish connection with the repository if the information on the repository's root location has not been received yet from the repository.
      Parameters:
        `forceConnection` - if true then forces this driver to test a connection - try to access a repository
      Returns:
        the repository root directory location url
      Throws:
        `SVNException` - in case the repository could not be connected
        `SVNAuthenticationException` - in case of authentication problems
      See Also:
        `testConnection()`

    - #### setAuthenticationManager

          public void setAuthenticationManager(ISVNAuthenticationManager authManager)

      Sets an authentication driver for this object. The auth driver may be implemented to retrieve cached credentials, to prompt a user for credentials or something else (actually, this is up to an implementor). Also there's a default implementation - see the `SVNWCUtil` class for more details.
      Parameters:
        `authManager` - an authentication driver to provide user credentials
      See Also:
        `getAuthenticationManager()`

    - #### getAuthenticationManager

          public ISVNAuthenticationManager getAuthenticationManager()

      Returns the authentication driver registered for this object.
      Returns:
        an authentication driver that is used by this object to authenticate a user over network

    - #### setTunnelProvider

          public void setTunnelProvider(ISVNTunnelProvider tunnelProvider)

      Sets a tunnel provider. Actually relevant only to `svn+xxx://` scheme cases. The provider is responsible for matching `xxx` to the tunnel command string.

      If one would like to have a standard Subversion behaviour (when tunnel commands are fetched from the `config` file beneath the section named `tunnels`), he should provide a default provider (default implementation of the `ISVNOptions` interface). Refer to `SVNWCUtil` class for more details on how to get a default options driver.

      Parameters:
        `tunnelProvider` - a tunnel provider
      See Also:
        `getTunnelProvider()`

    - #### getTunnelProvider

          public ISVNTunnelProvider getTunnelProvider()

      Returns a tunnel provider.
      Returns:
        a tunnel provider
      See Also:
        `setTunnelProvider(ISVNTunnelProvider)`

    - #### setCanceller

          public void setCanceller(ISVNCanceller canceller)

      Sets a canceller to this object.
      Parameters:
        `canceller` - canceller object
      Since:
        1.2.0

    - #### getCanceller

          public ISVNCanceller getCanceller()

      Returns the canceller, stored in this object.
      Returns:
        canceller object
      Since:
        1.2.0

    - #### setRepositoryCredentials

          protected void setRepositoryCredentials(java.lang.String uuid,
                                      SVNURL rootURL)

      Caches identification parameters (UUID, rood directory location) of the repository with which this driver is working.
      Parameters:
        `uuid` - the repository's Universal Unique IDentifier (UUID)
        `rootURL` - the repository's root directory location
      See Also:
        `getRepositoryRoot(boolean)`, `getRepositoryUUID(boolean)`

    - #### testConnection

          public abstract void testConnection()
                                       throws SVNException

      Tries to access a repository. Used to check if there're no problems with accessing a repository and to cache a repository UUID and root directory location.
      Throws:
        `SVNException` - if a failure occured while connecting to a repository or the user's authentication failed (see `SVNAuthenticationException`)

    - #### getLatestRevision

          public abstract long getLatestRevision()
                                          throws SVNException

      Returns the number of the latest revision of the repository this driver is working with.
      Returns:
        the latest revision number
      Throws:
        `SVNException` - if a failure occured while connecting to a repository or the user's authentication failed (see `SVNAuthenticationException`)

    - #### getDatedRevision

          public abstract long getDatedRevision(java.util.Date date)
                                         throws SVNException

      Returns the recent repository revision number for the particular moment in time - the closest one before or at the specified datestamp.

      Example: if you specify a single date without specifying a time of the day (e.g. 2002-11-27) the timestamp is assumed to 00:00:00 and the method won't return any revisions for the day you have specified but for the day just before it.

      Parameters:
        `date` - a datestamp for defining the needed moment in time
      Returns:
        the revision of the repository for that time
      Throws:
        `SVNException` - if a failure occured while connecting to a repository or the user's authentication failed (see `SVNAuthenticationException`)

    - #### getRevisionProperties

          public abstract SVNProperties getRevisionProperties(long revision,
                                            SVNProperties properties)
                                                       throws SVNException

      Returns unversioned revision properties for a particular revision. Property names (keys) are mapped to their values. You may use SVNRevisionProperty constants to retrieve property values from the map.
      Parameters:
        `revision` - a revision number
        `properties` - if not null then properties will be placed in this map, otherwise a new map will be created
      Returns:
        a map containing unversioned revision properties
      Throws:
        `SVNException` - in the following cases:
        - `revision` number is invalid
        - there's no such `revision` at all
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `SVNRevisionProperty`

    - #### setRevisionPropertyValue

          public abstract void setRevisionPropertyValue(long revision,
                                      java.lang.String propertyName,
                                      SVNPropertyValue propertyValue)
                                                 throws SVNException

      Sets a revision property with the specified name to a new value.

      NOTE: revision properties are not versioned. So, the old values may be lost forever.

      Parameters:
        `revision` - the number of the revision which property is to be changed
        `propertyName` - a revision property name
        `propertyValue` - the value of the revision property
      Throws:
        `SVNException` - in the following cases:
        - the repository is configured not to allow clients to modify revision properties (e.g. a pre-revprop-change-hook program is not found or failed)
        - `revision` is invalid or doesn't exist at all
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `SVNRevisionProperty`

    - #### getRevisionPropertyValue

          public abstract SVNPropertyValue getRevisionPropertyValue(long revision,
                                                  java.lang.String propertyName)
                                                             throws SVNException

      Gets the value of an unversioned property.
      Parameters:
        `revision` - a revision number
        `propertyName` - a property name
      Returns:
        a revision property value or null if there's no such revision property
      Throws:
        `SVNException` - in the following cases:
        - `revision` number is invalid or if there's no such `revision` at all.
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)

    - #### checkPath

          public abstract SVNNodeKind checkPath(java.lang.String path,
                              long revision)
                                         throws SVNException

      Returns the kind of an item located at the specified path in a particular revision. If the `path` does not exist under the specified `revision`, `SVNNodeKind.NONE` will be returned.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      Parameters:
        `path` - an item's path
        `revision` - a revision number
      Returns:
        the node kind for the given `path` at the given `revision`
      Throws:
        `SVNException` - if a failure occured while connecting to a repository or the user's authentication failed (see `SVNAuthenticationException`)

    - #### getFile

          public abstract long getFile(java.lang.String path,
                     long revision,
                     SVNProperties properties,
                     java.io.OutputStream contents)
                                throws SVNException

      Fetches the contents and/or properties of a file located at the specified path in a particular revision.

      If `contents` arg is not null it will be written with file contents.

      If `properties` arg is not null it will receive the properties of the file. This includes all properties: not just ones controlled by a user and stored in the repository filesystem, but also non-tweakable ones (e.g. 'wcprops', 'entryprops', etc.). Property names (keys) are mapped to property values.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      If `revision` is invalid (negative), HEAD revision will be used.

      Parameters:
        `path` - a file path
        `revision` - a file revision
        `properties` - a file properties receiver map
        `contents` - an output stream to write the file contents to
      Returns:
        the revision the file has been taken at
      Throws:
        `SVNException` - in the following cases:
        - there's no such `path` in `revision`
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)

    - #### getDir

          public abstract long getDir(java.lang.String path,
                    long revision,
                    SVNProperties properties,
                    ISVNDirEntryHandler handler)
                               throws SVNException

      Fetches the contents and/or properties of a directory located at the specified path in a particular revision.

      This method is the same as `getDir(String, long, SVNProperties, int, ISVNDirEntryHandler)` with `entryFields` parameter set to `DIRENT_ALL`.

      Parameters:
        `path` - a directory path
        `revision` - a directory revision
        `properties` - a directory properties receiver map
        `handler` - a handler to process directory entries
      Returns:
        the revision of the directory
      Throws:
        `SVNException` - in the following cases:
        - `path` not found in the specified `revision`
        - `path` is not a directory
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `getDir(String, long, boolean, Collection)`, `getDir(String, long, SVNProperties, int, Collection)`, `SVNDirEntry`

    - #### getDir

          public abstract long getDir(java.lang.String path,
                    long revision,
                    SVNProperties properties,
                    int entryFields,
                    ISVNDirEntryHandler handler)
                               throws SVNException

      Fetches the contents and/or properties of a directory located at the specified path in a particular revision with the possibility to specify fields of the entry to fetch.

      If `handler` arg is not null it will be dispatched information of each directory entry represented by an SVNDirEntry object.

      If `properties` arg is not null it will receive the properties of the file. This includes all properties: not just ones controlled by a user and stored in the repository filesystem, but also non-tweakable ones (e.g. 'wcprops', 'entryprops', etc.). Property names (keys) are mapped to property values.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      If `revision` is invalid (negative), HEAD revision will be used. NOTE: you may not invoke operation methods of this SVNRepository object from within the provided `handler`.

      Parameters:
        `path` - a directory path
        `revision` - a directory revision
        `properties` - a directory properties receiver map
        `entryFields` - a combination of fields for the entry
        `handler` - a handler to process directory entries
      Returns:
        the revision of the directory
      Throws:
        `SVNException` - in the following cases:
        - `path` not found in the specified `revision`
        - `path` is not a directory
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `getDir(String, long, boolean, Collection)`, `getDir(String, long, SVNProperties, int, Collection)`, `SVNDirEntry`

    - #### getFileRevisions

          public int getFileRevisions(java.lang.String path,
                             long startRevision,
                             long endRevision,
                             ISVNFileRevisionHandler handler)
                               throws SVNException

      Retrieves interesting file revisions for the specified file.

      A file revision is represented by an SVNFileRevision object. Each file revision is handled by the file revision handler provided. Only those revisions will be retrieved in which the file was changed. The iteration will begin at the first such revision starting from the `startRevision` and so on - up to the `endRevision`. If the method succeeds, the provided `handler` will have been invoked at least once.

      For the first interesting revision the file contents will be provided to the `handler` as a text delta against an empty file. For the following revisions, the delta will be against the fulltext contents of the previous revision.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      NOTES:

      - you may not invoke methods of this SVNRepository object from within the provided `handler`
      - this functionality is not available in pre-1.1 servers
      Parameters:
        `path` - a file path
        `startRevision` - a revision to start from
        `endRevision` - a revision to stop at
        `handler` - a handler that processes file revisions passed
      Returns:
        the number of retrieved file revisions
      Throws:
        `SVNException` - if a failure occured while connecting to a repository or the user's authentication failed (see `SVNAuthenticationException`)
      Since:
        SVN 1.1
      See Also:
        `getFileRevisions(String, Collection, long, long)`, `SVNFileRevision`

    - #### getFileRevisions

          public int getFileRevisions(java.lang.String path,
                             long startRevision,
                             long endRevision,
                             boolean includeMergedRevisions,
                             ISVNFileRevisionHandler handler)
                               throws SVNException

      Retrieves interesting file revisions for the specified file with possibility to include merged revisions.

      A file revision is represented by an SVNFileRevision object. Each file revision is handled by the file revision handler provided. The iteration will begin at the first such revision starting from the `startRevision` and so on - up to the `endRevision`. If `includeMergedRevisions` is `true`, then revisions which were result of a merge will be included as well. If the method succeeds, the provided `handler` will have been invoked at least once.

      For the first interesting revision the file contents will be provided to the `handler` as a text delta against an empty file. For the following revisions, the delta will be against the fulltext contents of the previous revision.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      NOTES:

      - you may not invoke methods of this SVNRepository object from within the provided `handler`
      - this functionality is not available in pre-1.1 servers
      Parameters:
        `path` - a file path
        `startRevision` - a revision to start from
        `endRevision` - a revision to stop at
        `includeMergedRevisions` - if is `true`, merged revisions will be returned as well
        `handler` - a handler that processes file revisions passed
      Returns:
        the number of retrieved file revisions
      Throws:
        `SVNException` - if a failure occured while connecting to a repository or the user's authentication failed (see `SVNAuthenticationException`)
      Since:
        SVNKit 1.2.0, SVN 1.5.0
      See Also:
        `getFileRevisions(String, Collection, long, long)`, `SVNFileRevision`

    - #### assertServerIsMergeInfoCapable

          public void assertServerIsMergeInfoCapable(java.lang.String pathOrURL)
                                              throws SVNException

      Checks that this object is connected to a mergeinfo capable repository.

      If the repository that this object is used to access to does not support merge-tracking, an `SVNException` is thrown with the error code `SVNErrorCode.UNSUPPORTED_FEATURE`.

      `pathOrURL` is used only in an error message. If `pathOrURL` is null, it defaults to the `location` of this object.
      Parameters:
        `pathOrURL` - path or URl string for an error message
      Throws:
        `SVNException` - exception with `SVNErrorCode.UNSUPPORTED_FEATURE` error code - if the repository does not support merge-tracking
      Since:
        1.2.0

    - #### log

          public long log(java.lang.String[] targetPaths,
                 long startRevision,
                 long endRevision,
                 boolean changedPath,
                 boolean strictNode,
                 ISVNLogEntryHandler handler)
                   throws SVNException

      Traverses revisions history. In other words, collects per revision information that includes the revision number, author, datestamp, log message and maybe a list of changed paths (optional). For each revision this information is represented by an SVNLogEntry object. Such objects are passed to the provided `handler`.

      This method invokes `handler` on each log entry from `startRevision` to `endRevision`. `startRevision` may be greater or less than `endRevision`; this just controls whether the log messages are processed in descending or ascending revision number order.

      If `startRevision` or `endRevision` is invalid, it defaults to the youngest.

      If `targetPaths` has one or more elements, then only those revisions are processed in which at least one of `targetPaths` was changed (i.e., if a file text or properties changed; if dir properties changed or an entry was added or deleted). Each path is relative to the repository location that this object is set to.

      If `changedPath` is true, then each SVNLogEntry passed to the handler will contain info about all paths changed in that revision it represents. To get them call `SVNLogEntry.getChangedPaths()` that returns a map, which keys are the changed paths and the values are SVNLogEntryPath objects. If `changedPath` is false, changed paths info will not be provided.

      If `strictNode` is true, copy history will not be traversed (if any exists) when harvesting the revision logs for each path.

      Target paths can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      NOTE: you may not invoke methods of this SVNRepository object from within the provided `handler`.

      Parameters:
        `targetPaths` - paths that mean only those revisions at which they were changed
        `startRevision` - a revision to start from
        `endRevision` - a revision to end at
        `changedPath` - if true then revision information will also include all changed paths per revision, otherwise not
        `strictNode` - if true then copy history (if any) is not to be traversed
        `handler` - a caller's handler that will be dispatched log entry objects
      Returns:
        the number of revisions traversed
      Throws:
        `SVNException` - if a failure occured while connecting to a repository or the user's authentication failed (see `SVNAuthenticationException`)
      See Also:
        `log(String[], Collection, long, long, boolean, boolean)`, `log(String[], long, long, boolean, boolean, long, ISVNLogEntryHandler)`, `ISVNLogEntryHandler`, `SVNLogEntry`, `SVNLogEntryPath`

    - #### log

          public long log(java.lang.String[] targetPaths,
                 long startRevision,
                 long endRevision,
                 boolean changedPath,
                 boolean strictNode,
                 long limit,
                 ISVNLogEntryHandler handler)
                   throws SVNException

      Traverses revisions history. In other words, collects per revision information that includes the revision number, author, datestamp, log message and maybe a list of changed paths (optional). For each revision this information is represented by an SVNLogEntry object. Such objects are passed to the provided `handler`.

      This method invokes `handler` on each log entry from `startRevision` to `endRevision`. `startRevision` may be greater or less than `endRevision`; this just controls whether the log messages are processed in descending or ascending revision number order.

      If `startRevision` or `endRevision` is invalid, it defaults to the youngest.

      If `targetPaths` has one or more elements, then only those revisions are processed in which at least one of `targetPaths` was changed (i.e., if a file text or properties changed; if dir properties changed or an entry was added or deleted). Each path can be either absolute or relative to the repository location that this object is set to.

      If `changedPath` is true, then each SVNLogEntry passed to the handler will contain info about all paths changed in that revision it represents. To get them call `SVNLogEntry.getChangedPaths()` that returns a map, which keys are the changed paths and the values are SVNLogEntryPath objects. If `changedPath` is false, changed paths info will not be provided.

      If `strictNode` is true, copy history will not be traversed (if any exists) when harvesting the revision logs for each path.

      If `limit` is > 0 then only the first `limit` log entries will be handled. Otherwise (i.e. if `limit` is 0) this number is ignored.

      Target paths can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      NOTE: you may not invoke methods of this SVNRepository object from within the provided `handler`.

      Parameters:
        `targetPaths` - paths that mean only those revisions at which they were changed
        `startRevision` - a revision to start from
        `endRevision` - a revision to end at
        `changedPath` - if true then revision information will also include all changed paths per revision, otherwise not
        `strictNode` - if true then copy history (if any) is not to be traversed
        `limit` - the maximum number of log entries to process
        `handler` - a caller's handler that will be dispatched log entry objects
      Returns:
        the number of revisions traversed
      Throws:
        `SVNException` - if a failure occured while connecting to a repository or the user's authentication failed (see `SVNAuthenticationException`)
      See Also:
        `log(String[], Collection, long, long, boolean, boolean)`, `log(String[], long, long, boolean, boolean, long, ISVNLogEntryHandler)`, `ISVNLogEntryHandler`, `SVNLogEntry`, `SVNLogEntryPath`

    - #### log

          public long log(java.lang.String[] targetPaths,
                 long startRevision,
                 long endRevision,
                 boolean discoverChangedPaths,
                 boolean strictNodeHistory,
                 long limit,
                 boolean includeMergedRevisions,
                 java.lang.String[] revisionProperties,
                 ISVNLogEntryHandler handler)
                   throws SVNException

      Invokes `handler` on each log message from `startRevision` to `endRevision`. `startRevision` may be greater or less than `endRevision`; this just controls whether the log messages are processed in descending or ascending revision number order.

      If `startRevision` or `endRevision` is invalid (`<0`), it defaults to youngest.

      If `targetPaths` is non-null and has one or more elements, then shows only revisions in which at least one of `targetPaths` was changed (i.e., if file, text or props changed; if dir, props changed or an entry was added or deleted). Each path may be either absolut (starts with '/') or relative to this object's `location`.

      If `limit` is non-zero only invokes `handler` on the first `limit` logs.

      If `discoverChangedPaths` is set, then each call to `handler` passes an `SVNLogEntry` object with non-empty `changed paths map`; the hash's keys are all the paths committed in that revision. Otherwise, each call to `handler` passes null for changed paths.

      If `strictNodeHistory` is set, copy history will not be traversed (if any exists) when harvesting the revision logs for each path.

      If `includeMergedRevisions` is set, log information for revisions which have been merged to `targetPahts` will also be returned.

      Refer to `SVNLogEntry.hasChildren()` for additional information on how to handle mergeinfo information during a log operation.

      If `revisionProperties` is null, retrieves all revprops; else, retrieves only the revprops named in the array (i.e. retrieves none if the array is empty).

      If any invocation of `handler` throws an exception, then throws that exception immediately and without wrapping it.

      Note: the caller may not invoke any repository access operations using from within `handler`.

      Note: if `targetPahts` is null or empty, the result depends on the server. Pre-1.5 servers will send nothing; 1.5 servers will effectively perform the log operation on the root of the repository. This behavior may be changed in the future to ensure consistency across all pedigrees of server.

      Note: pre-1.5 servers do not support custom revision properties retrieval; if `revisionProperties` is null or contains a revision property other than `SVNRevisionProperty.AUTHOR`, `SVNRevisionProperty.DATE`, `SVNRevisionProperty.LOG`, an exception with the `SVNErrorCode.RA_NOT_IMPLEMENTED` error code is thrown.
      Parameters:
        `targetPaths` - paths that mean only those revisions at which they were changed
        `startRevision` - a revision to start from
        `endRevision` - a revision to end at
        `discoverChangedPaths` - if true then revision information will also include all changed paths per revision, otherwise not
        `strictNodeHistory` - if true then copy history (if any) is not to be traversed
        `limit` - the maximum number of log entries to process
        `includeMergedRevisions` - whether mergeinfo information should be taken into account or not
        `revisionProperties` - revision properties to fetch with log entries
        `handler` - a caller's handler that will be dispatched log entry objects
      Returns:
        the number of revisions traversed
      Throws:
        `SVNException` - in the following cases:
        exception with `SVNErrorCode.FS_NO_SUCH_REVISION` error code - if `startRevision` or `endRevision` is a non-existent revision
        exception with `SVNErrorCode.RA_NOT_IMPLEMENTED` error code - in case of a pre-1.5 server and custom revision properties requested
      Since:
        1.2.0, New in Subversion 1.5.0

    - #### getLocations

          public int getLocations(java.lang.String path,
                         long pegRevision,
                         long[] revisions,
                         ISVNLocationEntryHandler handler)
                           throws SVNException

      Gets entry locations in time. The location of an entry in a repository may change from revision to revision. This method allows to trace entry locations in different revisions.

      For each interesting revision (taken from `revisions`) an entry location is represented by an SVNLocationEntry object which is passed to the provided `handler`. Each SVNLocationEntry object represents a repository path in a definite revision.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      NOTES:

      - you may not invoke methods of this SVNRepository object from within the provided `handler`
      - this functionality is not available in pre-1.1 servers
      Parameters:
        `path` - an item's path
        `pegRevision` - a revision in which `path` is first looked up
        `revisions` - an array of numbers of interesting revisions in which locations are looked up. If `path` doesn't exist in an interesting revision, that revision will be ignored.
        `handler` - a location entry handler that will handle all found entry locations
      Returns:
        the number of the entry locations found
      Throws:
        `SVNException` - in the following cases:
        - `path` not found in the specified `pegRevision`
        - `pegRevision` is not valid
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      Since:
        SVN 1.1
      See Also:
        `getLocations(String, Collection, long, long[])`, `getLocations(String, Map, long, long[])`, `ISVNLocationEntryHandler`, `SVNLocationEntry`

    - #### getLocationSegments

          public long getLocationSegments(java.lang.String path,
                                 long pegRevision,
                                 long startRevision,
                                 long endRevision,
                                 ISVNLocationSegmentHandler handler)
                                   throws SVNException

      Calls `handler` for each segment in the location history of `path` in `pegRevision`, working backwards in time from `startRevision` to `endRevision`.

      `endRevision` may be invalid (`<0`) to indicate that you want to trace the history of the object to its origin.

      `startRevision` may be invalid to indicate "the HEAD revision". Otherwise, `startRevision` must be younger than `endRevision` (unless `endRevision` is invalid).

      `pegRevision` may be invalid to indicate "the HEAD revision", and must evaluate to be at least as young as `startRevision`.
      Parameters:
        `path` - repository path
        `pegRevision` - revision in which `path` is valid
        `startRevision` - revision range start
        `endRevision` - revision range end
        `handler` - caller's segment handler implementation
      Returns:
        number of revisions covered by all segments found
      Throws:
        `SVNException`
      Since:
        1.2.0, New in Subversion 1.5.0

    - #### getLocationSegments

          public java.util.List getLocationSegments(java.lang.String path,
                                           long pegRevision,
                                           long startRevision,
                                           long endRevision)
                                             throws SVNException

      Calls `handler` for each segment in the location history of `path` in `pegRevision`, working backwards in time from `startRevision` to `endRevision`.

      The same as `getLocationSegments(String, long, long, long, ISVNLocationSegmentHandler)` except for this method returns a list of all the segments fetched for `path`. The list will be sorted into an ascenging order (segments with greater start revisions will be placed in the head of the list).
      Parameters:
        `path` - repository path
        `pegRevision` - revision in which `path` is valid
        `startRevision` - revision range start
        `endRevision` - revision range end
      Returns:
        number of revisions covered by all segments found
      Throws:
        `SVNException`
      Since:
        1.2.0, New in Subversion 1.5.0

    - #### getFileRevisions

          public java.util.Collection getFileRevisions(java.lang.String path,
                                              java.util.Collection revisions,
                                              long sRevision,
                                              long eRevision)
                                                throws SVNException

      Retrieves and returns interesting file revisions for the specified file.

      A file revision is represented by an SVNFileRevision object. Only those revisions will be retrieved in which the file was changed. The iteration will begin at the first such revision starting from the `startRevision` and so on - up to the `endRevision`.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      NOTE: this functionality is not available in pre-1.1 servers

      Parameters:
        `path` - a file path
        `revisions` - if not null this collection will receive all the fetched file revisions
        `sRevision` - a revision to start from
        `eRevision` - a revision to stop at
      Returns:
        a collection that keeps file revisions - `SVNFileRevision` instances
      Throws:
        `SVNException` - if a failure occured while connecting to a repository or the user's authentication failed (see `SVNAuthenticationException`)
      Since:
        SVN 1.1
      See Also:
        `getFileRevisions(String, long, long, ISVNFileRevisionHandler)`, `SVNFileRevision`

    - #### getDir

          public java.util.Collection getDir(java.lang.String path,
                                    long revision,
                                    SVNProperties properties,
                                    java.util.Collection dirEntries)
                                      throws SVNException

      Fetches the contents and properties of a directory located at the specified path in a particular revision. Information of each directory entry is represented by a single SVNDirEntry object.

      This method is the same as `getDir(String, long, SVNProperties, int, Collection)` with `entryFields` parameter set to `DIRENT_ALL`.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      Parameters:
        `path` - a directory path
        `revision` - a revision number
        `properties` - if not null then all directory properties (including non-tweakable ones) will be put into this map (where keys are property names and mappings are property values)
        `dirEntries` - if not null then this collection receives fetched dir entries (SVNDirEntry objects)
      Returns:
        a collection containing fetched directory entries (SVNDirEntry objects)
      Throws:
        `SVNException` - in the following cases:
        - `path` not found in the specified `revision`
        - `path` is not a directory
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `getDir(String, long, SVNProperties, int, Collection)`, `getDir(String, long, boolean, Collection)`, `SVNDirEntry`

    - #### getDir

          public java.util.Collection getDir(java.lang.String path,
                                    long revision,
                                    SVNProperties properties,
                                    int entryFields,
                                    java.util.Collection dirEntries)
                                      throws SVNException

      Fetches the contents and properties of a directory located at the specified path in a particular revision with the possibility to specify fields of the entry to fetch. Information of each directory entry is represented by a single SVNDirEntry object.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      Parameters:
        `path` - a directory path
        `revision` - a revision number
        `properties` - if not null then all directory properties (including non-tweakable ones) will be put into this map (where keys are property names and mappings are property values)
        `entryFields` - a combination of fields for the entry
        `dirEntries` - if not null then this collection receives fetched dir entries (SVNDirEntry objects)
      Returns:
        a collection containing fetched directory entries (SVNDirEntry objects)
      Throws:
        `SVNException` - in the following cases:
        - `path` not found in the specified `revision`
        - `path` is not a directory
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `getDir(String, long, SVNProperties, int, Collection)`, `getDir(String, long, boolean, Collection)`, `SVNDirEntry`

    - #### getDir

          public abstract SVNDirEntry getDir(java.lang.String path,
                           long revision,
                           boolean includeCommitMessages,
                           java.util.Collection entries)
                                      throws SVNException

      Fetches the contents of a directory into the provided collection object and returns the directory entry itself.

      If `entries` arg is not null it receives the directory entries. Information of each directory entry is represented by an SVNDirEntry object.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      Parameters:
        `path` - a directory path
        `revision` - a revision number
        `includeCommitMessages` - if true then dir entries (SVNDirEntry objects) will be supplied with commit log messages, otherwise not
        `entries` - a collection that receives fetched dir entries
      Returns:
        the directory entry itself which contents are fetched into `entries`
      Throws:
        `SVNException` - in the following cases:
        - `path` not found in the specified `revision`
        - `path` is not a directory
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `getDir(String, long, SVNProperties, ISVNDirEntryHandler)`, `getDir(String, long, SVNProperties, Collection)`, `SVNDirEntry`

    - #### log

          public java.util.Collection log(java.lang.String[] targetPaths,
                                 java.util.Collection entries,
                                 long startRevision,
                                 long endRevision,
                                 boolean changedPath,
                                 boolean strictNode)
                                   throws SVNException

      Traverses revisions history and returns a collection of log entries. In other words, collects per revision information that includes the revision number, author, datestamp, log message and maybe a list of changed paths (optional). For each revision this information is represented by an SVNLogEntry. object.

      `startRevision` may be greater or less than `endRevision`; this just controls whether the log messages are processed in descending or ascending revision number order.

      If `startRevision` or `endRevision` is invalid, it defaults to the youngest.

      If `targetPaths` has one or more elements, then only those revisions are processed in which at least one of `targetPaths` was changed (i.e., if a file text or properties changed; if dir properties changed or an entry was added or deleted). Each path is relative to the repository location that this object is set to.

      If `changedPath` is true, then each SVNLogEntry object is supplied with info about all paths changed in that revision it represents. To get them call `SVNLogEntry.getChangedPaths()` that returns a map, which keys are the changed paths and the mappings are SVNLogEntryPath objects. If `changedPath` is false, changed paths info will not be provided.

      If `strictNode` is true, copy history will not be traversed (if any exists) when harvesting the revision logs for each path.

      Target paths can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      Parameters:
        `targetPaths` - paths that mean only those revisions at which they were changed
        `entries` - if not null then this collection will receive log entries
        `startRevision` - a revision to start from
        `endRevision` - a revision to end at
        `changedPath` - if true then revision information will also include all changed paths per revision, otherwise not
        `strictNode` - if true then copy history (if any) is not to be traversed
      Returns:
        a collection with log entries
      Throws:
        `SVNException` - if a failure occured while connecting to a repository or the user's authentication failed (see `SVNAuthenticationException`)
      See Also:
        `log(String[], long, long, boolean, boolean, ISVNLogEntryHandler)`, `log(String[], long, long, boolean, boolean, long, ISVNLogEntryHandler)`, `ISVNLogEntryHandler`, `SVNLogEntry`, `SVNLogEntryPath`

    - #### getLocations

          public java.util.Collection getLocations(java.lang.String path,
                                          java.util.Collection entries,
                                          long pegRevision,
                                          long[] revisions)
                                            throws SVNException

      Gets entry locations in time. The location of an entry in a repository may change from revision to revision. This method allows to trace entry locations in different revisions.

      For each interesting revision (taken from `revisions`) an entry location is represented by an SVNLocationEntry object. Each SVNLocationEntry object represents a repository path in a definite revision.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      NOTE: this functionality is not available in pre-1.1 servers

      Parameters:
        `path` - an item's path
        `entries` - if not null then this collection object receives entry locations
        `pegRevision` - a revision in which `path` is first looked up
        `revisions` - an array of numbers of interesting revisions in which locations are looked up. If `path` doesn't exist in an interesting revision, that revision will be ignored.
      Returns:
        a collection with retrieved entry locations
      Throws:
        `SVNException` - in the following cases:
        - `path` not found in the specified `pegRevision`
        - `pegRevision` is not valid
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      Since:
        SVN 1.1
      See Also:
        `getLocations(String, long, long[], ISVNLocationEntryHandler)`, `getLocations(String, Map, long, long[])`, `SVNLocationEntry`, `ISVNLocationEntryHandler`

    - #### getLocations

          public java.util.Map getLocations(java.lang.String path,
                                   java.util.Map entries,
                                   long pegRevision,
                                   long[] revisions)
                                     throws SVNException

      Gets entry locations in time. The location of an entry in a repository may change from revision to revision. This method allows to trace entry locations in different revisions.

      For each interesting revision (taken from `revisions`) an entry location is represented by an SVNLocationEntry object. Each SVNLocationEntry object represents a repository path in a definite revision.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      NOTE: this functionality is not available in pre-1.1 servers

      Parameters:
        `path` - an item's path
        `entries` - if not null then this map object receives entry locations (which keys are revision numbers as Longs and mappings are entry locations objects)
        `pegRevision` - a revision in which `path` is first looked up
        `revisions` - an array of numbers of interesting revisions in which locations are looked up. If `path` doesn't exist in an interesting revision, that revision will be ignored.
      Returns:
        a map (which keys are revision numbers as Longs and mappings are entry locations objects) with collected entry locations
      Throws:
        `SVNException` - in the following cases:
        - `path` not found in the specified `pegRevision`
        - `pegRevision` is not valid
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      Since:
        SVN 1.1
      See Also:
        `getLocations(String, long, long[], ISVNLocationEntryHandler)`, `getLocations(String, Collection, long, long[])`, `SVNLocationEntry`, `ISVNLocationEntryHandler`

    - #### diff

          public void diff(SVNURL url,
                  long targetRevision,
                  long revision,
                  java.lang.String target,
                  boolean ignoreAncestry,
                  boolean recursive,
                  boolean getContents,
                  ISVNReporterBaton reporter,
                  ISVNEditor editor)
                    throws SVNException

      Deprecated. use `diff(SVNURL, long, long, String, boolean, SVNDepth, boolean, ISVNReporterBaton, ISVNEditor)` instead
      Calculates the differences between two items.

      `target` is the name (one-level path component) of an entry that will restrict the scope of the diff operation to this entry. In other words `target` is a child entry of the directory represented by the repository location to which this object is set. For example, if we have something like `"/dirA/dirB"` in a repository, then this object's repository location may be set to `"svn://host:port/path/to/repos/dirA"`, and `target` may be `"dirB"`.

      If `target` is null or empty (`""`) then the scope of the diff operation is the repository location to which this object is set.

      The `reporter` is used to describe the state of the target item(s) (i.e. items' revision numbers). All the paths described by the `reporter` should be relative to the repository location to which this object is set.

      After that the `editor` is used to carry out all the work on evaluating differences against `url`. This `editor` contains knowledge of where the change will begin (when `ISVNEditor.openRoot()` is called).

      If `ignoreAncestry` is false then the ancestry of the paths being diffed is taken into consideration - they are treated as related. In this case, for example, if calculating differences between two files with identical contents but different ancestry, the entire contents of the target file is considered as having been removed and added again.

      If `ignoreAncestry` is true then the two paths are merely compared ignoring the ancestry.

      NOTE: you may not invoke methods of this SVNRepository object from within the provided `reporter` and `editor`.

      This method is analogous to `diff(url, targetRevision, revision, target, ignoreAncestry, SVNDepth.fromRecurse(recursive), getContents, reporter, editor)`.
      Parameters:
        `url` - a repository location of the entry against which differences are calculated
        `targetRevision` - a revision number of the entry located at the specified `url`; defaults to the latest revision (HEAD) if this arg is invalid
        `revision` - a revision number of the repository location to which this driver object is set
        `target` - a target entry name (optional)
        `ignoreAncestry` - if true then the ancestry of the two entries to be diffed is ignored, otherwise not
        `recursive` - if true and the diff scope is a directory, descends recursively, otherwise not
        `getContents` - if false contents (diff windows) will not be sent to the editor.
        `reporter` - a caller's reporter
        `editor` - a caller's editor
      Throws:
        `SVNException` - in the following cases:
        - `url` not found neither in the specified `revision` nor in the HEAD revision
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)

    - #### diff

          public abstract void diff(SVNURL url,
                  long targetRevision,
                  long revision,
                  java.lang.String target,
                  boolean ignoreAncestry,
                  SVNDepth depth,
                  boolean getContents,
                  ISVNReporterBaton reporter,
                  ISVNEditor editor)
                             throws SVNException

      Asks this repository access object to 'diff' a working copy against `targetRevision`.

      Note: this method cannot be used to diff a single file, only a directory. See the `update(SVNURL, long, String, SVNDepth, ISVNReporterBaton, ISVNEditor)` method for more details.

      The client initially provides an `editor`; this editor contains knowledge of where the common diff root is in the working copy (when `ISVNEditor.openRoot(long)` is called).

      In return, the client receives a `ISVNReporter` object in his `ISVNReporterBaton` implementation. The client then describes its working copy by making calls into the reporter object.

      When finished, the client calls `ISVNReporter.finishReport()`. This `SVNRepository` object then does a complete drive of `editor`, ending with `ISVNEditor.closeEdit()`, to transmit the diff.

      `target` is an optional single path component that will restrict the scope of things affected by the switch to an entry in the directory represented by the `location` of this object, or null if the entire directory is meant to be switched.

      The working copy will be diffed against `url` as it exists in revision `targeRevision`, or as it is in HEAD if `targetRevision` is invalid (`<0`).

      Use `ignoreAncestry` to control whether or not items being diffed will be checked for relatedness first. Unrelated items are typically transmitted to the editor as a deletion of one thing and the addition of another, but if this flag is true, unrelated items will be diffed as if they were related.

      Diffs only as deeply as `depth` indicates.

      The caller may not perform any repository access operations using this `SVNRepository` object before finishing the report, and may not perform any repository access operations using this `SVNRepository` object from within the editing operations of `editor`.

      `getContents` instructs the driver of the `editor` to enable the generation of text deltas. If `getContents` is false the `editor`'s `ISVNDeltaConsumer.textDeltaChunk(String, SVNDiffWindow)` method will be called once with `SVNDiffWindow.EMPTY`.

      Note: the reporter provided by this function does NOT supply copy-from information to the diff editor callbacks.

      Note: in order to prevent pre-1.5 servers from doing more work than needed, and sending too much data back, a pre-1.5 'recurse' directive may be sent to the server, based on `depth`.
      Parameters:
        `url` - a repository location of the entry against which differences are calculated
        `targetRevision` - a revision number of the entry located at the specified `url`; defaults to the latest revision (HEAD) if this arg is invalid
        `revision` - a revision number of the repository location to which this driver object is set
        `target` - a target entry name (optional)
        `ignoreAncestry` - if true then the ancestry of the two entries to be diffed is ignored, otherwise not
        `depth` - tree depth to process
        `getContents` - if false contents (diff windows) will not be sent to the editor
        `reporter` - a caller's reporter
        `editor` - a caller's editor
      Throws:
        `SVNException` - in the following cases:
        - `url` not found neither in the specified `revision` nor in the HEAD revision
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      Since:
        1.2.0, New in Subversion 1.5.0

    - #### diff

          public void diff(SVNURL url,
                  long targetRevision,
                  long revision,
                  java.lang.String target,
                  boolean ignoreAncestry,
                  boolean recursive,
                  ISVNReporterBaton reporter,
                  ISVNEditor editor)
                    throws SVNException

      Deprecated. use `diff(SVNURL, long, long, String, boolean, SVNDepth, boolean, ISVNReporterBaton, ISVNEditor)` instead
      This method is analogous to `diff(SVNURL, long, long, String, boolean, boolean, boolean, ISVNReporterBaton, ISVNEditor)`.
      Parameters:
        `url` -
        `targetRevision` -
        `revision` -
        `target` -
        `ignoreAncestry` -
        `recursive` -
        `reporter` -
        `editor` -
      Throws:
        `SVNException`

    - #### diff

          public void diff(SVNURL url,
                  long revision,
                  java.lang.String target,
                  boolean ignoreAncestry,
                  boolean recursive,
                  ISVNReporterBaton reporter,
                  ISVNEditor editor)
                    throws SVNException

      Deprecated. use `diff(SVNURL, long, long, String, boolean, SVNDepth, boolean, ISVNReporterBaton, ISVNEditor)` instead
      Calculates the differences between two items.

      `target` is the name (one-level path component) of an entry that will restrict the scope of the diff operation to this entry. In other words `target` is a child entry of the directory represented by the repository location to which this object is set. For example, if we have something like `"/dirA/dirB"` in a repository, then this object's repository location may be set to `"svn://host:port/path/to/repos/dirA"`, and `target` may be `"dirB"`.

      If `target` is null or empty (`""`) then the scope of the diff operation is the repository location to which this object is set.

      The `reporter` is used to describe the state of the target item(s) (i.e. items' revision numbers). All the paths described by the `reporter` should be relative to the repository location to which this object is set.

      After that the `editor` is used to carry out all the work on evaluating differences against `url`. This `editor` contains knowledge of where the change will begin (when `ISVNEditor.openRoot()` is called).

      If `ignoreAncestry` is false then the ancestry of the paths being diffed is taken into consideration - they are treated as related. In this case, for example, if calculating differences between two files with identical contents but different ancestry, the entire contents of the target file is considered as having been removed and added again.

      If `ignoreAncestry` is true then the two paths are merely compared ignoring the ancestry.

      NOTE: you may not invoke methods of this SVNRepository object from within the provided `reporter` and `editor`.

      This method is analogous to `diff(url, revision, revision, target, ignoreAncestry, SVNDepth.fromRecurse(recursive), true, reporter, editor)`.
      Parameters:
        `url` - a repository location of the entry against which differences are calculated
        `revision` - a revision number of the repository location to which this driver object is set
        `target` - a target entry name (optional)
        `ignoreAncestry` - if true then the ancestry of the two entries to be diffed is ignored, otherwise not
        `recursive` - if true and the diff scope is a directory, descends recursively, otherwise not
        `reporter` - a caller's reporter
        `editor` - a caller's editor
      Throws:
        `SVNException` - in the following cases:
        - `url` not found neither in the specified `revision` nor in the HEAD revision
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)

    - #### update

          public void update(SVNURL url,
                    long revision,
                    java.lang.String target,
                    boolean recursive,
                    ISVNReporterBaton reporter,
                    ISVNEditor editor)
                      throws SVNException

      Deprecated. use `update(SVNURL, long, String, SVNDepth, ISVNReporterBaton, ISVNEditor)` instead
      Updates a path switching it to a new repository location.

      Updates a path as it's described for the `update()` method using the provided `reporter` and `editor`, and switching it to a new repository location.

      NOTE: you may not invoke methods of this SVNRepository object from within the provided `reporter` and `editor`.

      Parameters:
        `url` - a new location in the repository to switch to
        `revision` - a desired revision to make update to; defaults to the latest revision (HEAD)
        `target` - an entry name (optional)
        `recursive` - if true and the switch scope is a directory, descends recursively, otherwise not
        `reporter` - a caller's reporter
        `editor` - a caller's editor
      Throws:
        `SVNException` - in the following cases:
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)

    - #### update

          public abstract void update(SVNURL url,
                    long revision,
                    java.lang.String target,
                    SVNDepth depth,
                    ISVNReporterBaton reporter,
                    ISVNEditor editor)
                               throws SVNException

      Asks this repository access object to 'switch' a versioned tree to a new `url`.

      The client initially provides an `editor`; this editor contains knowledge of where the change will begin in the working copy (`ISVNEditor.openRoot(long)` is called).

      In return, the client receives a `ISVNReporter` object in his `ISVNReporterBaton` implementation. The client then describes its working copy by making calls into the reporter object.

      When finished, the client calls `ISVNReporter.finishReport()`. This `SVNRepository` object then does a complete drive of `editor`, ending with `ISVNEditor.closeEdit()`, to switch the working copy.

      `target` is an optional single path component that will restrict the scope of things affected by the switch to an entry in the directory represented by the `location` of this object, or null if the entire directory is meant to be switched.

      Switches the target only as deeply as `depth` indicates.

      The local tree will be switched to `revision`, or the HEAD revision if this arg is invalid.

      The caller may not perform any repository access operations using this `SVNRepository` object before finishing the report, and may not perform any repository access operations using this `SVNRepository` object from within the editing operations of `editor`.

      Note: the reporter provided by this function does NOT supply copy-from information to the diff editor callbacks.

      Note: in order to prevent pre-1.5 servers from doing more work than needed, and sending too much data back, a pre-1.5 'recurse' directive may be sent to the server, based on `depth`.
      Parameters:
        `url` - a new location in the repository to switch to
        `revision` - a desired revision to make update to; defaults to the latest revision (HEAD)
        `target` - an entry name (optional)
        `depth` - the depth for update operation
        `reporter` - a caller's reporter
        `editor` - a caller's editor
      Throws:
        `SVNException`
      Since:
        1.2.0, New in Subversion 1.5.0
      See Also:
        `ISVNReporterBaton`, `ISVNReporter`, `ISVNEditor`, Using ISVNReporter/ISVNEditor in update-related operations

    - #### update

          public void update(long revision,
                    java.lang.String target,
                    boolean recursive,
                    ISVNReporterBaton reporter,
                    ISVNEditor editor)
                      throws SVNException

      Updates a path receiving changes from a repository.

      `target` is the name (one-level path component) of an entry that will restrict the scope of the update to this entry. In other words `target` is a child entry of the directory represented by the repository location to which this object is set. For example, if we have something like `"/dirA/dirB"` in a repository, then this object's repository location may be set to `"svn://host:port/path/to/repos/dirA"`, and `target` may be `"dirB"`.

      If `target` is null or empty (`""`) then the scope of the update operation is the repository location to which this object is set.

      The `reporter` is used to describe the state of the local item(s) (i.e. items' revision numbers, deleted, switched items). All the paths described by the `reporter` should be relative to the repository location to which this object is set.

      After that the `editor` is used to carry out all the work on updating. This `editor` contains knowledge of where the change will begin (when `ISVNEditor.openRoot()` is called).

      NOTE: you may not invoke methods of this SVNRepository object from within the provided `reporter` and `editor`.

      Parameters:
        `revision` - a desired revision to make update to; defaults to the latest revision (HEAD)
        `target` - an entry name (optional)
        `recursive` - if true and the update scope is a directory, descends recursively, otherwise not
        `reporter` - a caller's reporter
        `editor` - a caller's editor
      Throws:
        `SVNException` - in the following cases:
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `update(SVNURL, long, String, boolean, ISVNReporterBaton, ISVNEditor)`, `ISVNReporterBaton`, `ISVNReporter`, `ISVNEditor`, Using ISVNReporter/ISVNEditor in update-related operations

    - #### update

          public abstract void update(long revision,
                    java.lang.String target,
                    SVNDepth depth,
                    boolean sendCopyFromArgs,
                    ISVNReporterBaton reporter,
                    ISVNEditor editor)
                               throws SVNException

      Updates a path receiving changes from a repository.

      `target` is the name (one-level path component) of an entry that will restrict the scope of the update to this entry. In other words `target` is a child entry of the directory represented by the repository location to which this object is set. For example, if we have something like `"/dirA/dirB"` in a repository, then this object's repository location may be set to `"svn://host:port/path/to/repos/dirA"`, and `target` may be `"dirB"`.

      If `target` is null or empty (`""`) then the scope of the update operation is the repository location to which this object is set.

      The `reporter` is used to describe the state of the local item(s) (i.e. items' revision numbers, deleted, switched items). All the paths described by the `reporter` should be relative to the repository location to which this object is set.

      After that the `editor` is used to carry out all the work on updating. This `editor` contains knowledge of where the change will begin (when `ISVNEditor.openRoot()` is called).

      NOTE: you may not invoke methods of this SVNRepository object from within the provided `reporter` and `editor`.

      Parameters:
        `revision` - a desired revision to make update to; defaults to the latest revision (HEAD)
        `target` - an entry name (optional)
        `depth` - a depth for update operation, determines the scope of the update
        `sendCopyFromArgs` -
        `reporter` - a caller's reporter
        `editor` - a caller's editor
      Throws:
        `SVNException` - in case the repository could not be connected
        `SVNAuthenticationException` - in case of authentication problems
      See Also:
        `update(long, String, boolean, ISVNReporterBaton, ISVNEditor)`, `ISVNReporterBaton`, `ISVNReporter`, `ISVNEditor`, Using ISVNReporter/ISVNEditor in update-related operations

    - #### status

          public void status(long revision,
                    java.lang.String target,
                    boolean recursive,
                    ISVNReporterBaton reporter,
                    ISVNEditor editor)
                      throws SVNException

      Gets status of a path.

      `target` is the name (one-level path component) of an entry that will restrict the scope of the status to this entry. In other words `target` is a child entry of the directory represented by the repository location to which this object is set. For example, if we have something like `"/dirA/dirB"` in a repository, then this object's repository location may be set to `"svn://host:port/path/to/repos/dirA"`, and `target` may be `"dirB"`.

      If `target` is null or empty (`""`) then the scope of the update operation is the repository location to which this object is set.

      The `reporter` is used to describe the state of the local item(s) (i.e. items' revision numbers, deleted, switched items). All the paths described by the `reporter` should be relative to the repository location to which this object is set.

      After that the `editor` is used to carry out all the work on performing status. This `editor` contains knowledge of where the change will begin (when `ISVNEditor.openRoot()` is called).

      NOTE: you may not invoke methods of this SVNRepository object from within the provided `reporter` and `editor`.

      Parameters:
        `revision` - a desired revision to get status against; defaults to the latest revision (HEAD)
        `target` - an entry name (optional)
        `recursive` - if true and the status scope is a directory, descends recursively, otherwise not
        `reporter` - a client's reporter-baton
        `editor` - a client's status editor
      Throws:
        `SVNException` - in the following cases:
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `ISVNReporterBaton`, `ISVNEditor`

    - #### status

          public abstract void status(long revision,
                    java.lang.String target,
                    SVNDepth depth,
                    ISVNReporterBaton reporter,
                    ISVNEditor editor)
                               throws SVNException

      Gets status of a path to the particular `depth` as a scope. `status(long, String, boolean, ISVNReporterBaton, ISVNEditor)`
      Parameters:
        `revision` - a desired revision to get status against; defaults to the latest revision (HEAD)
        `target` - an entry name (optional)
        `depth` - defines the status scope
        `reporter` - a client's reporter-baton
        `editor` - a client's status editor
      Throws:
        `SVNException` - in the following cases:
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `status(long, String, boolean, ISVNReporterBaton, ISVNEditor)`, `ISVNReporterBaton`, `ISVNEditor`

    - #### checkout

          public void checkout(long revision,
                      java.lang.String target,
                      boolean recursive,
                      ISVNEditor editor)
                        throws SVNException

      Checks out a directory from a repository.

      `target` is the name (one-level path component) of an entry that will restrict the scope of the checkout to this entry. In other words `target` is a child entry of the directory represented by the repository location to which this object is set. For example, if we have something like `"/dirA/dirB"` in a repository, then this object's repository location may be set to `"svn://host:port/path/to/repos/dirA"`, and `target` may be `"dirB"`.

      If `target` is null or empty (`""`) then the scope of the checkout operation is the repository location to which this object is set.

      The provided `editor` is used to carry out all the work on building a local tree of dirs and files being checked out.

      NOTE: you may not invoke methods of this SVNRepository object from within the provided `editor`.

      Parameters:
        `revision` - a desired revision of a dir to check out; defaults to the latest revision (HEAD)
        `target` - an entry name (optional)
        `recursive` - if true and the checkout scope is a directory, descends recursively, otherwise not
        `editor` - a caller's checkout editor
      Throws:
        `SVNException` - in the following cases:
        - the checkout scope is not a directory (only dirs can be checked out)
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `update(long, String, boolean, ISVNReporterBaton, ISVNEditor)`, `ISVNEditor`

    - #### checkout

          public void checkout(long revision,
                      java.lang.String target,
                      SVNDepth depth,
                      ISVNEditor editor)
                        throws SVNException

      Checks out a directory from a repository to define `depth`.

      `target` is the name (one-level path component) of an entry that will restrict the scope of the checkout to this entry. In other words `target` is a child entry of the directory represented by the repository location to which this object is set. For example, if we have something like `"/dirA/dirB"` in a repository, then this object's repository location may be set to `"svn://host:port/path/to/repos/dirA"`, and `target` may be `"dirB"`.

      If `target` is null or empty (`""`) then the scope of the checkout operation is the repository location to which this object is set.

      The provided `editor` is used to carry out all the work on building a local tree of dirs and files being checked out.

      NOTE: you may not invoke methods of this SVNRepository object from within the provided `editor`.

      Parameters:
        `revision` - a desired revision of a dir to check out; defaults to the latest revision (HEAD)
        `target` - an entry name (optional)
        `depth` - the checkout operation scope
        `editor` - a caller's checkout editor
      Throws:
        `SVNException` - in the following cases:
        - the checkout scope is not a directory (only dirs can be checked out)
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `update(long, String, SVNDepth, boolean, ISVNReporterBaton, ISVNEditor)`, `ISVNEditor`

    - #### checkoutFiles

          public void checkoutFiles(long revision,
                           java.lang.String[] paths,
                           ISVNFileCheckoutTarget fileCheckoutHandler)
                             throws SVNException

      Recursively checks out only files from the repository at `revision` invoking `fileCheckoutHandler` on every file received.

      Instead of multiple calls to `getFileRevisions(String, long, long, boolean, ISVNFileRevisionHandler)` which lead to multiple requests to the repository server a user may use this method to get all interesting files.

      If `paths` is not null and not empty, checks out only those `paths`. It means if a path is from `paths` and is a file - checks out that file; if a directory - checks out every file under the directory and down the tree.

      Otherwise if `paths` is null or empty, checks out files from the entire tree under this object's `getLocation()`.

      `paths` does not have to be sorted; it will be sorted automatically.
      Parameters:
        `revision` - revision of files to checkout
        `paths` - paths to check out
        `fileCheckoutHandler` - caller's file data receiver
      Throws:
        `SVNException`
      Since:
        1.2.0

    - #### replay

          public abstract void replay(long lowRevision,
                    long revision,
                    boolean sendDeltas,
                    ISVNEditor editor)
                               throws SVNException

      Replays the changes from the specified revision through the given editor.

      Changes will be limited to those that occur under a session's URL, and the server will assume that the client has no knowledge of revisions prior to a `lowRevision`. These two limiting factors define the portion of the tree that the server will assume the client already has knowledge of, and thus any copies of data from outside that part of the tree will be sent in their entirety, not as simple copies or deltas against a previous version.

      If `sendDeltas` is true, the actual text and property changes in the revision will be sent, otherwise no text deltas and null property changes will be sent instead.

      If `lowRevision` is invalid, it defaults to 0.

      Parameters:
        `lowRevision` - a low revision point beyond which a client has no knowledge of paths history
        `revision` - a revision to replay
        `sendDeltas` - controls whether text and property changes are to be sent
        `editor` - a commit editor to receive changes
      Throws:
        `SVNException` - in case the repository could not be connected
        `SVNAuthenticationException` - in case of authentication problems
      Since:
        1.1, new in SVN 1.4

    - #### replayRange

          public void replayRange(long startRevision,
                         long endRevision,
                         long lowRevision,
                         boolean sendDeltas,
                         ISVNReplayHandler handler)
                           throws SVNException

      Replays the changes from a range of revisions between `startRevision` and `endRevision`.

      When receiving information for one revision, `ISVNReplayHandler.handleStartRevision(long, SVNProperties)` is called; this method will provide an editor through which the revision will be replayed. When replaying the revision is finished, `ISVNReplayHandler.handleEndRevision(long, SVNProperties, ISVNEditor)` will be called so the editor can be closed.

      Changes will be limited to those that occur under this object's `getLocation()`, and the server will assume that the client has no knowledge of revisions prior to `lowRevision`. These two limiting factors define the portion of the tree that the server will assume the client already has knowledge of, and thus any copies of data from outside that part of the tree will be sent in their entirety, not as simple copies or deltas against a previous version.

      If `sendDeltas` is true, the actual text and property changes in the revision will be sent, otherwise dummy text deltas and null property changes will be sent instead.

      If the server does not support revision range replication, then invokes `replay(long, long, boolean, ISVNEditor)` on each revision between `startRevision` and `endRevision` inclusively.
      Parameters:
        `startRevision` - revision range start
        `endRevision` - revision range end
        `lowRevision` - low water mark revision
        `sendDeltas` - whether to ask the server send text and properties
        `handler` - caller's handler
      Throws:
        `SVNException` - in the following cases:
        exception with `SVNErrorCode.RA_NOT_IMPLEMENTED` error code - if the server does not support revision range replication
      Since:
        1.2.0, New in Subversion 1.5.0

    - #### getCommitEditor

          public ISVNEditor getCommitEditor(java.lang.String logMessage,
                                   ISVNWorkspaceMediator mediator)
                                     throws SVNException

      Gets an editor for committing changes to a repository. Having got the editor traverse a local tree of dirs and/or files to be committed, handling them with corresponding methods of the editor.

      `mediator` is used for temporary delta data storage allocations.

      The root path of the commit is the current repository location to which this object is set.

      After the commit has succeeded `ISVNEditor.closeEdit()` returns an SVNCommitInfo object that contains a new revision number, the commit date, commit author.

      This method should be rather used with pre-1.2 repositories.

      NOTE: you may not invoke methods of this SVNRepository object from within the returned commit editor.

      Parameters:
        `logMessage` - a commit log message
        `mediator` - temp delta storage provider; used also to cache wcprops while committing
      Returns:
        an editor to commit a local tree of dirs and/or files
      Throws:
        `SVNException` - in the following cases:
        - the repository location this object is set to is not a directory
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `ISVNEditor`, `ISVNWorkspaceMediator`, Using ISVNEditor in commit operations

    - #### info

          public abstract SVNDirEntry info(java.lang.String path,
                         long revision)
                                    throws SVNException

      Gives information about an entry located at the specified path in a particular revision.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      Parameters:
        `path` - an item's path
        `revision` - a revision of the entry; defaults to the latest revision (HEAD)
      Returns:
        an SVNDirEntry containing information about the entry or null if there's no entry with at the specified `path` under the specified `revision`
      Throws:
        `SVNException` - in the following cases:
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)

    - #### getCommitEditor

          public abstract ISVNEditor getCommitEditor(java.lang.String logMessage,
                                   java.util.Map locks,
                                   boolean keepLocks,
                                   ISVNWorkspaceMediator mediator)
                                              throws SVNException

      Gets an editor for committing changes to a repository. Having got the editor traverse a local tree of dirs and/or files to be committed, handling them with corresponding methods of the editor.

      `locks` is a map used to provide lock tokens on the locked paths. Keys are locked paths in a local tree, and each value for a key is a lock token. `locks` must live during the whole commit operation.

      If `keepLocks` is true, then the locked paths won't be unlocked after a successful commit. Otherwise, if false, locks will be automatically released.

      `mediator` is used for temporary delta data storage allocations.

      The root path of the commit is the current repository location to which this object is set.

      After the commit has succeeded `ISVNEditor.closeEdit()` returns an SVNCommitInfo object that contains a new revision number, the commit date, commit author.

      NOTE: you may not invoke methods of this SVNRepository object from within the returned commit editor.

      Parameters:
        `logMessage` - a commit log message
        `locks` - a map containing locked paths mapped to lock tokens
        `keepLocks` - true to keep existing locks; false to release locks after the commit
        `mediator` - temp delta storage provider; used also to cache wcprops while committing
      Returns:
        an editor to commit a local tree of dirs and/or files
      Throws:
        `SVNException` - in the following cases:
        - the repository location this object is set to is not a directory
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      See Also:
        `getCommitEditor(String, ISVNWorkspaceMediator)`, Using ISVNEditor in commit operations

    - #### getCommitEditor

          public ISVNEditor getCommitEditor(java.lang.String logMessage,
                                   java.util.Map locks,
                                   boolean keepLocks,
                                   SVNProperties revisionProperties,
                                   ISVNWorkspaceMediator mediator)
                                     throws SVNException

      Returns an editor for committing changes to the repository ession, setting the revision properties from `revisionProperties` table. The revisions being committed against are passed to the editor methods, starting with the `revision` argument to `ISVNEditor.openRoot(long)`. The path root of the commit is this object's `location`.

      `revisionProperties` maps `String` property names to `SVNPropertyValue` property values. `revisionProperties` can not contain either of `SVNRevisionProperty.LOG`, `SVNRevisionProperty.DATE` or `SVNRevisionProperty.AUTHOR`.

      `locks`, if non-null, is a hash mapping `String` paths (relative to the `location` of this object) to `String` lock tokens. The server checks that the correct token is provided for each committed, locked path.

      If `keepLocks` is true, then does not release locks on committed objects. Else, automatically releasees such locks.

      The caller may not perform any repository access operations using this `SVNRepository` object before finishing the edit.
      Parameters:
        `logMessage` - commit log message
        `locks` - local locks on files
        `keepLocks` - whether to unlock locked files after the commit or not
        `revisionProperties` - custom revision properties
        `mediator` - temp delta storage provider; used also to cache wcprops while committing
      Returns:
        commit editor
      Throws:
        `SVNException` - in the following cases:
        exception with `SVNErrorCode.CLIENT_PROPERTY_NAME` error code - if `revisionProperties` contains any `svn:` namespace property
      Since:
        1.2.0, New in Subversion 1.5.0

    - #### getCommitEditorInternal

          protected abstract ISVNEditor getCommitEditorInternal(java.util.Map locks,
                                           boolean keepLocks,
                                           SVNProperties revProps,
                                           ISVNWorkspaceMediator mediator)
                                                         throws SVNException

      Throws:
        `SVNException`

    - #### getLock

          public abstract SVNLock getLock(java.lang.String path)
                                   throws SVNException

      Gets the lock for the file located at the specified path. If the file has no lock the method returns null.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      Parameters:
        `path` - a file path
      Returns:
        an SVNLock instance (representing the lock) or null if there's no lock
      Throws:
        `SVNException` - in the following cases:
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      Since:
        SVN 1.2
      See Also:
        `lock(Map, String, boolean, ISVNLockHandler)`, `unlock(Map, boolean, ISVNLockHandler)`, `getLocks(String)`, `SVNLock`

    - #### getLocks

          public abstract SVNLock[] getLocks(java.lang.String path)
                                      throws SVNException

      Gets all locks on or below the `path`, that is if the repository entry (located at the `path`) is a directory then the method returns locks of all locked files (if any) in it.

      The `path` arg can be both relative to the location of this driver and absolute to the repository root (starts with `"/"`).

      Parameters:
        `path` - a path under which locks are to be retrieved
      Returns:
        an array of SVNLock objects (representing locks)
      Throws:
        `SVNException` - in the following cases:
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      Since:
        SVN 1.2
      See Also:
        `lock(Map, String, boolean, ISVNLockHandler)`, `unlock(Map, boolean, ISVNLockHandler)`, `getLock(String)`, `SVNLock`

    - #### getMergeInfo

          public java.util.Map getMergeInfo(java.lang.String[] paths,
                                   long revision,
                                   SVNMergeInfoInheritance inherit,
                                   boolean includeDescendants)
                                     throws SVNException

      Returns merge information for the repository entries in `paths` for paricular `revision`, if the repository supports merge-tracking information
      Parameters:
        `paths` - paths under which merge information is to be retrieved
        `revision` - revision for which merge information is to be retrieved
        `inherit` - indicates whether explicit, explicit or inherited, or only inherited merge info is retrieved
        `includeDescendants` - indicates whether merge info is retrieved for descendants of elements in `paths`
      Returns:
        the map of merge information for the repository entries in `paths`
      Throws:
        `SVNException` - in case the repository could not be connected
        `SVNAuthenticationException` - in case of authentication problems
      Since:
        SVNKit 1.2.0, SVN 1.5.0

    - #### lock

          public abstract void lock(java.util.Map pathsToRevisions,
                  java.lang.String comment,
                  boolean force,
                  ISVNLockHandler handler)
                             throws SVNException

      Locks path(s) at definite revision(s).

      Note that locking is never anonymous, so any server implementing this function will have to "pull" a username from the client, if it hasn't done so already.

      Each path to be locked is handled with the provided `handler`. If a path was successfully locked, the `handler`'s `handleLock()` is called that receives the path and either a lock object (representing the lock that was set on the path) or an error exception, if locking failed for that path.

      If any path is already locked by a different user and the `force` flag is false, then this call fails with throwing an SVNException. But if `force` is true, then the existing lock(s) will be "stolen" anyway, even if the user name does not match the current lock's owner.

      Paths can be both relative to the location of this driver and absolute to the repository root (starting with `"/"`).

      Parameters:
        `pathsToRevisions` - a map which keys are paths and values are revision numbers (as Longs); paths are strings and revision numbers are Long objects
        `comment` - a comment string for the lock (optional)
        `force` - true if the file is to be locked in any way (even if it's already locked by someone else)
        `handler` - if not null, the lock handler is invoked on each path to be locked
      Throws:
        `SVNException` - in the following cases:
        - `force` is false and a path is already locked by someone else
        - a revision of a path is less than its last changed revision
        - a path does not exist in the latest revision
        - a failure occured while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      Since:
        SVN 1.2
      See Also:
        `unlock(Map, boolean, ISVNLockHandler)`, `getLocks(String)`, `getLock(String)`, `SVNLock`

    - #### unlock

          public abstract void unlock(java.util.Map pathToTokens,
                    boolean force,
                    ISVNLockHandler handler)
                               throws SVNException

      Removes lock(s) from the file(s).

      Note that unlocking is never anonymous, so any server implementing this function will have to "pull" a username from the client, if it hasn't done so already.

      Each path to be unlocked is handled with the provided `handler`. If a path was successfully unlocked, the `handler`'s `handleUnlock()` is called that receives the path and either a lock object (representing the lock that was removed from the path) or an error exception, if unlocking failed for that path.

      If the username doesn't match the lock's owner and `force` is false, this method call fails with throwing an SVNException. But if the `force` flag is true, the lock will be "broken" by the current user.

      Also if the lock token is incorrect or null and `force` is false, the method fails with throwing a SVNException. However, if `force` is true the lock will be removed anyway.

      Paths can be both relative to the location of this driver and absolute to the repository root (starting with `"/"`).

      Parameters:
        `pathToTokens` - a map which keys are file paths and values are file lock tokens (both keys and values are strings)
        `force` - true to remove the lock in any case - i.e. to "break" the lock
        `handler` - if not null, the lock handler is invoked on each path to be unlocked
      Throws:
        `SVNException` - in the following cases:
        - `force` is false and the name of the user who tries to unlock a path does not match the lock owner
        - a lock token is incorrect for a path
        - a failure occurred while connecting to a repository
        - the user authentication failed (see `SVNAuthenticationException`)
      Since:
        SVN 1.2
      See Also:
        `lock(Map, String, boolean, ISVNLockHandler)`, `getLocks(String)`, `getLock(String)`, `SVNLock`

    - #### closeSession

          public abstract void closeSession()

      Closes the current session closing a socket connection used by this object. If this driver object keeps a single connection for all the data i/o, this method helps to reset the connection.

    - #### hasCapability

          public abstract boolean hasCapability(SVNCapability capability)
                                         throws SVNException

      Returns `true` if the repository has specified `capability`. This method may need to establish connection with the repository if information on capabilities has not been received yet from the repository.
      Parameters:
        `capability` - one of `SVNCapability`
      Returns:
        boolean if the repository has specified capability
      Throws:
        `SVNException` - in case the repository could not be connected
        `SVNAuthenticationException` - in case of authentication problems
      Since:
        SVNKit 1.2.0, SVN 1.5.0
      See Also:
        `SVNCapability`

    - #### getOptions

          public ISVNSession getOptions()

      Returns the session options object this driver is using. If no options object was provided to create this driver then it uses a default one - `ISVNSession.DEFAULT`.
      Returns:
        a session options object

    - #### addConnectionListener

          public void addConnectionListener(ISVNConnectionListener listener)

      Adds a connection listener to this object. There can be more than one connection listeners added to a single `SVNRepository` object.

      All the provided listeners will be notified each time by this object about a new connection which it's opening.

      Note: listeners are not notified in case of the `file:///` repository access protocol.
      Parameters:
        `listener` - caller's connection listener
      Since:
        1.2.0

    - #### removeConnectionListener

          public void removeConnectionListener(ISVNConnectionListener listener)

      Removes the specified connection listener from the collection of connection listeners held by this object.
      Parameters:
        `listener` - connection listener to remove
      Since:
        1.2.0

    - #### getDeletedRevision

          public long getDeletedRevision(java.lang.String path,
                                long pegRevision,
                                long endRevision)
                                  throws SVNException

      Returns the revision where the path was first deleted within the inclusive revision range defined by `pegRevision` and `endRevision`.

      If `path` does not exist at `pegRevision` or was not deleted within the specified range, then returns an invalid revision (`<0`).
      Parameters:
        `path` - relative or absolute repository path
        `pegRevision` - peg revision to start the search from
        `endRevision` - end revision to end the search at
      Returns:
        revision where `path` is first deleted
      Throws:
        `SVNException` - if `pegRevision` or `endRevision` are invalid or if `pegRevision` is greater than `endRevision`, then the exception is set `SVNErrorCode.CLIENT_BAD_REVISION` error code; if `path` is the repository root (`"/"`).
      Since:
        1.3

    - #### getDeletedRevisionImpl

          protected abstract long getDeletedRevisionImpl(java.lang.String path,
                                    long pegRevision,
                                    long endRevision)
                                                  throws SVNException

      Throws:
        `SVNException`

    - #### getLocationSegmentsImpl

          protected abstract long getLocationSegmentsImpl(java.lang.String path,
                                     long pegRevision,
                                     long startRevision,
                                     long endRevision,
                                     ISVNLocationSegmentHandler handler)
                                                   throws SVNException

      Throws:
        `SVNException`

    - #### getLocationsImpl

          protected abstract int getLocationsImpl(java.lang.String path,
                             long pegRevision,
                             long[] revisions,
                             ISVNLocationEntryHandler handler)
                                           throws SVNException

      Throws:
        `SVNException`

    - #### logImpl

          protected abstract long logImpl(java.lang.String[] targetPaths,
                     long startRevision,
                     long endRevision,
                     boolean changedPath,
                     boolean strictNode,
                     long limit,
                     boolean includeMergedRevisions,
                     java.lang.String[] revisionProperties,
                     ISVNLogEntryHandler handler)
                                   throws SVNException

      Throws:
        `SVNException`

    - #### getFileRevisionsImpl

          protected abstract int getFileRevisionsImpl(java.lang.String path,
                                 long startRevision,
                                 long endRevision,
                                 boolean includeMergedRevisions,
                                 ISVNFileRevisionHandler handler)
                                               throws SVNException

      Throws:
        `SVNException`

    - #### getMergeInfoImpl

          protected abstract java.util.Map getMergeInfoImpl(java.lang.String[] paths,
                                       long revision,
                                       SVNMergeInfoInheritance inherit,
                                       boolean includeDescendants)
                                                     throws SVNException

      Throws:
        `SVNException`

    - #### replayRangeImpl

          protected abstract void replayRangeImpl(long startRevision,
                             long endRevision,
                             long lowRevision,
                             boolean sendDeltas,
                             ISVNReplayHandler handler)
                                           throws SVNException

      Throws:
        `SVNException`

    - #### fireConnectionOpened

          protected void fireConnectionOpened()

    - #### fireConnectionClosed

          protected void fireConnectionClosed()

    - #### lock

          protected void lock()

    - #### lock

          protected void lock(boolean force)

    - #### unlock

          protected void unlock()

    - #### isInvalidRevision

          protected static boolean isInvalidRevision(long revision)

    - #### isValidRevision

          protected static boolean isValidRevision(long revision)

    - #### getRevisionObject

          protected static java.lang.Long getRevisionObject(long revision)

    - #### assertValidRevision

          protected static void assertValidRevision(long revision)
                                             throws SVNException

      Throws:
        `SVNException`

    - #### hasSVNProperties

          protected static boolean hasSVNProperties(SVNProperties props)

    - #### getRepositoryPath

          public java.lang.String getRepositoryPath(java.lang.String relativePath)
                                             throws SVNException

      Returns a path relative to the repository root directory given a path relative to the location to which this driver object is set.
      Parameters:
        `relativePath` - a path relative to the location to which this SVNRepository is set
      Returns:
        a path relative to the repository root
      Throws:
        `SVNException` - in case the repository could not be connected
        `SVNAuthenticationException` - in case of authentication problems

    - #### getFullPath

          public java.lang.String getFullPath(java.lang.String relativeOrRepositoryPath)
                                       throws SVNException

      Resolves a path, relative either to the location to which this driver object is set or to the repository root directory, to a path, relative to the host.
      Parameters:
        `relativeOrRepositoryPath` - a relative path within the repository
      Returns:
        a path relative to the host
      Throws:
        `SVNException` - in case the repository could not be connected
        `SVNAuthenticationException` - in case of authentication problems

    - #### setDebugLog

          public void setDebugLog(org.tmatesoft.svn.util.ISVNDebugLog log)

      Sets a logger to write debug log information to.
      Parameters:
        `log` - a debug logger

    - #### getDebugLog

          public org.tmatesoft.svn.util.ISVNDebugLog getDebugLog()

      Returns the debug logger currently in use.

      If no debug logger has been specified by the time this call occurs, a default one (returned by `org.tmatesoft.svn.util.SVNDebugLog.getDefaultLog()`) will be created and used.

      Returns:
        a debug logger

Copyright © 2004-2009 TMate Software Ltd. All Rights Reserved.