net.sf.statsvn.input

## Class Builder

- java.lang.Object
- - net.sf.statsvn.input.Builder

- All Implemented Interfaces:
    SvnLogBuilder

      public class Builder
      extends java.lang.Object
      implements SvnLogBuilder

  Helps building the `net.sf.statsvn.model.Repository` from a SVN log. The `Builder` is fed by some SVN history data source, for example a SVN log parser. The `Repository` can be retrieved using the `createRepository()` method.

  The class also takes care of the creation of `Author` and Directory objects and makes sure that there's only one of these for each author name and path. It also provides LOC count services.

  Version:
    $Id: Builder.java 389 2009-05-27 18:17:59Z benoitx $
  Author:
    Richard Cyganiak , Jason Kealey , Gunter Mussbacher

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Builder(RepositoryFileManager repositoryFileManager, net.sf.statcvs.util.FilePatternMatcher includePattern, net.sf.statcvs.util.FilePatternMatcher excludePattern, java.util.regex.Pattern tagsPattern)` Creates a new `Builder`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addToAttic(java.lang.String filename)` Adds a file to the attic.
    `void` | `buildFile(java.lang.String filename, boolean isBinary, boolean isInAttic, java.util.Map revBySymnames, java.util.Map dateBySymnames)` Starts building a new file.
    `void` | `buildModule(java.lang.String moduleName)` Starts building the module.
    `void` | `buildRevision(RevisionData data)` Adds a revision to the current file.
    `void` | `clean()`
    `net.sf.statcvs.model.Repository` | `createRepository()` Returns a Repository object of all files.
    `java.util.Set` | `getAtticFileNames()` Returns the `Set` of filenames that are "in the attic".
    `net.sf.statcvs.model.Author` | `getAuthor(java.lang.String name)` returns the `Author` of the given name or creates it if it does not yet exist.
    `net.sf.statcvs.model.Directory` | `getDirectory(java.lang.String filename)` Returns the `Directory` of the given filename or creates it if it does not yet exist.
    `java.util.Map` | `getFileBuilders()` New in StatSVN: We need to have access to FileBuilders after they have been created to populate them with version numbers later on.
    `int` | `getLOC(java.lang.String filename)`
    `java.lang.String` | `getProjectName()`
    `java.lang.String` | `getRevision(java.lang.String filename)`
    `net.sf.statcvs.model.SymbolicName` | `getSymbolicName(java.lang.String name, java.util.Date date)` Returns the `SymbolicName` with the given name or creates it if it does not yet exist.
    `boolean` | `matchesPatterns(java.lang.String filename)` Matches a filename against the include and exclude patterns.
    `boolean` | `matchesTagPatterns(java.lang.String tag)` Matches a tag against the tag patterns.
    `void` | `updateRevision(java.lang.String filename, java.lang.String revisionNumber, int linesAdded, int linesRemoved)` New in StatSVN: Updates a particular revision for a file with new line count information.

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

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

