org.apache.subversion.javahl

Interface ISVNRemote

All Known Implementing Classes:

RemoteSession

public interface ISVNRemote

Encapsulates an RA session object and related operations.

Since:

1.9

See Also:

svn_ra.h, the documentation of the svn_ra_open function.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ISVNRemote.Capability Enumeration of known capabilities of the repository and server.
static class	ISVNRemote.FileRevision The object returned by getFileRevisions(java.lang.String, long, long, boolean, org.apache.subversion.javahl.callback.RemoteFileRevisionsCallback).
static class	ISVNRemote.LocationSegment The object returned from getLocationSegments(java.lang.String, long, long, long, org.apache.subversion.javahl.callback.RemoteLocationSegmentsCallback).

Method Summary

Modifier and Type	Method and Description
void	cancelOperation() Cancel the active operation, including any ongoing edits.
void	changeRevisionProperty(long revision, java.lang.String propertyName, byte[] oldValue, byte[] newValue) Change the value of an unversioned property.
NodeKind	checkPath(java.lang.String path, long revision) Return the kind of the node in path at revision.
void	dispose() Release the native peer (should not depend on finalize).
ISVNEditor	getCommitEditor(java.util.Map<java.lang.String,byte[]> revisionProperties, CommitCallback commitCallback, java.util.Set<Lock> lockTokens, boolean keepLocks) Like #getCommitEditor(Map,CommitCallback, but with all callbacks set to null.
ISVNEditor	getCommitEditor(java.util.Map<java.lang.String,byte[]> revisionProperties, CommitCallback commitCallback, java.util.Set<Lock> lockTokens, boolean keepLocks, ISVNEditor.ProvideBaseCallback getBase, ISVNEditor.ProvidePropsCallback getProps, ISVNEditor.GetNodeKindCallback getCopyfromKind) Return an editor for committing changes to the session's repository, setting the revision properties from revisionProperties.
long	getDirectory(long revision, java.lang.String path, int direntFields, java.util.Map<java.lang.String,DirEntry> dirents, java.util.Map<java.lang.String,byte[]> properties) Fetch the contents and properties of directory path at revision.
long	getFile(long revision, java.lang.String path, java.io.OutputStream contents, java.util.Map<java.lang.String,byte[]> properties) Fetch the contents and properties of file path at revision.
java.util.List<ISVNRemote.FileRevision>	getFileRevisions(java.lang.String path, long startRevision, long endRevision, boolean includeMergedRevisions) Retrieve a subset of the interesting revisions of a file path as seen in revision endRevision.
void	getFileRevisions(java.lang.String path, long startRevision, long endRevision, boolean includeMergedRevisions, RemoteFileRevisionsCallback handler) Call handler for each of a subset of the interesting revisions of a file path as seen in revision endRevision.
long	getLatestRevision() Get the latest revision number from the session's repository.
java.util.Map<java.lang.Long,java.lang.String>	getLocations(java.lang.String path, long pegRevision, java.lang.Iterable<java.lang.Long> locationRevisions) Find the locations of the object identified by path and pegRevision in the repository at the given revisions.
java.util.List<ISVNRemote.LocationSegment>	getLocationSegments(java.lang.String path, long pegRevision, long startRevision, long endRevision) Return a list of segments in the location history of path at pegRevision, working backwards in time from startRevision to endRevision.
void	getLocationSegments(java.lang.String path, long pegRevision, long startRevision, long endRevision, RemoteLocationSegmentsCallback handler) Call handler for every segment in the location history of path at pegRevision, working backwards in time from startRevision to endRevision.
java.util.Map<java.lang.String,Lock>	getLocks(java.lang.String path, Depth depth) Return a dictionary containing all locks on or below the given path.
void	getLog(java.lang.Iterable<java.lang.String> paths, long startRevision, long endRevision, int limit, boolean strictNodeHistory, boolean discoverPath, boolean includeMergedRevisions, java.lang.Iterable<java.lang.String> revisionProperties, LogMessageCallback callback) Invoke callback for each log message from startRevision to endRevision.
java.util.Map<java.lang.String,Mergeinfo>	getMergeinfo(java.lang.Iterable<java.lang.String> paths, long revision, Mergeinfo.Inheritance inherit, boolean includeDescendants) Retrieve the merginfo for paths, whose elements are relative to the session's URL.
java.lang.String	getReposRelativePath(java.lang.String url) Return a path relative to the repository root URL associated with current session URL.
java.lang.String	getReposRootUrl() Get the root URL of the session's repository.
java.lang.String	getReposUUID() Get the UUID of the session's repository.
long	getRevisionByDate(java.util.Date date) Get the latest revision number at the given time from the session's repository.
long	getRevisionByTimestamp(long timestamp) Get the latest revision number at the given time, expressed as the number of microseconds since the epoch, from the session's repository.
java.util.Map<java.lang.String,byte[]>	getRevisionProperties(long revision) Return the set of unversioned properties set on revision in the session's repository.
byte[]	getRevisionProperty(long revision, java.lang.String propertyName) Return the value of unversioned property propertyName in revision in the session's repository.
java.lang.String	getSessionRelativePath(java.lang.String url) Return a path relative to the current session URL.
java.lang.String	getSessionUrl() Get the current session URL.
boolean	hasCapability(ISVNRemote.Capability capability) Check if the server associated with this session has the given capability.
void	reparent(java.lang.String url) Change the URL of the session to point to a new path in the same repository.
DirEntry	stat(java.lang.String path, long revision) Return the directory entry object for path at revision.
ISVNReporter	status(java.lang.String statusTarget, long revision, Depth depth, RemoteStatus receiver) Ask for a description of the status of a working copy with respect to revision of the session's repository, or the HEAD revision if revision is Revision.SVN_INVALID_REVNUM.

