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

  • Method Details

    • 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 {@link #getCommitEditor(Map,CommitCallbacknull.
      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<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

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

      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