001/*
002 * SonarQube
003 * Copyright (C) 2009-2017 SonarSource SA
004 * mailto:info AT sonarsource DOT com
005 *
006 * This program is free software; you can redistribute it and/or
007 * modify it under the terms of the GNU Lesser General Public
008 * License as published by the Free Software Foundation; either
009 * version 3 of the License, or (at your option) any later version.
010 *
011 * This program is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 * Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with this program; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
019 */
020package org.sonar.api.batch.fs;
021
022import java.io.File;
023import java.nio.charset.Charset;
024import java.util.SortedSet;
025import javax.annotation.CheckForNull;
026import org.sonar.api.batch.ScannerSide;
027
028/**
029 * The {@link FileSystem} manages all the source files to be analyzed.
030 * <p>
031 * This is not an extension point so it must not be implemented by plugins. It must be injected as a
032 * constructor parameter :
033 * <pre>
034 * public class MySensor implements Sensor {
035 *   private final FileSystem fs;
036 *
037 *   public MySensor(FileSystem fs) {
038 *     this.fs = fs;
039 *   }
040 * }
041 * </pre>
042 *
043 * <h2>How to use in unit tests</h2>
044 * The unit tests needing an instance of FileSystem can use the implementation
045 * {@link org.sonar.api.batch.fs.internal.DefaultFileSystem} and the related {@link org.sonar.api.batch.fs.internal.DefaultInputFile},
046 * for example :
047 * <pre>
048 * DefaultFileSystem fs = new DefaultFileSystem();
049 * fs.add(new DefaultInputFile("myprojectKey", "src/foo/bar.php"));
050 * </pre>
051 *
052 * @since 4.2
053 */
054@ScannerSide
055public interface FileSystem {
056
057  /**
058   * Absolute base directory of module.
059   */
060  File baseDir();
061
062  /**
063   * Default encoding of files in this project. If it's not defined, then
064   * the platform default encoding is returned.
065   * When reading an {@link InputFile} it is preferable to use {@link InputFile#charset()} 
066   */
067  Charset encoding();
068
069  /**
070   * Absolute work directory. It can be used to
071   * store third-party analysis reports.
072   * <br>
073   * The work directory can be located outside {@link #baseDir()}.
074   */
075  File workDir();
076
077  /**
078   * Factory of {@link FilePredicate}
079   */
080  FilePredicates predicates();
081
082  /**
083   * Returns the single element matching the predicate. If more than one elements match
084   * the predicate, then {@link IllegalArgumentException} is thrown. Returns {@code null}
085   * if no files match.
086   *
087   * <p>
088   * How to use :
089   * <pre>
090   * InputFile file = fs.inputFile(fs.predicates().hasRelativePath("src/Foo.php"));
091   * </pre>
092   *
093   * @see #predicates()
094   */
095  @CheckForNull
096  InputFile inputFile(FilePredicate predicate);
097
098  /**
099   * Returns {@link InputDir} matching the current {@link File}.
100   * @return null if directory is not indexed.
101   * @throws IllegalArgumentException is File is null or not a directory.
102   * 
103   * @since 4.5
104   * @deprecated since 6.6 Ability to report issues or measures on directories will soon be dropped. Report issues on project if needed. 
105   */
106  @Deprecated
107  @CheckForNull
108  InputDir inputDir(File dir);
109
110  /**
111   * Input files matching the given attributes. Return all the files if the parameter
112   * <code>attributes</code> is empty.
113   * <p>
114   * <b>Important</b> - result is an {@link java.lang.Iterable} to benefit from streaming and decreasing
115   * memory consumption. It should be iterated only once, else copy it into a list :
116   * {@code com.google.common.collect.Lists.newArrayList(inputFiles(predicate))}
117   * <p>
118   * How to use :
119   * <pre>
120   * {@code
121   * FilePredicates p = fs.predicates();
122   * Iterable<InputFile> files = fs.inputFiles(p.and(p.hasLanguage("java"), p.hasType(InputFile.Type.MAIN)));
123   * }
124   * </pre>
125   *
126   * @see #predicates()
127   */
128  Iterable<InputFile> inputFiles(FilePredicate predicate);
129
130  /**
131   * Returns true if at least one {@link org.sonar.api.batch.fs.InputFile} matches
132   * the given predicate. This method can be faster than checking if {@link #inputFiles(org.sonar.api.batch.fs.FilePredicate)}
133   * has elements.
134   * @see #predicates()
135   */
136  boolean hasFiles(FilePredicate predicate);
137
138  /**
139   * Files matching the given predicate.
140   * @see #predicates()
141   * @deprecated since 6.6 Plugins should avoid working with {@link File} and prefer working with {@link InputFile}
142   */
143  @Deprecated
144  Iterable<File> files(FilePredicate predicate);
145
146  /**
147   * Languages detected in all files, whatever their type (main or test)
148   */
149  SortedSet<String> languages();
150
151  /**
152   * Utility method mainly used to resolve location of reports.
153   * @return file in canonical form from specified path. Path can be absolute or relative to project basedir.
154   *         For example resolvePath("pom.xml") or resolvePath("src/main/java")
155   * @since 5.0
156   */
157  File resolvePath(String path);
158
159  /**
160   * Interface of the underlying file index.
161   */
162  interface Index {
163    Iterable<InputFile> inputFiles();
164
165    @CheckForNull
166    InputFile inputFile(String relativePath);
167
168    @CheckForNull
169    InputDir inputDir(String relativePath);
170
171    /**
172     * @since 6.3
173     */
174    Iterable<InputFile> getFilesByName(String filename);
175
176    /**
177     * @since 6.3
178     */
179    Iterable<InputFile> getFilesByExtension(String extension);
180  }
181}