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.io.IOException; 024import java.io.InputStream; 025import java.nio.charset.Charset; 026import java.nio.file.Path; 027import javax.annotation.CheckForNull; 028import org.sonar.api.batch.fs.internal.TestInputFileBuilder; 029 030/** 031 * This layer over {@link java.io.File} adds information for code analyzers. 032 * For unit testing purpose, use {@link TestInputFileBuilder} and initialize 033 * the needed fields: 034 * 035 * <pre> 036 * new TestInputFileBuilder("moduleKey", "relative/path/from/module/baseDir.java") 037 * .setModuleBaseDir(path) 038 * .build(); 039 * </pre> 040 * 041 * @since 4.2 042 */ 043public interface InputFile extends IndexedFile { 044 045 enum Type { 046 MAIN, TEST 047 } 048 049 /** 050 * Status regarding previous analysis 051 */ 052 enum Status { 053 SAME, CHANGED, ADDED 054 } 055 056 /** 057 * Path relative to module base directory. Path is unique and identifies file 058 * within given <code>{@link FileSystem}</code>. File separator is the forward 059 * slash ('/'), even on Microsoft Windows. 060 * <br> 061 * Returns <code>src/main/java/com/Foo.java</code> if module base dir is 062 * <code>/path/to/module</code> and if file is 063 * <code>/path/to/module/src/main/java/com/Foo.java</code>. 064 * <br> 065 * Relative path is not null and is normalized ('foo/../foo' is replaced by 'foo'). 066 */ 067 @Override 068 String relativePath(); 069 070 /** 071 * Normalized absolute path. File separator is forward slash ('/'), even on Microsoft Windows. 072 * <br> 073 * This is not canonical path. Symbolic links are not resolved. For example if /project/src links 074 * to /tmp/src and basedir is /project, then this method returns /project/src/index.php. Use 075 * {@code file().getCanonicalPath()} to resolve symbolic link. 076 */ 077 @Override 078 String absolutePath(); 079 080 /** 081 * The underlying absolute {@link java.io.File}. It should not be used to read the file in the filesystem. 082 * @see #contents() 083 * @see #inputStream() 084 */ 085 @Override 086 File file(); 087 088 /** 089 * The underlying absolute {@link Path}. 090 * It should not be used to read the file in the filesystem. 091 * @see #contents() 092 * @see #inputStream() 093 * @since 5.1 094 */ 095 @Override 096 Path path(); 097 098 /** 099 * Language, for example "java" or "php". Can be null if indexation of all files is enabled and no language claims to support the file. 100 */ 101 @CheckForNull 102 @Override 103 String language(); 104 105 /** 106 * Does it contain main or test code ? 107 */ 108 @Override 109 Type type(); 110 111 /** 112 * Creates a stream of the file's contents. Depending on the runtime context, the source might be a file in a physical or virtual filesystem. 113 * Typically, it won't be buffered. <b>The stream must be closed by the caller</b>. 114 * Since 6.4 BOM is automatically filtered out. 115 * @since 6.2 116 */ 117 @Override 118 InputStream inputStream() throws IOException; 119 120 /** 121 * Fetches the entire contents of the file, decoding with the {@link #charset}. 122 * Since 6.4 BOM is automatically filtered out. 123 * @since 6.2 124 */ 125 String contents() throws IOException; 126 127 /** 128 * Status regarding previous analysis 129 */ 130 Status status(); 131 132 /** 133 * Number of physical lines. This method supports all end-of-line characters. Formula is (number of line break + 1). 134 * <p> 135 * Returns 1 if the file is empty. 136 * <br> 137 * Returns 2 for <tt>foo\nbar</tt>. 138 * <br> 139 * Returns 3 for <tt>foo\nbar\n</tt>. 140 */ 141 int lines(); 142 143 /** 144 * Check if the file content is empty (ignore potential BOM). 145 * @since 5.2 146 */ 147 boolean isEmpty(); 148 149 /** 150 * Returns a {@link TextPointer} in the given file. 151 * @param line Line of the pointer. Start at 1. 152 * @param lineOffset Offset in the line. Start at 0. 153 * @throws IllegalArgumentException if line or offset is not valid for the given file. 154 * @since 5.2 155 */ 156 TextPointer newPointer(int line, int lineOffset); 157 158 /** 159 * Returns a {@link TextRange} in the given file. 160 * @param start start pointer 161 * @param end end pointer 162 * @throws IllegalArgumentException if start or stop pointers are not valid for the given file. 163 * @since 5.2 164 */ 165 TextRange newRange(TextPointer start, TextPointer end); 166 167 /** 168 * Returns a {@link TextRange} in the given file. 169 * <ul> 170 * <li><code>newRange(1, 0, 1, 1)</code> selects the first character at line 1</li> 171 * <li><code>newRange(1, 0, 1, 10)</code> selects the 10 first characters at line 1</li> 172 * </ul> 173 * @throws IllegalArgumentException if start or stop positions are not valid for the given file. 174 * @since 5.2 175 */ 176 TextRange newRange(int startLine, int startLineOffset, int endLine, int endLineOffset); 177 178 /** 179 * Returns a {@link TextRange} in the given file that select the full line. 180 * @param line Start at 1. 181 * @throws IllegalArgumentException if line is not valid for the given file. 182 * @since 5.2 183 */ 184 TextRange selectLine(int line); 185 186 /** 187 * Charset to be used to decode this specific file. 188 * @since 6.0 189 */ 190 Charset charset(); 191}