org.tmatesoft.svn.core.wc2

## Class SvnLog

- java.lang.Object
- - org.tmatesoft.svn.core.wc2.SvnOperation<T>
  - - org.tmatesoft.svn.core.wc2.SvnReceivingOperation<SVNLogEntry>
    - - org.tmatesoft.svn.core.wc2.SvnLog

- All Implemented Interfaces:
    ISvnObjectReceiver<SVNLogEntry>, ISvnOperationOptionsProvider

      public class SvnLog
      extends SvnReceivingOperation<SVNLogEntry>

  Represents log operation. Gets commit log messages with other revision specific information for `target`' paths(`targetPaths`) from a repository and returns them as list of `SVNLogEntry` items. Useful for observing the history of affected paths, author, date and log comments information per revision. `Target` can represent one repository URL with list of relative paths - `targetPaths` or many targets representing working copy paths can be provided, and `targetPaths` should not be set. Operation finds root URL of the working copy paths, and calculates relative`targetPaths` for them. Operation creates `SVNLogEntry` item on each log message from `startRevision` to `endRevision` in turn, inclusive (but never creates item on a given log message more than once).

  Log entries are created only on messages whose revisions involved a change to some path in `targetPaths`. `Targets`' `pegRevisions` indicates in which revision `targetPaths`' paths are valid. If `target`'s `pegRevision` is `invalid`, it defaults to `SVNRevision.WORKING` if `target` is working copy path, or `SVNRevision.HEAD` if `target` is URL.

  If `limit` is non-zero, only creates first `limit` log entries.

  If `discoverChangedPaths` is set, then the changed paths `Map` argument will be passed to a constructor of `SVNLogEntry` on each invocation of `handler`.

  If `stopOnCopy` is set, copy history (if any exists) will not be traversed while harvesting revision logs for each `targetPath`.

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

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

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

  For every `SvnRevisionRange` in `revisionRanges`: If `startRevision` is `valid` but `endRevision` is not, then `endRevision` defaults to `startRevision`. If both `startRevision` and `endRevision` are invalid, then `endRevision` defaults to revision `0`, and `startRevision` defaults either to `target`'s `pegRevision` in case the latter one is valid, or to `SVNRevision.BASE`, if it is not.

  Important: to avoid an exception with the `SVNErrorCode.FS_NO_SUCH_REVISION` error code when invoked against an empty repository (i.e. one not containing a revision 1), callers should specify the range `SVNRevision.HEAD`:`0`.

  If the caller has provided a non-`null` `ISVNEventHandler`, it will be called with the `SVNEventAction.SKIP` event action on any unversioned paths.

  Note: this routine requires repository access. `SvnOperation.run()` method throws `SVNException` in if one of the following is true:
  - a path is not under version control
  - can not obtain a URL of a working copy path
  - `paths` contain entries that belong to different repositories
  See Also:
    `SVNLogEntry`

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `SvnLog(SvnOperationFactory factory)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addRange(SvnRevisionRange range)` Adds the revision range to the operation's revision ranges.
    `protected void` | `ensureArgumentsAreValid()`
    `long` | `getLimit()` Returns a maximum number of log entries to be processed
    `protected int` | `getMaximumTargetsCount()`
    `java.lang.String[]` | `getRevisionProperties()` Returns what properties should be retrieved.
    `java.util.Collection<SvnRevisionRange>` | `getRevisionRanges()` Returns all revision ranges for those log should be reported.
    `java.lang.String[]` | `getTargetPaths()` Returns all relative paths what should be reported for each `target`.
    `boolean` | `isChangesWorkingCopy()` Gets whether the operation changes working copy
    `boolean` | `isDiscoverChangedPaths()` Returns whether to report of all changed paths for every revision being processed If `true` then the changed paths `Map` argument will be passed to a constructor of `SVNLogEntry`.
    `boolean` | `isStopOnCopy()` Returns whether to copy history (if any exists) should be traversed while harvesting revision logs for each `targetPath`.
    `boolean` | `isUseMergeHistory()` Returns whether the log information for revisions which have been merged to `targetPaths` will also be returned.
    `void` | `setDiscoverChangedPaths(boolean discoverChangedPaths)` Sets whether to report of all changed paths for every revision being processed If `true` then the changed paths `Map` argument will be passed to a constructor of `SVNLogEntry`.
    `void` | `setLimit(long limit)` Sets a maximum number of log entries to be processed
    `void` | `setRevisionProperties(java.lang.String[] revisionProperties)` Sets what properties should be retrieved.
    `void` | `setRevisionRanges(java.util.Collection<SvnRevisionRange> revisionRanges)` Sets all revision ranges for those log should be reported.
    `void` | `setStopOnCopy(boolean stopOnCopy)` Sets whether to copy history (if any exists) should be traversed while harvesting revision logs for each `targetPath`.
    `void` | `setTargetPaths(java.lang.String[] targetPaths)` Sets all relative paths what should be reported for each `target`.
    `void` | `setUseMergeHistory(boolean useMergeHistory)` Sets whether the log information for revisions which have been merged to `targetPaths` will also be returned.

    - ### Methods inherited from class org.tmatesoft.svn.core.wc2.SvnReceivingOperation

      `first, getReceiver, initDefaults, last, receive, run, setReceiver`

    - ### Methods inherited from class org.tmatesoft.svn.core.wc2.SvnOperation

      `addTarget, cancel, ensureEnoughTargets, ensureHomohenousTargets, getApplicableChangelists, getAuthenticationManager, getCanceller, getDepth, getEventHandler, getFirstTarget, getMinimumTargetsCount, getOperationalWorkingCopy, getOperationFactory, getOptions, getRepositoryPool, getRevision, getSqliteJournalMode, getTargets, hasFileTargets, hasLocalTargets, hasRemoteTargets, isCancelled, isSleepForTimestamp, isUseParentWcFormat, needsHomohenousTargets, run, setApplicalbeChangelists, setDepth, setRevision, setSingleTarget, setSleepForTimestamp, setSqliteJournalMode`

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

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

