org.tmatesoft.svn.core

## Class SVNAnnotationGenerator

- java.lang.Object
- - org.tmatesoft.svn.core.SVNAnnotationGenerator

All Implemented Interfaces:
  ISVNDeltaConsumer, ISVNFileRevisionHandler

    public class SVNAnnotationGenerator
    extends java.lang.Object
    implements ISVNFileRevisionHandler

The SVNAnnotationGenerator class is used to annotate files - that is to place author and revision information in-line for the specified file.

Since SVNAnnotationGenerator implements ISVNFileRevisionHandler, it is merely passed to a `getFileRevisions()` method of SVNRepository. After that you handle the resultant annotated file line-by-line providing an ISVNAnnotateHandler implementation to the `reportAnnotations()` method:

     import org.tmatesoft.svn.core.SVNAnnotationGenerator;
     import org.tmatesoft.svn.core.io.SVNRepositoryFactory;
     import org.tmatesoft.svn.core.io.SVNRepository;
     import org.tmatesoft.svn.core.wc.SVNAnnotateHandler;
     ...

         File tmpFile;
         SVNRepository repos;
         ISVNAnnotateHandler annotateHandler;
         ISVNEventHandler cancelHandler;
         long startRev = 0;
         long endRev = 150;
         ...

         SVNAnnotationGenerator generator = new SVNAnnotationGenerator(path, tmpFile, cancelHandler);
         try {
             repos.getFileRevisions("", startRev, endRev, generator);
             generator.reportAnnotations(annotateHandler, null);
         } finally {
             generator.dispose();
         }
     ...

Since:
  1.2
Version:
  1.3
Author:
  TMate Software Ltd.

### Constructor Summary

Constructors
Constructor and Description
`SVNAnnotationGenerator(java.lang.String path, java.io.File tmpDirectory, long startRevision, boolean force, boolean includeMergedRevisions, SVNDiffOptions diffOptions, java.lang.String encoding, ISVNAnnotateHandler handler, ISVNEventHandler cancelBaton)` Constructs an annotation generator object.
`SVNAnnotationGenerator(java.lang.String path, java.io.File tmpDirectory, long startRevision, boolean force, ISVNEventHandler cancelBaton)` Constructs an annotation generator object.
`SVNAnnotationGenerator(java.lang.String path, java.io.File tmpDirectory, long startRevision, boolean force, SVNDiffOptions diffOptions, ISVNEventHandler cancelBaton)` Constructs an annotation generator object.
`SVNAnnotationGenerator(java.lang.String path, java.io.File tmpDirectory, long startRevision, ISVNEventHandler cancelBaton)` Constructs an annotation generator object.

### Method Summary

Methods
`void` `addFileBlame(java.io.InputStream contents)`
`void` `applyTextDelta(java.lang.String token, java.lang.String baseChecksum)` Creates a temporary file for delta application.
`void` `closeRevision(java.lang.String token)` Does nothing.
`void` `dispose()` Finalizes an annotation operation releasing resources involved by this generator.
`boolean` `isLastRevisionReported()` This method is used by `SVNKit` internals and is not intended for API users.
`void` `openRevision(SVNFileRevision fileRevision)` Handles a next revision.
`void` `reportAnnotations(ISVNAnnotateHandler handler, java.lang.String inputEncoding)` Dispatches file lines along with author & revision info to the provided annotation handler.
`java.io.OutputStream` `textDeltaChunk(java.lang.String token, SVNDiffWindow diffWindow)` Applies a next text delta chunk.
`void` `textDeltaEnd(java.lang.String token)` Marks the end of the text delta series.

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

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

### Constructor Detail

#### SVNAnnotationGenerator

    public SVNAnnotationGenerator(java.lang.String path,
                          java.io.File tmpDirectory,
                          long startRevision,
                          ISVNEventHandler cancelBaton)

Constructs an annotation generator object.

This constructor is equivalent to `SVNAnnotationGenerator(path, tmpDirectory, startRevision, false, cancelBaton)`.

Parameters:
  `path` - a file path (relative to a repository location)
  `tmpDirectory` - a revision to stop at
  `startRevision` - a start revision to begin annotation with
  `cancelBaton` - a baton which is used to check if an operation is cancelled

#### SVNAnnotationGenerator

    public SVNAnnotationGenerator(java.lang.String path,
                          java.io.File tmpDirectory,
                          long startRevision,
                          boolean force,
                          ISVNEventHandler cancelBaton)

Constructs an annotation generator object.

This constructor is identical to `SVNAnnotationGenerator(path, tmpDirectory, startRevision, force, new SVNDiffOptions(), cancelBaton)`.

