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 */
020 package org.sonar.api.batch.fs;
021
022 import org.sonar.api.BatchComponent;
023
024 import javax.annotation.CheckForNull;
025
026 import java.io.File;
027 import java.nio.charset.Charset;
028 import 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("src/foo/bar.php"));
052 * </pre>
053 *
054 * @since 4.2
055 */
056 public interface FileSystem extends BatchComponent {
057
058 /**
059 * Absolute base directory of module
060 */
061 File baseDir();
062
063 /**
064 * Default encoding of input files. If it's not defined, then
065 * the platform default encoding is returned
066 */
067 Charset encoding();
068
069 /**
070 * Absolute work directory. It can be used to
071 * store third-party analysis reports.
072 * <p/>
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 * @throw {@link IllegalArgumentException} is File is null or not a directory.
102 *
103 * @since 4.5
104 */
105 @CheckForNull
106 InputDir inputDir(File dir);
107
108 /**
109 * Input files matching the given attributes. Return all the files if the parameter
110 * <code>attributes</code> is empty.
111 * <p/>
112 * <b>Important</b> - result is an {@link java.lang.Iterable} to benefit from streaming and decreasing
113 * memory consumption. It should be iterated only once, else copy it into a list :
114 * {@code com.google.common.collect.Lists.newArrayList(inputFiles(predicate))}
115 * <p/>
116 * How to use :
117 * <pre>
118 * FilePredicates p = fs.predicates();
119 * Iterable<InputFile> files = fs.inputFiles(p.and(p.hasLanguage("java"), p.hasType(InputFile.Type.MAIN)));
120 * </pre>
121 *
122 * @see #predicates()
123 */
124 Iterable<InputFile> inputFiles(FilePredicate predicate);
125
126 /**
127 * Returns true if at least one {@link org.sonar.api.batch.fs.InputFile} matches
128 * the given predicate. This method can be faster than checking if {@link #inputFiles(org.sonar.api.batch.fs.FilePredicate)}
129 * has elements.
130 * @see #predicates()
131 */
132 boolean hasFiles(FilePredicate predicate);
133
134 /**
135 * Files matching the given predicate.
136 * @see #predicates()
137 */
138 Iterable<File> files(FilePredicate predicate);
139
140 /**
141 * Languages detected in all files, whatever their type (main or test)
142 */
143 SortedSet<String> languages();
144
145 /**
146 * Interface of the underlying file index.
147 */
148 public static interface Index {
149 Iterable<InputFile> inputFiles();
150
151 @CheckForNull
152 InputFile inputFile(String relativePath);
153
154 @CheckForNull
155 InputDir inputDir(String relativePath);
156 }
157 }