Method Detail

dispose

void dispose()

Release the native peer (should not depend on finalize). Also invalidates any existing editors related to this session.

cancelOperation

void cancelOperation()
              throws ClientException

Cancel the active operation, including any ongoing edits.

Throws:

ClientException

reparent

void reparent(java.lang.String url)
       throws ClientException

Change the URL of the session to point to a new path in the same repository.

Note: The operation fails if the URL has a different repository root than the current session URL.

Throws:

ClientException

getSessionUrl

java.lang.String getSessionUrl()
                        throws ClientException

Get the current session URL.

Throws:

ClientException

getSessionRelativePath

java.lang.String getSessionRelativePath(java.lang.String url)
                                 throws ClientException

Return a path relative to the current session URL.

Parameters:

url - Must be a child of the current session URL.

Throws:

ClientException

getReposRelativePath

java.lang.String getReposRelativePath(java.lang.String url)
                               throws ClientException

Return a path relative to the repository root URL associated with current session URL.

Parameters:

url - Must be a child of the repository root URL.

Throws:

ClientException

getReposUUID

java.lang.String getReposUUID()
                       throws ClientException

Get the UUID of the session's repository.

Throws:

ClientException

getReposRootUrl

java.lang.String getReposRootUrl()
                          throws ClientException

Get the root URL of the session's repository.

Throws:

ClientException

getLatestRevision

long getLatestRevision()
                throws ClientException

Get the latest revision number from the session's repository.

Throws:

ClientException

getRevisionByDate

long getRevisionByDate(java.util.Date date)
                throws ClientException

Get the latest revision number at the given time from the session's repository.

Throws:

ClientException

getRevisionByTimestamp

long getRevisionByTimestamp(long timestamp)
                     throws ClientException

Get the latest revision number at the given time, expressed as the number of microseconds since the epoch, from the session's repository.

Throws:

ClientException

changeRevisionProperty

void changeRevisionProperty(long revision,
                            java.lang.String propertyName,
                            byte[] oldValue,
                            byte[] newValue)
                     throws ClientException

Change the value of an unversioned property.

Note: If the server has Capability.atomic_revprops and oldValue is not null, and the present value of the propery is not oldValue (e.g., if another client changed the property), then the operation will fail.

Note: If the server does not adveritse Capability.atomic_revprops, then oldValue must be null.

Parameters:

revision - The revision to which the propery is attached

propertyName - The name of the propery

oldValue - The previous value of the property (see note below)

newValue - The new value of the property. If newValue is null, the property will be deleted.

Throws:

java.lang.IllegalArgumentException - if oldValue is not null and the server does not advertise the atomic_revprops capability.

ClientException

getRevisionProperties

java.util.Map<java.lang.String,byte[]> getRevisionProperties(long revision)
                                                      throws ClientException

Return the set of unversioned properties set on revision in the session's repository.

Throws:

ClientException

getRevisionProperty

byte[] getRevisionProperty(long revision,
                           java.lang.String propertyName)
                    throws ClientException

Return the value of unversioned property propertyName in revision in the session's repository. Returns null if the property does not exist.

Throws:

ClientException

getCommitEditor

