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}