001/* 002 * SonarQube 003 * Copyright (C) 2009-2018 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}