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
    Modifier and Type | Method and Description
    --- | ---
    `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) or URL-encoded URL
        `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()`.