ISVNEditor getCommitEditor(java.util.Map<java.lang.String,byte[]> revisionProperties,
                           CommitCallback commitCallback,
                           java.util.Set<Lock> lockTokens,
                           boolean keepLocks,
                           ISVNEditor.ProvideBaseCallback getBase,
                           ISVNEditor.ProvidePropsCallback getProps,
                           ISVNEditor.GetNodeKindCallback getCopyfromKind)
                    throws ClientException

Return an editor for committing changes to the session's repository, setting the revision properties from revisionProperties. The revisions being committed against are passed to the editor functions. The root of the commit is the session's URL.

revisionProperties is a hash mapping property names to property values. The commit log message is expected to be in the Property.REV_LOG element. revisionProperties can not contain either of Property.REV_DATE or Property.REV_AUTHOR.

Before ISVNEditor.complete() returns, but after the commit has succeeded, it will invoke commitCallback (if not null) with filled-in CommitInfo. If commitCallback returns an error, that error will be returned from ISVNEditor.complete(), otherwise ISVNEditor.complete() will return successfully (unless it encountered an error before invoking commitCallback). The callback will not be called if the commit was a no-op (i.e., nothing was committed).

lockTokens, if not null, is a hash mapping paths (relative to the session's URL) to lock tokens. The server checks that the correct token is provided for each committed, locked path. lockTokens must live during the whole commit operation.

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

The callbacks getBase, getProps and getCopyfromKind are invoked by the editor to fetch the contents, preoprties and copyfrom kind of an entry during the commit drive. They may be null; in that case, the commit may be less efficient because the client will not be able to delta-compress the data sent to the server, and more server connections may have to be opened.

The caller may not perform any remote operations using this session before finishing the edit.

Throws:

ClientException

getCommitEditor

ISVNEditor getCommitEditor(java.util.Map<java.lang.String,byte[]> revisionProperties,
                           CommitCallback commitCallback,
                           java.util.Set<Lock> lockTokens,
                           boolean keepLocks)
                    throws ClientException

Like #getCommitEditor(Map,CommitCallback, but with all callbacks set to null.

Throws:

ClientException

getFile

long getFile(long revision,
             java.lang.String path,
             java.io.OutputStream contents,
             java.util.Map<java.lang.String,byte[]> properties)
      throws ClientException

Fetch the contents and properties of file path at revision. revision may be Revision.SVN_INVALID_REVNUM indicating that the HEAD revision should be used. path is interpreted relative to the session's URL.

If revision is Revision.SVN_INVALID_REVNUM. returns the actual revision that was retrieved; otherwise returns revision.

If contents is not null, push the contents of the file into the stream.

If properties is not null, set properties to contain the properties of the file. This means all properties: not just ones controlled by the user and stored in the repository, but immutable ones generated by the SCM system itself (e.g. 'wcprops', 'entryprops', etc.). Any existing contents of the properties map will be discarded by calling Map.clear(), if the map implementation supports that operation.

The implementations of contents and properties may not perform any ISVNRemote operations using this session.

Returns:

The revision of the file that was retrieved.

Throws:

ClientException

getDirectory

long getDirectory(long revision,
                  java.lang.String path,
                  int direntFields,
                  java.util.Map<java.lang.String,DirEntry> dirents,
                  java.util.Map<java.lang.String,byte[]> properties)
           throws ClientException

Fetch the contents and properties of directory path at revision. revision may be Revision.SVN_INVALID_REVNUM, indicating that the HEAD revision should be used. path is interpreted relative to the session's URL.

If dirents is not null, it will contain all the entries of the directory; the keys will be the entry basenames. Any existing contente of the dirents collection will be discarded by calling Map.clear(), if the collection implementation supports that operation.

direntFields controls which portions of the DirEntry objects are filled in. To have them completely filled in, just pass DirEntry.Fields.all, othewise pass a bitwise OR of any of the DirEntry.Fields flags you would like to have.

If properties is not null, set properties to contain the properties of the directory. This means all properties: not just ones controlled by the user and stored in the repository, but immutable ones generated by the SCM system itself (e.g. 'wcprops', 'entryprops', etc.). Any existing contents of the properties map will be discarded by calling Map.clear(), if the map implementation supports that operation.

The implementations of dirents and properties may not perform any ISVNRemote operations using this session.

Returns:

The revision of the directory that was retrieved.

Throws:

ClientException

getMergeinfo

java.util.Map<java.lang.String,Mergeinfo> getMergeinfo(java.lang.Iterable<java.lang.String> paths,
                                                       long revision,
                                                       Mergeinfo.Inheritance inherit,
                                                       boolean includeDescendants)
                                                throws ClientException

Retrieve the merginfo for paths, whose elements are relative to the session's URL. The request will fail if any one of paths does not exist in the given revision.

Note: If the server doesn't support retrieval of mergeinfo (which can happen even for file:// URLs, if the repository itself hasn't been upgraded), an unsupported feature exception is thrown in preference to any other error that might otherwise be returned.

