org.tmatesoft.svn.core.io

Class SVNRepository

public abstract class SVNRepository extends 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.

Version: 1.1.1

Author: TMate Software Ltd.

See Also: SVNRepositoryFactory ISVNAuthenticationManager Examples

Field Summary
protected SVNURLmyLocation
protected SVNURLmyRepositoryRoot
protected StringmyRepositoryUUID
Constructor Summary
protected SVNRepository(SVNURL location, ISVNSession options)
Method Summary
voidaddConnectionListener(ISVNConnectionListener listener)
protected static voidassertValidRevision(long revision)
voidcheckout(long revision, String target, boolean recursive, ISVNEditor editor)
Checks out a directory from a repository .
abstract SVNNodeKindcheckPath(String path, long revision)
Returns the kind of an item located at the specified path in a particular revision.
abstract voidcloseSession()
Closes the current session closing a socket connection used by this object.
abstract voiddiff(SVNURL url, long targetRevision, long revision, String target, boolean ignoreAncestry, boolean recursive, boolean getContents, ISVNReporterBaton reporter, ISVNEditor editor)
Calculates the differences between two items.
abstract voiddiff(SVNURL url, long targetRevision, long revision, String target, boolean ignoreAncestry, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)
abstract voiddiff(SVNURL url, long revision, String target, boolean ignoreAncestry, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)
Calculates the differences between two items.
protected voidfireConnectionClosed()
protected voidfireConnectionOpened()
ISVNAuthenticationManagergetAuthenticationManager()
Returns the authentication driver registered for this object.
ISVNCancellergetCanceller()
ISVNEditorgetCommitEditor(String logMessage, ISVNWorkspaceMediator mediator)
Gets an editor for committing changes to a repository.
abstract ISVNEditorgetCommitEditor(String logMessage, Map locks, boolean keepLocks, ISVNWorkspaceMediator mediator)
Gets an editor for committing changes to a repository.
abstract longgetDatedRevision(Date date)
Returns the recent repository revision number for the particular moment in time - the closest one before or at the specified datestamp.
ISVNDebugLoggetDebugLog()
Returns the debug logger currently in use.
abstract longgetDir(String path, long revision, Map properties, ISVNDirEntryHandler handler)
Fetches the contents and/or properties of a directory located at the specified path in a particular revision.
CollectiongetDir(String path, long revision, Map properties, Collection dirEntries)
Fetches the contents and properties of a directory located at the specified path in a particular revision.
abstract SVNDirEntrygetDir(String path, long revision, boolean includeCommitMessages, Collection entries)
Fetches the contents of a directory into the provided collection object and returns the directory entry itself.
abstract longgetFile(String path, long revision, Map properties, OutputStream contents)
Fetches the contents and/or properties of a file located at the specified path in a particular revision.
abstract intgetFileRevisions(String path, long startRevision, long endRevision, ISVNFileRevisionHandler handler)
Retrieves interesting file revisions for the specified file.
CollectiongetFileRevisions(String path, Collection revisions, long sRevision, long eRevision)
Retrieves and returns interesting file revisions for the specified file.
StringgetFullPath(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 longgetLatestRevision()
Returns the number of the latest revision of the repository this driver is working with.
SVNURLgetLocation()
Returns the repository location to which this object is set.
abstract intgetLocations(String path, long pegRevision, long[] revisions, ISVNLocationEntryHandler handler)
Gets entry locations in time.
CollectiongetLocations(String path, Collection entries, long pegRevision, long[] revisions)
Gets entry locations in time.
MapgetLocations(String path, Map entries, long pegRevision, long[] revisions)
Gets entry locations in time.
abstract SVNLockgetLock(String path)
Gets the lock for the file located at the specified path.
abstract SVNLock[]getLocks(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.
ISVNSessiongetOptions()
Returns the session options object this driver is using.
StringgetRepositoryPath(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.
SVNURLgetRepositoryRoot()
SVNURLgetRepositoryRoot(boolean forceConnection)
Gets a repository's root directory location.
StringgetRepositoryUUID()
StringgetRepositoryUUID(boolean forceConnection)
Gets the Universal Unique IDentifier (UUID) of the repository this driver is created for.
protected static LonggetRevisionObject(long revision)
abstract MapgetRevisionProperties(long revision, Map properties)
Returns unversioned revision properties for a particular revision.
abstract StringgetRevisionPropertyValue(long revision, String propertyName)
Gets the value of an unversioned property.
ISVNTunnelProvidergetTunnelProvider()
Returns a tunnel provider.
abstract SVNDirEntryinfo(String path, long revision)
Gives information about an entry located at the specified path in a particular revision.
protected static booleanisInvalidRevision(long revision)
protected static booleanisValidRevision(long revision)
abstract voidlock(Map pathsToRevisions, String comment, boolean force, ISVNLockHandler handler)
Locks path(s) at definite revision(s).
protected voidlock()
protected voidlock(boolean force)
longlog(String[] targetPaths, long startRevision, long endRevision, boolean changedPath, boolean strictNode, ISVNLogEntryHandler handler)
Traverses revisions history.
abstract longlog(String[] targetPaths, long startRevision, long endRevision, boolean changedPath, boolean strictNode, long limit, ISVNLogEntryHandler handler)
Traverses revisions history.
Collectionlog(String[] targetPaths, Collection entries, long startRevision, long endRevision, boolean changedPath, boolean strictNode)
Traverses revisions history and returns a collection of log entries.
voidremoveConnectionListener(ISVNConnectionListener listener)
abstract voidreplay(long lowRevision, long revision, boolean sendDeltas, ISVNEditor editor)
Replays the changes from the specified revision through the given editor.
voidsetAuthenticationManager(ISVNAuthenticationManager authManager)
Sets an authentication driver for this object.
voidsetCanceller(ISVNCanceller canceller)
voidsetDebugLog(ISVNDebugLog log)
Sets a logger to write debug log information to.
voidsetLocation(SVNURL url, boolean forceReconnect)
Sets a new repository location for this object.
protected voidsetRepositoryCredentials(String uuid, SVNURL rootURL)
Caches identification parameters (UUID, rood directory location) of the repository with which this driver is working.
abstract voidsetRevisionPropertyValue(long revision, String propertyName, String propertyValue)
Sets a revision property with the specified name to a new value.
voidsetTunnelProvider(ISVNTunnelProvider tunnelProvider)
Sets a tunnel provider.
abstract voidstatus(long revision, String target, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)
Gets status of a path.
abstract voidtestConnection()
Tries to access a repository.
abstract voidunlock(Map pathToTokens, boolean force, ISVNLockHandler handler)
Removes lock(s) from the file(s).
protected voidunlock()
abstract voidupdate(long revision, String target, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)
Updates a path receiving changes from a repository.
abstract voidupdate(SVNURL url, long revision, String target, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)
Updates a path switching it to a new repository location.

Field Detail

myLocation

protected SVNURL myLocation

myRepositoryRoot

protected SVNURL myRepositoryRoot

myRepositoryUUID

protected String myRepositoryUUID

Constructor Detail

SVNRepository

protected SVNRepository(SVNURL location, ISVNSession options)

Method Detail

addConnectionListener

public void addConnectionListener(ISVNConnectionListener listener)

assertValidRevision

protected static void assertValidRevision(long revision)

checkout

public void checkout(long revision, String target, boolean recursive, ISVNEditor editor)
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:

See Also: SVNRepository

checkPath

public abstract SVNNodeKind checkPath(String path, long revision)
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)

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.

Throws: SVNException if some i/o error has occurred

diff

public abstract void diff(SVNURL url, long targetRevision, long revision, String target, boolean ignoreAncestry, boolean recursive, boolean getContents, ISVNReporterBaton reporter, ISVNEditor editor)
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.

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 ot the editor. reporter a caller's reporter editor a caller's editor

Throws: SVNException in the following cases:

See Also: ISVNReporterBaton ISVNReporter ISVNEditor

diff

public abstract void diff(SVNURL url, long targetRevision, long revision, String target, boolean ignoreAncestry, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)

Deprecated:

diff

public abstract void diff(SVNURL url, long revision, String target, boolean ignoreAncestry, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)

Deprecated: use SVNRepository 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.

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:

See Also: ISVNReporterBaton ISVNReporter ISVNEditor

fireConnectionClosed

protected void fireConnectionClosed()

fireConnectionOpened

protected void fireConnectionOpened()

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

getCanceller

public ISVNCanceller getCanceller()

getCommitEditor

public ISVNEditor getCommitEditor(String logMessage, ISVNWorkspaceMediator mediator)
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:

See Also: ISVNEditor ISVNWorkspaceMediator Using ISVNEditor in commit operations

getCommitEditor

public abstract ISVNEditor getCommitEditor(String logMessage, Map locks, boolean keepLocks, ISVNWorkspaceMediator mediator)
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:

See Also: SVNRepository Using ISVNEditor in commit operations

getDatedRevision

public abstract long getDatedRevision(Date date)
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)

getDebugLog

public 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

getDir

public abstract long getDir(String path, long revision, Map properties, ISVNDirEntryHandler handler)
Fetches the contents and/or properties of a directory located at the specified path in a particular revision.

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 handler a handler to process directory entries

Returns: the revision of the directory

Throws: SVNException in the following cases:

See Also: SVNRepository SVNRepository SVNDirEntry

getDir

public Collection getDir(String path, long revision, Map properties, Collection dirEntries)
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.

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:

See Also: SVNRepository SVNRepository SVNDirEntry

getDir

public abstract SVNDirEntry getDir(String path, long revision, boolean includeCommitMessages, Collection entries)
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:

See Also: SVNRepository SVNRepository SVNDirEntry

getFile

public abstract long getFile(String path, long revision, Map properties, OutputStream contents)
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:

getFileRevisions

public abstract int getFileRevisions(String path, long startRevision, long endRevision, ISVNFileRevisionHandler handler)
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:

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: SVNRepository SVNFileRevision

getFileRevisions

public Collection getFileRevisions(String path, Collection revisions, long sRevision, long eRevision)
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: SVNRepository SVNFileRevision

getFullPath

public String getFullPath(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.

Parameters: relativeOrRepositoryPath a relative path within the repository

Returns: a path relative to the host

Throws: SVNException

getLatestRevision

public abstract long getLatestRevision()
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)

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 create), or the recent one the object was set to.

