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
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
 void cancelOperation()
          Cancel the active operation, including any ongoing edits.
 void changeRevisionProperty(long revision, String propertyName, byte[] oldValue, byte[] newValue)
          Change the value of an unversioned property.
 NodeKind checkPath(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(Map<String,byte[]> revisionProperties, CommitCallback commitCallback, Set<Lock> lockTokens, boolean keepLocks)
          Like #getCommitEditor(Map,CommitCallback, but with all callbacks set to null.
 ISVNEditor getCommitEditor(Map<String,byte[]> revisionProperties, CommitCallback commitCallback, 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, String path, int direntFields, Map<String,DirEntry> dirents, Map<String,byte[]> properties)
          Fetch the contents and properties of directory path at revision.
 long getFile(long revision, String path, OutputStream contents, Map<String,byte[]> properties)
          Fetch the contents and properties of file path at revision.
 List<ISVNRemote.FileRevision> getFileRevisions(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(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.
 Map<Long,String> getLocations(String path, long pegRevision, Iterable<Long> locationRevisions)
          Find the locations of the object identified by path and pegRevision in the repository at the given revisions.
 List<ISVNRemote.LocationSegment> getLocationSegments(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(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.
 Map<String,Lock> getLocks(String path, Depth depth)
          Return a dictionary containing all locks on or below the given path.
 void getLog(Iterable<String> paths, long startRevision, long endRevision, int limit, boolean strictNodeHistory, boolean discoverPath, boolean includeMergedRevisions, Iterable<String> revisionProperties, LogMessageCallback callback)
          Invoke callback for each log message from startRevision to endRevision.
 Map<String,Mergeinfo> getMergeinfo(Iterable<String> paths, long revision, Mergeinfo.Inheritance inherit, boolean includeDescendants)
          Retrieve the merginfo for paths, whose elements are relative to the session's URL.
 String getReposRelativePath(String url)
          Return a path relative to the repository root URL associated with current session URL.
 String getReposRootUrl()
          Get the root URL of the session's repository.
 String getReposUUID()
          Get the UUID of the session's repository.
 long getRevisionByDate(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.
 Map<String,byte[]> getRevisionProperties(long revision)
          Return the set of unversioned properties set on revision in the session's repository.
 byte[] getRevisionProperty(long revision, String propertyName)
          Return the value of unversioned property propertyName in revision in the session's repository.
 String getSessionRelativePath(String url)
          Return a path relative to the current session URL.
 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(String url)
          Change the URL of the session to point to a new path in the same repository.
 DirEntry stat(String path, long revision)
          Return the directory entry object for path at revision.
 ISVNReporter status(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(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

String getSessionUrl()
                     throws ClientException
Get the current session URL.

Throws:
ClientException

getSessionRelativePath

String getSessionRelativePath(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

String getReposRelativePath(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

String getReposUUID()
                    throws ClientException
Get the UUID of the session's repository.

Throws:
ClientException

getReposRootUrl

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(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,
                            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:
IllegalArgumentException - if oldValue is not null and the server does not advertise the atomic_revprops capability.
ClientException

getRevisionProperties

Map<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,
                           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(Map<String,byte[]> revisionProperties,
                           CommitCallback commitCallback,
                           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(Map<String,byte[]> revisionProperties,
                           CommitCallback commitCallback,
                           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,
             String path,
             OutputStream contents,
             Map<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,
                  String path,
                  int direntFields,
                  Map<String,DirEntry> dirents,
                  Map<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

Map<String,Mergeinfo> getMergeinfo(Iterable<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(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(Iterable<String> paths,
            long startRevision,
            long endRevision,
            int limit,
            boolean strictNodeHistory,
            boolean discoverPath,
            boolean includeMergedRevisions,
            Iterable<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(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(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

Map<Long,String> getLocations(String path,
                              long pegRevision,
                              Iterable<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(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

List<ISVNRemote.LocationSegment> getLocationSegments(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(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, long, long, int, boolean, boolean, boolean, java.lang.Iterable, 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

List<ISVNRemote.FileRevision> getFileRevisions(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, long, long, int, boolean, boolean, boolean, java.lang.Iterable, 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

Map<String,Lock> getLocks(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