Parameters:

revision - The revision to look for paths in. Defaults to the youngest revision when Revision.SVN_INVALID_REVNUM.

inherit - Indicates whether explicit, explicit or inherited, or only inherited mergeinfo for paths is retrieved.

includeDescendants - When true, additionally return the mergeinfo for any descendant of any element of paths which has the mergeinfo explicitly set on it. (Note that inheritance is only taken into account for the elements in paths; descendants of the elements in paths which get their mergeinfo via inheritance are not included.)

Returns:

A dictionary of Mergeinfo objects for the given paths, or null if no mergeinfo is available..

Throws:

ClientException

status

ISVNReporter status(java.lang.String statusTarget,
                    long revision,
                    Depth depth,
                    RemoteStatus receiver)
             throws ClientException

Ask for a description of the status of a working copy with respect to revision of the session's repository, or the HEAD revision if revision is Revision.SVN_INVALID_REVNUM.

The client begins by providing a receiver to the remote session; this object must contain knowledge of where the change will begin in the working copy.

In return, the client receives an ISVNReporter instance, which it uses to describe its working copy by making calls to its methods.

When finished, the client calls ISVNReporter.finishReport(). This results in receiver being called once for every path in the working copy that is different from the repository. statusTarget is an optional single path component that restricts the scope of the status report to an entry in the directory represented by the session's URL, or empty if the entire directory is meant to be examined.

Get status as deeply as depth indicates. If depth is Depth.unknown, get the status down to the ambient depth of the working copy. If depth is deeper than the working copy, include changes that would be needed to populate the working copy to that depth.

The caller may not perform any operations using this session before finishing the report, and may not perform any operations using this session from within the implementation of receiver.

Note: The reporter provided by this function does not supply copy-from information to the editor methods.

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.

Throws:

ClientException

getLog

void getLog(java.lang.Iterable<java.lang.String> paths,
            long startRevision,
            long endRevision,
            int limit,
            boolean strictNodeHistory,
            boolean discoverPath,
            boolean includeMergedRevisions,
            java.lang.Iterable<java.lang.String> revisionProperties,
            LogMessageCallback callback)
     throws ClientException

Invoke callback for 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 Revision.SVN_INVALID_REVNUM, the HEAD revision is uses for that argument. If eiter is an invaild non-existent revision, an error will be returned.

If paths is not null and has one or more elements, then only show revisions in which at least one of paths was changed (i.e., if file, text or props changed; if dir, props changed or an entry was added or deleted).

If limit is non-zero only invoke @a receiver on the first code>limit logs.

If discoverPath is set, then each call to callback contains the list of changed paths in that revision.

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 @a targets will also be returned.

If revisionProperties is null, retrieve all revision properties; otherwise, retrieve only the revision properties contained in the set (i.e. retrieve none if the set is empty).

The implementation of callback may not perform any operations using this session. If the invocation of callback throws an exception, the operation will stop.

Note: If paths 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 revprop retrieval; revisionProperties is null or contains a revprop other than svn:author, svn:date, or svn:log, an not-implemented error is returned.

Throws:

ClientException

checkPath

NodeKind checkPath(java.lang.String path,
                   long revision)
            throws ClientException

Return the kind of the node in path at revision.

Parameters:

path - A path relative to the sessionn URL

Throws:

ClientException

stat

DirEntry stat(java.lang.String path,
              long revision)
       throws ClientException

Return the directory entry object for path at revision.

Parameters:

path - A path relative to the sessionn URL

Returns:

A directory entry obeject, or null if path at revision does not exist.

Throws:

ClientException

getLocations

java.util.Map<java.lang.Long,java.lang.String> getLocations(java.lang.String path,
                                                            long pegRevision,
                                                            java.lang.Iterable<java.lang.Long> locationRevisions)
                                                     throws ClientException

Find the locations of the object identified by path and pegRevision in the repository at the given revisions. If the object does not exist in a given revision, that revision will be ignored.

Note: None of the parameters may be NULL.

Parameters:

path - A path relative to the session URL

pegRevision - The peg revision to use for locating the object

locationRevisions - The set of revisions to find locations for