Parameters:
  `path` - a file path (relative to a repository location)
  `tmpDirectory` - a revision to stop at
  `startRevision` - a start revision to begin annotation with
  `force` - forces binary files processing
  `cancelBaton` - a baton which is used to check if an operation is cancelled

#### SVNAnnotationGenerator

    public SVNAnnotationGenerator(java.lang.String path,
                          java.io.File tmpDirectory,
                          long startRevision,
                          boolean force,
                          SVNDiffOptions diffOptions,
                          ISVNEventHandler cancelBaton)

Constructs an annotation generator object.

This constructor is identical to `SVNAnnotationGenerator(path, tmpDirectory, startRevision, force, false, diffOptions, null, null, cancelBaton)`.

Parameters:
  `path` - a file path (relative to a repository location)
  `tmpDirectory` - a revision to stop at
  `startRevision` - a start revision to begin annotation with
  `force` - forces binary files processing
  `diffOptions` - diff options
  `cancelBaton` - a baton which is used to check if an operation is cancelled

#### SVNAnnotationGenerator

    public SVNAnnotationGenerator(java.lang.String path,
                          java.io.File tmpDirectory,
                          long startRevision,
                          boolean force,
                          boolean includeMergedRevisions,
                          SVNDiffOptions diffOptions,
                          java.lang.String encoding,
                          ISVNAnnotateHandler handler,
                          ISVNEventHandler cancelBaton)

Constructs an annotation generator object.

Parameters:
  `path` - a file path (relative to a repository location)
  `tmpDirectory` - a revision to stop at
  `startRevision` - a start revision to begin annotation with
  `force` - forces binary files processing
  `includeMergedRevisions` - whether to include merged revisions or not
  `diffOptions` - diff options
  `encoding` - charset name to use to encode annotation result
  `handler` - caller's annotation handler implementation
  `cancelBaton` - a baton which is used to check if an operation is cancelled
Since:
  1.2.0

### Method Detail

#### openRevision

    public void openRevision(SVNFileRevision fileRevision)
                      throws SVNException

Handles a next revision.

Specified by:
  `openRevision` in interface `ISVNFileRevisionHandler`
Parameters:
  `fileRevision` -
Throws:
  `SVNException` - if one of the following occurs:
  - exception with `SVNErrorCode.CLIENT_IS_BINARY_FILE` error code - if the file is binary and no forcing is specified
  - operation is cancelled
See Also:
  `SVNFileRevision`

#### closeRevision

    public void closeRevision(java.lang.String token)
                       throws SVNException

Does nothing.

Specified by:
  `closeRevision` in interface `ISVNFileRevisionHandler`
Parameters:
  `token` -
Throws:
  `SVNException`

#### applyTextDelta

    public void applyTextDelta(java.lang.String token,
                      java.lang.String baseChecksum)
                        throws SVNException

Creates a temporary file for delta application.

Specified by:
  `applyTextDelta` in interface `ISVNDeltaConsumer`
Parameters:
  `token` - not used in this method
  `baseChecksum` - not used in this method
Throws:
  `SVNException`

#### textDeltaChunk

    public java.io.OutputStream textDeltaChunk(java.lang.String token,
                                      SVNDiffWindow diffWindow)
                                        throws SVNException

Applies a next text delta chunk.

Specified by:
  `textDeltaChunk` in interface `ISVNDeltaConsumer`
Parameters:
  `token` - not used in this method
  `diffWindow` - next diff window
Returns:
  dummy output stream
Throws:
  `SVNException`

#### textDeltaEnd

    public void textDeltaEnd(java.lang.String token)
                      throws SVNException

Marks the end of the text delta series.

Specified by:
  `textDeltaEnd` in interface `ISVNDeltaConsumer`
Parameters:
  `token` - not used in this method
Throws:
  `SVNException`

#### addFileBlame

    public void addFileBlame(java.io.InputStream contents)
                      throws SVNException

Throws:
  `SVNException`

#### isLastRevisionReported

    public boolean isLastRevisionReported()

This method is used by `SVNKit` internals and is not intended for API users.

Returns:
  whether the last revision was reported or not yet
Since:
  1.2.0

#### reportAnnotations

    public void reportAnnotations(ISVNAnnotateHandler handler,
                         java.lang.String inputEncoding)
                           throws SVNException

Dispatches file lines along with author & revision info to the provided annotation handler.

If `inputEncoding` is null then "file.encoding" system property is used.

Parameters:
  `handler` - an annotation handler that processes file lines with author & revision info
  `inputEncoding` - a desired character set (encoding) of text lines
Throws:
  `SVNException`

#### dispose

    public void dispose()

Finalizes an annotation operation releasing resources involved by this generator. Should be called after `reportAnnotations()`.