001/*
002 * SonarQube, open source software quality management tool.
003 * Copyright (C) 2008-2014 SonarSource
004 * mailto:contact AT sonarsource DOT com
005 *
006 * SonarQube 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 * SonarQube 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 org.sonar.api.batch.BatchSide;
023
024import javax.annotation.CheckForNull;
025
026import java.io.File;
027import java.nio.charset.Charset;
028import java.util.SortedSet;
029
030/**
031 * The {@link FileSystem} manages all the source files to be analyzed.
032 * <p/>
033 * This is not an extension point so it must not be implemented by plugins. It must be injected as a
034 * constructor parameter :
035 * <pre>
036 * public class MySensor implements Sensor {
037 *   private final FileSystem fs;
038 *
039 *   public MySensor(FileSystem fs) {
040 *     this.fs = fs;
041 *   }
042 * }
043 * </pre>
044 *
045 * <h2>How to use in unit tests</h2>
046 * The unit tests needing an instance of FileSystem can use the implementation
047 * {@link org.sonar.api.batch.fs.internal.DefaultFileSystem} and the related {@link org.sonar.api.batch.fs.internal.DefaultInputFile},
048 * for example :
049 * <pre>
050 * DefaultFileSystem fs = new DefaultFileSystem();
051 * fs.add(new DefaultInputFile("myprojectKey", "src/foo/bar.php"));
052 * </pre>
053 *
054 * @since 4.2
055 */
056@BatchSide
057public interface FileSystem {
058
059  /**
060   * Absolute base directory of module
061   */
062  File baseDir();
063
064  /**
065   * Default encoding of input files. If it's not defined, then
066   * the platform default encoding is returned
067   */
068  Charset encoding();
069
070  /**
071   * Absolute work directory. It can be used to
072   * store third-party analysis reports.
073   * <p/>
074   * The work directory can be located outside {@link #baseDir()}.
075   */
076  File workDir();
077
078  /**
079   * Factory of {@link FilePredicate}
080   */
081  FilePredicates predicates();
082
083  /**
084   * Returns the single element matching the predicate. If more than one elements match
085   * the predicate, then {@link IllegalArgumentException} is thrown. Returns {@code null}
086   * if no files match.
087   *
088   * <p/>
089   * How to use :
090   * <pre>
091   * InputFile file = fs.inputFile(fs.predicates().hasRelativePath("src/Foo.php"));
092   * </pre>
093   *
094   * @see #predicates()
095   */
096  @CheckForNull
097  InputFile inputFile(FilePredicate predicate);
098
099  /**
100   * Returns {@link InputDir} matching the current {@link File}.
101   * @return null if directory is not indexed.
102   * @throw {@link IllegalArgumentException} is File is null or not a directory.
103   * 
104   * @since 4.5
105   */
106  @CheckForNull
107  InputDir inputDir(File dir);
108
109  /**
110   * Input files matching the given attributes. Return all the files if the parameter
111   * <code>attributes</code> is empty.
112   * <p/>
113   * <b>Important</b> - result is an {@link java.lang.Iterable} to benefit from streaming and decreasing
114   * memory consumption. It should be iterated only once, else copy it into a list :
115   * {@code com.google.common.collect.Lists.newArrayList(inputFiles(predicate))}
116   * <p/>
117   * How to use :
118   * <pre>
119   * FilePredicates p = fs.predicates();
120   * Iterable<InputFile> files = fs.inputFiles(p.and(p.hasLanguage("java"), p.hasType(InputFile.Type.MAIN)));
121   * </pre>
122   *
123   * @see #predicates()
124   */
125  Iterable<InputFile> inputFiles(FilePredicate predicate);
126
127  /**
128   * Returns true if at least one {@link org.sonar.api.batch.fs.InputFile} matches
129   * the given predicate. This method can be faster than checking if {@link #inputFiles(org.sonar.api.batch.fs.FilePredicate)}
130   * has elements.
131   * @see #predicates()
132   */
133  boolean hasFiles(FilePredicate predicate);
134
135  /**
136   * Files matching the given predicate.
137   * @see #predicates()
138   */
139  Iterable<File> files(FilePredicate predicate);
140
141  /**
142   * Languages detected in all files, whatever their type (main or test)
143   */
144  SortedSet<String> languages();
145
146  /**
147   * Utility method mainly used to resolve location of reports.
148   * @return file in canonical form from specified path. Path can be absolute or relative to project basedir.
149   *         For example resolvePath("pom.xml") or resolvePath("src/main/java")
150   * @since 5.0
151   */
152  File resolvePath(String path);
153
154  /**
155   * Interface of the underlying file index.
156   */
157  interface Index {
158    Iterable<InputFile> inputFiles();
159
160    @CheckForNull
161    InputFile inputFile(String relativePath);
162
163    @CheckForNull
164    InputDir inputDir(String relativePath);
165  }
166}