Throws:

ClientException

getLocationSegments

void getLocationSegments(java.lang.String path,
                         long pegRevision,
                         long startRevision,
                         long endRevision,
                         RemoteLocationSegmentsCallback handler)
                  throws ClientException

Call handler for every segment in the location history of path at pegRevision, working backwards in time from startRevision to endRevision.

Parameters:

path - A session-relative path.

pegRevision - The peg revision to find path in.

startRevision - The upper bound of the revision range. Use Revision.SVN_INVALID_REVNUM to indicate HEAD.

endRevision - The lower bound of the revision range. Use Revision.SVN_INVALID_REVNUM to trace the history of the object to its origin.

handler - The callback handler.

Throws:

ClientException

getLocationSegments

java.util.List<ISVNRemote.LocationSegment> getLocationSegments(java.lang.String path,
                                                               long pegRevision,
                                                               long startRevision,
                                                               long endRevision)
                                                        throws ClientException

Return a list of segments in the location history of path at pegRevision, working backwards in time from startRevision to endRevision.

Parameters:

path - A session-relative path.

pegRevision - The peg revision to find path in.

startRevision - The upper bound of the revision range. Use Revision.SVN_INVALID_REVNUM to indicate HEAD.

endRevision - The lower bound of the revision range. Use Revision.SVN_INVALID_REVNUM to trace the history of the object to its origin.

Throws:

ClientException

getFileRevisions

void getFileRevisions(java.lang.String path,
                      long startRevision,
                      long endRevision,
                      boolean includeMergedRevisions,
                      RemoteFileRevisionsCallback handler)
               throws ClientException

Call handler for each of a subset of the interesting revisions of a file path as seen in revision endRevision.

If there is an interesting revision of the file that is less than or equal to startRevision, the iteration will begin at that revision. Otherwise the iteration will begin at the first revision of the file in the repository, which has to be less than or equal to endRevision. Note that if the function succeeds, handler will be called at least once.

Note: This functionality is not available in pre-1.1 servers. If the server doesn't implement it, an alternative (but much slower) implementation based on getLog(java.lang.Iterable<java.lang.String>, long, long, int, boolean, boolean, boolean, java.lang.Iterable<java.lang.String>, org.apache.subversion.javahl.callback.LogMessageCallback) is used.

Note: With Subversion 1.8 and newer servers this function supports reversion of the revision range for when includeMergedRevisions is false.

Parameters:

path - A path relative to the session URL.

startRevision - The lower bound of the revision interval.

endRevision - the upper bound of the revision interval.

includeMergedRevisions - When true, revisions that contributed to a merge are included in the result.

Throws:

ClientException

getFileRevisions

java.util.List<ISVNRemote.FileRevision> getFileRevisions(java.lang.String path,
                                                         long startRevision,
                                                         long endRevision,
                                                         boolean includeMergedRevisions)
                                                  throws ClientException

Retrieve a subset of the interesting revisions of a file path as seen in revision endRevision.

If there is an interesting revision of the file that is less than or equal to startRevision, the iteration will begin at that revision. Otherwise the iteration will begin at the first revision of the file in the repository, which has to be less than or equal to endRevision. Note that if the function succeeds, the returned list will contain at least one element.

Note: This functionality is not available in pre-1.1 servers. If the server doesn't implement it, an alternative (but much slower) implementation based on getLog(java.lang.Iterable<java.lang.String>, long, long, int, boolean, boolean, boolean, java.lang.Iterable<java.lang.String>, org.apache.subversion.javahl.callback.LogMessageCallback) is used.

Note: With Subversion 1.8 and newer servers this function supports reversion of the revision range for when includeMergedRevisions is false.

Parameters:

path - A path relative to the session URL.

startRevision - The lower bound of the revision interval.

endRevision - the upper bound of the revision interval.

includeMergedRevisions - When true, revisions that contributed to a merge are included in the result.

Throws:

ClientException

getLocks

java.util.Map<java.lang.String,Lock> getLocks(java.lang.String path,
                                              Depth depth)
                                       throws ClientException

Return a dictionary containing all locks on or below the given path.

Note: It is not considered an error if path does not exist in HEAD. Such a search will simply return no locks.

Note:This functionality is not available in pre-1.2 servers.

Parameters:

path - A path relative to the sessionn URL

depth - The recursion depth

Throws:

ClientException

hasCapability

boolean hasCapability(ISVNRemote.Capability capability)
               throws ClientException

Check if the server associated with this session has the given capability.

Throws:

ClientException