Returns: a repository location set for this driver

See Also:

getLocations

public abstract int getLocations(String path, long pegRevision, long[] revisions, ISVNLocationEntryHandler handler)
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:

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:

Since: SVN 1.1

See Also: (String, Collection, long, long[]) (String, Map, long, long[]) ISVNLocationEntryHandler SVNLocationEntry

getLocations

public Collection getLocations(String path, Collection entries, long pegRevision, long[] revisions)
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:

Since: SVN 1.1

See Also: (String, long, long[], ISVNLocationEntryHandler) (String, Map, long, long[]) SVNLocationEntry ISVNLocationEntryHandler

getLocations

public Map getLocations(String path, Map entries, long pegRevision, long[] revisions)
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:

Since: SVN 1.1

See Also: (String, long, long[], ISVNLocationEntryHandler) (String, Collection, long, long[]) SVNLocationEntry ISVNLocationEntryHandler

getLock

public abstract SVNLock getLock(String path)
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:

Since: SVN 1.2

See Also: SVNRepository SVNRepository getLocks SVNLock

getLocks

public abstract SVNLock[] getLocks(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.

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:

Since: SVN 1.2

See Also: SVNRepository SVNRepository getLock SVNLock

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 - DEFAULT.

Returns: a session options object

getRepositoryPath

public String getRepositoryPath(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.

Parameters: relativePath a path relative to the location to which this SVNRepository is set

Returns: a path relative to the repository root

Throws: SVNException

getRepositoryRoot

public SVNURL getRepositoryRoot()

Deprecated: use #getRepositoryRoot(boolean) instead

Returns: the repository root directory location url

See Also:

getRepositoryRoot

public SVNURL getRepositoryRoot(boolean forceConnection)
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.

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

See Also: testConnection

getRepositoryUUID

public String getRepositoryUUID()

Deprecated: use instead

Returns: the UUID of a repository

getRepositoryUUID

public String getRepositoryUUID(boolean forceConnection)
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

getRevisionObject

protected static Long getRevisionObject(long revision)

getRevisionProperties

public abstract Map getRevisionProperties(long revision, Map properties)
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:

See Also: SVNRevisionProperty

getRevisionPropertyValue

public abstract String getRevisionPropertyValue(long revision, String propertyName)
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:

getTunnelProvider

public ISVNTunnelProvider getTunnelProvider()
Returns a tunnel provider.

Returns: a tunnel provider

See Also: setTunnelProvider

info

public abstract SVNDirEntry info(String path, long revision)
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:

isInvalidRevision

protected static boolean isInvalidRevision(long revision)

isValidRevision

protected static boolean isValidRevision(long revision)

lock

public abstract void lock(Map pathsToRevisions, String comment, boolean force, ISVNLockHandler handler)
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:

Since: SVN 1.2

See Also: SVNRepository getLocks getLock SVNLock

lock

protected void lock()

lock

protected void lock(boolean force)

log

public long log(String[] targetPaths, long startRevision, long endRevision, boolean changedPath, boolean strictNode, ISVNLogEntryHandler handler)
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 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: (String[], Collection, long, long, boolean, boolean) (String[], long, long, boolean, boolean, long, ISVNLogEntryHandler) ISVNLogEntryHandler SVNLogEntry SVNLogEntryPath

log

public abstract long log(String[] targetPaths, long startRevision, long endRevision, boolean changedPath, boolean strictNode, long limit, ISVNLogEntryHandler handler)
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 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: (String[], Collection, long, long, boolean, boolean) (String[], long, long, boolean, boolean, long, ISVNLogEntryHandler) ISVNLogEntryHandler SVNLogEntry SVNLogEntryPath

log

public Collection log(String[] targetPaths, Collection entries, long startRevision, long endRevision, boolean changedPath, boolean strictNode)
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 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: (String[], long, long, boolean, boolean, ISVNLogEntryHandler) (String[], long, long, boolean, boolean, long, ISVNLogEntryHandler) ISVNLogEntryHandler SVNLogEntry SVNLogEntryPath

removeConnectionListener

public void removeConnectionListener(ISVNConnectionListener listener)

replay

public abstract void replay(long lowRevision, long revision, boolean sendDeltas, ISVNEditor editor)
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 null, 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

Since: 1.1, new in SVN 1.4

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

setCanceller

public void setCanceller(ISVNCanceller canceller)

setDebugLog

public void setDebugLog(ISVNDebugLog log)
Sets a logger to write debug log information to.

Parameters: log a debug logger

setLocation

public void setLocation(SVNURL url, boolean forceReconnect)
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

setRepositoryCredentials

protected void setRepositoryCredentials(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: SVNRepository SVNRepository

setRevisionPropertyValue

public abstract void setRevisionPropertyValue(long revision, String propertyName, String propertyValue)
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:

See Also: SVNRevisionProperty

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

status

public abstract void status(long revision, String target, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)
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:

See Also: ISVNReporterBaton ISVNEditor

testConnection

public abstract void testConnection()
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)

unlock

public abstract void unlock(Map pathToTokens, boolean force, ISVNLockHandler handler)
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:

Since: SVN 1.2

See Also: SVNRepository getLocks getLock SVNLock

unlock

protected void unlock()

update

public abstract void update(long revision, String target, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)
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:

See Also: SVNRepository ISVNReporterBaton ISVNReporter ISVNEditor Using ISVNReporter/ISVNEditor in update-related operations

update

public abstract void update(SVNURL url, long revision, String target, boolean recursive, ISVNReporterBaton reporter, ISVNEditor editor)
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:

See Also: SVNRepository ISVNReporterBaton ISVNReporter ISVNEditor Using ISVNReporter/ISVNEditor in update-related operations

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