- - ### Constructor Detail

    - #### Builder

          public Builder(RepositoryFileManager repositoryFileManager,
                 net.sf.statcvs.util.FilePatternMatcher includePattern,
                 net.sf.statcvs.util.FilePatternMatcher excludePattern,
                 java.util.regex.Pattern tagsPattern)

      Creates a new `Builder`
      Parameters:
        `repositoryFileManager` - the `RepositoryFileManager` that can be used to retrieve LOC counts for the files that this builder will create
        `includePattern` - a list of Ant-style wildcard patterns, seperated by : or ;
        `excludePattern` - a list of Ant-style wildcard patterns, seperated by : or ;

  - ### Method Detail

    - #### clean

          public void clean()

    - #### addToAttic

          public void addToAttic(java.lang.String filename)

      Adds a file to the attic. This method should only be called if our first invocation to (@link #buildFile(String, boolean, boolean, Map)) was given an invalid isInAttic field. This is a hack to handle post-processing of implicit deletions at the same time as the implicit additions that can be found in Subversion.
      Specified by:
        `addToAttic` in interface `SvnLogBuilder`
      Parameters:
        `filename` - the filename to add to the attic.

    - #### buildFile

          public void buildFile(java.lang.String filename,
                       boolean isBinary,
                       boolean isInAttic,
                       java.util.Map revBySymnames,
                       java.util.Map dateBySymnames)

      Starts building a new file. The files are not expected to be created in any particular order. Subsequent calls to (@link #buildRevision(RevisionData)) will add revisions to this file.

      New in StatSVN: If the method has already been invoked with the same filename, the original file will be re-loaded and the other arguments are ignored.

      Specified by:
        `buildFile` in interface `SvnLogBuilder`
      Parameters:
        `filename` - the file's name with path, for example "path/file.txt"
        `isBinary` - `true` if it's a binary file
        `isInAttic` - `true` if the file is dead on the main branch
        `revBySymnames` - maps revision (string) by symbolic name (string)
        `dateBySymnames` - maps date (date) by symbolic name (string)

    - #### buildModule

          public void buildModule(java.lang.String moduleName)

      Starts building the module.
      Specified by:
        `buildModule` in interface `SvnLogBuilder`
      Parameters:
        `moduleName` - name of the module

    - #### buildRevision

          public void buildRevision(RevisionData data)

      Adds a revision to the current file. The revisions must be added in SVN logfile order, that is starting with the most recent one.
      Specified by:
        `buildRevision` in interface `SvnLogBuilder`
      Parameters:
        `data` - the revision

    - #### createRepository

          public net.sf.statcvs.model.Repository createRepository()

      Returns a Repository object of all files.
      Returns:
        Repository a Repository object

    - #### getAtticFileNames

          public java.util.Set getAtticFileNames()

      Returns the `Set` of filenames that are "in the attic".
      Returns:
        a `Set` of `String`s

    - #### getAuthor

          public net.sf.statcvs.model.Author getAuthor(java.lang.String name)

      returns the `Author` of the given name or creates it if it does not yet exist. Author names are handled as case-insensitive.
      Parameters:
        `name` - the author's name
      Returns:
        a corresponding `Author` object

    - #### getDirectory

          public net.sf.statcvs.model.Directory getDirectory(java.lang.String filename)

      Returns the `Directory` of the given filename or creates it if it does not yet exist.
      Parameters:
        `filename` - the name and path of a file, for example "src/Main.java"
      Returns:
        a corresponding `Directory` object

    - #### getFileBuilders

          public java.util.Map getFileBuilders()

      New in StatSVN: We need to have access to FileBuilders after they have been created to populate them with version numbers later on.
      Specified by:
        `getFileBuilders` in interface `SvnLogBuilder`
      Returns:
        this builder's contained (@link FileBuilder)s.

    - #### getLOC

          public int getLOC(java.lang.String filename)
                     throws net.sf.statcvs.input.NoLineCountException

      Throws:
        `net.sf.statcvs.input.NoLineCountException`
      See Also:
        `RepositoryFileManager.getLinesOfCode(String)`

    - #### getProjectName

          public java.lang.String getProjectName()

    - #### getRevision

          public java.lang.String getRevision(java.lang.String filename)
                                       throws java.io.IOException

      Throws:
        `java.io.IOException`
      See Also:
        `RepositoryFileManager.getRevision(String)`

    - #### getSymbolicName

          public net.sf.statcvs.model.SymbolicName getSymbolicName(java.lang.String name,
                                                          java.util.Date date)

      Returns the `SymbolicName` with the given name or creates it if it does not yet exist.
      Parameters:
        `name` - the symbolic name's name
      Returns:
        the corresponding symbolic name object

    - #### matchesPatterns

          public boolean matchesPatterns(java.lang.String filename)

      Matches a filename against the include and exclude patterns. If no include pattern was specified, all files will be included. If no exclude pattern was specified, no files will be excluded.
      Specified by:
        `matchesPatterns` in interface `SvnLogBuilder`
      Parameters:
        `filename` - a filename
      Returns:
        `true` if the filename matches one of the include patterns and does not match any of the exclude patterns. If it matches an include and an exclude pattern, `false` will be returned.

    - #### matchesTagPatterns

          public boolean matchesTagPatterns(java.lang.String tag)

      Matches a tag against the tag patterns.
      Specified by:
        `matchesTagPatterns` in interface `SvnLogBuilder`
      Parameters:
        `tag` - a tag
      Returns:
        `true` if the tag matches the tag pattern.

    - #### updateRevision

          public void updateRevision(java.lang.String filename,
                            java.lang.String revisionNumber,
                            int linesAdded,
                            int linesRemoved)

      New in StatSVN: Updates a particular revision for a file with new line count information. If the file or revision does not exist, action will do nothing. Necessary because line counts are not given in the log file and hence can only be added in a second pass.
      Specified by:
        `updateRevision` in interface `SvnLogBuilder`
      Parameters:
        `filename` - the file to be updated
        `revisionNumber` - the revision number to be updated
        `linesAdded` - the lines that were added
        `linesRemoved` - the lines that were removed