- - ### Constructor Detail

    - #### SvnLog

          protected SvnLog(SvnOperationFactory factory)

  - ### Method Detail

    - #### getLimit

          public long getLimit()

      Returns a maximum number of log entries to be processed
      Returns:
        maximum number of entries

    - #### setLimit

          public void setLimit(long limit)

      Sets a maximum number of log entries to be processed
      Parameters:
        `limit` - maximum number of entries

    - #### isUseMergeHistory

          public boolean isUseMergeHistory()

      Returns whether the log information for revisions which have been merged to `targetPaths` will also be returned.
      Returns:
        `true` if merged revisions should be also reported, otherwise `false`

    - #### setUseMergeHistory

          public void setUseMergeHistory(boolean useMergeHistory)

      Sets whether the log information for revisions which have been merged to `targetPaths` will also be returned.
      Parameters:
        `useMergeHistory` - `true` if merged revisions should be also reported, otherwise `false`

    - #### isDiscoverChangedPaths

          public boolean isDiscoverChangedPaths()

      Returns whether to report of all changed paths for every revision being processed If `true` then the changed paths `Map` argument will be passed to a constructor of `SVNLogEntry`.
      Returns:
        `true` if all changed paths for every revision being processed should be reported, otherwise `false`

    - #### setDiscoverChangedPaths

          public void setDiscoverChangedPaths(boolean discoverChangedPaths)

      Sets whether to report of all changed paths for every revision being processed If `true` then the changed paths `Map` argument will be passed to a constructor of `SVNLogEntry`.
      Parameters:
        `discoverChangedPaths` - `true` if all changed paths for every revision being processed should be reported, otherwise `false`

    - #### isStopOnCopy

          public boolean isStopOnCopy()

      Returns whether to copy history (if any exists) should be traversed while harvesting revision logs for each `targetPath`.
      Returns:
        `true` if not to cross copies while traversing history, otherwise copies history will be also included into processing

    - #### setStopOnCopy

          public void setStopOnCopy(boolean stopOnCopy)

      Sets whether to copy history (if any exists) should be traversed while harvesting revision logs for each `targetPath`.
      Parameters:
        `stopOnCopy` - `true` if not to cross copies while traversing history, otherwise copies history will be also included into processing

    - #### getRevisionRanges

          public java.util.Collection<SvnRevisionRange> getRevisionRanges()

      Returns all revision ranges for those log should be reported.
      Returns:
        collection of `SVNRevisionRange` objects

    - #### setRevisionRanges

          public void setRevisionRanges(java.util.Collection<SvnRevisionRange> revisionRanges)

      Sets all revision ranges for those log should be reported.
      Parameters:
        `revisionRanges` - collection of `SVNRevisionRange` objects

    - #### getTargetPaths

          public java.lang.String[] getTargetPaths()

      Returns all relative paths what should be reported for each `target`.
      Returns:
        relative paths of the `target`

    - #### setTargetPaths

          public void setTargetPaths(java.lang.String[] targetPaths)

      Sets all relative paths what should be reported for each `target`.
      Parameters:
        `targetPaths` - relative paths of the `target`

    - #### getRevisionProperties

          public java.lang.String[] getRevisionProperties()

      Returns what properties should be retrieved. If `revisionProperties` is `null`, retrieves all revision properties; else retrieves only the revision properties named in the array (i.e. retrieves none if the array is empty).
      Returns:
        array of names of the properties

    - #### setRevisionProperties

          public void setRevisionProperties(java.lang.String[] revisionProperties)

      Sets what properties should be retrieved. If `revisionProperties` is `null`, retrieves all revision properties; else retrieves only the revision properties named in the array (i.e. retrieves none if the array is empty).
      Parameters:
        `revisionProperties` - array of names of the properties

    - #### ensureArgumentsAreValid

          protected void ensureArgumentsAreValid()
                                          throws SVNException

      Overrides:
        `ensureArgumentsAreValid` in class `SvnOperation<SVNLogEntry>`
      Throws:
        `SVNException`

    - #### addRange

          public void addRange(SvnRevisionRange range)

      Adds the revision range to the operation's revision ranges.
      Parameters:
        `range` - revision range

    - #### getMaximumTargetsCount

          protected int getMaximumTargetsCount()

      Overrides:
        `getMaximumTargetsCount` in class `SvnOperation<SVNLogEntry>`

    - #### isChangesWorkingCopy

          public boolean isChangesWorkingCopy()

      Gets whether the operation changes working copy
      Overrides:
        `isChangesWorkingCopy` in class `SvnOperation<SVNLogEntry>`
      Returns:
        `true` if the operation changes the working copy, otherwise `false`