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
`protected` `SvnLog(SvnOperationFactory factory)`

### Method Summary

Methods
`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, getTargets, hasFileTargets, hasLocalTargets, hasRemoteTargets, isCancelled, isSleepForTimestamp, isUseParentWcFormat, needsHomohenousTargets, run, setApplicalbeChangelists, setDepth, setRevision, setSingleTarget, setSleepForTimestamp`

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