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;
021
022 import org.sonar.api.batch.fs.InputFile;
023 import org.sonar.api.design.Dependency;
024 import org.sonar.api.measures.Measure;
025 import org.sonar.api.measures.MeasuresFilter;
026 import org.sonar.api.measures.Metric;
027 import org.sonar.api.resources.ProjectLink;
028 import org.sonar.api.resources.Resource;
029 import org.sonar.api.rules.Violation;
030
031 import javax.annotation.CheckForNull;
032
033 import java.io.Serializable;
034 import java.util.Collection;
035 import java.util.Date;
036 import java.util.List;
037 import java.util.Set;
038
039 /**
040 * @since 1.10
041 */
042 public interface SensorContext {
043
044 /**
045 * Indexes a resource as a direct child of project. This method does nothing and returns true if the resource already indexed.
046 *
047 * @return false if the resource is excluded
048 * @deprecated since 4.2 Resource indexing is done by the platform for all physical resources.
049 */
050 @Deprecated
051 boolean index(Resource resource);
052
053 /**
054 * Indexes a resource. This method does nothing if the resource is already indexed.
055 *
056 * @param resource the resource to index. Not nullable
057 * @param parentReference a reference to the parent. If null, the the resource is indexed as a direct child of project.
058 * @return false if the parent is not indexed or if the resource is excluded
059 * @deprecated since 4.2 Resource indexing is done by the platform for all physical resources.
060 */
061 @Deprecated
062 boolean index(Resource resource, Resource parentReference);
063
064 /**
065 * Returns true if the referenced resource is indexed and excluded.
066 *
067 * @since 2.6
068 * @deprecated since 4.2 Excluded resources are not indexed.
069 */
070 @Deprecated
071 boolean isExcluded(Resource reference);
072
073 /**
074 * Returns true if the referenced resource is indexed.
075 *
076 * @since 2.6
077 * @deprecated since 4.2 Excluded resources are not indexed.
078 */
079 @Deprecated
080 boolean isIndexed(Resource reference, boolean acceptExcluded);
081
082 /**
083 * Search for an indexed resource.
084 *
085 * @param reference the resource reference
086 * @return the indexed resource, null if it's not indexed
087 * @since 1.10. Generic types since 2.6.
088 */
089 @CheckForNull
090 <R extends Resource> R getResource(R reference);
091
092 /**
093 * @since 2.6
094 */
095 Resource getParent(Resource reference);
096
097 /**
098 * @since 2.6
099 */
100
101 Collection<Resource> getChildren(Resource reference);
102
103 // ----------- MEASURES ON PROJECT --------------
104
105 /**
106 * Find a project measure
107 */
108 <G extends Serializable> Measure<G> getMeasure(Metric<G> metric);
109
110 /**
111 * All measures of the project. Never return null.
112 */
113 <M> M getMeasures(MeasuresFilter<M> filter);
114
115 /**
116 * Add a measure on project
117 */
118 Measure saveMeasure(Measure measure);
119
120 /**
121 * Add a measure on project
122 */
123 Measure saveMeasure(Metric metric, Double value);
124
125 // ----------- MEASURES ON RESOURCES --------------
126
127 /**
128 * Find a measure for this project
129 */
130 <G extends Serializable> Measure<G> getMeasure(Resource resource, Metric<G> metric);
131
132 /**
133 * Key is updated when saving the resource.
134 *
135 * @return the key as saved in database. Null if the resource is set as excluded.
136 * @deprecated use the methods index()
137 */
138 @Deprecated
139 String saveResource(Resource resource);
140
141 /**
142 * Find all measures for this project. Never return null.
143 */
144 <M> M getMeasures(Resource resource, MeasuresFilter<M> filter);
145
146 /**
147 * Add or update a measure.
148 * <p>
149 * The resource is automatically saved, so there is no need to execute the method saveResource(). Does nothing if the resource is set as
150 * excluded.
151 * </p>
152 */
153 Measure saveMeasure(Resource resource, Metric metric, Double value);
154
155 /**
156 * Add or update a measure.
157 * <p>
158 * The resource is automatically saved, so there is no need to execute the method saveResource(). Does nothing if the resource is set as
159 * excluded.
160 * </p>
161 */
162 Measure saveMeasure(Resource resource, Measure measure);
163
164 // ----------- RULE VIOLATIONS --------------
165
166 /**
167 * Save a coding rule violation.
168 *
169 * @param force allows to force creation of violation even if it was supressed by {@link org.sonar.api.rules.ViolationFilter}
170 * @since 2.5
171 */
172 void saveViolation(Violation violation, boolean force);
173
174 /**
175 * Save a coding rule violation.
176 */
177 void saveViolation(Violation violation);
178
179 /**
180 * Saves a list of violations.
181 */
182 void saveViolations(Collection<Violation> violations);
183
184 // ----------- DEPENDENCIES BETWEEN RESOURCES --------------
185
186 /**
187 * Build a new dependency : from depends upon to. The dependency is NOT saved. The method saveDependency() must still be executed.
188 */
189 Dependency saveDependency(Dependency dependency);
190
191 Set<Dependency> getDependencies();
192
193 Collection<Dependency> getIncomingDependencies(Resource to);
194
195 Collection<Dependency> getOutgoingDependencies(Resource from);
196
197 // ----------- FILE SOURCES --------------
198
199 /**
200 * Save the source code of a file. The file must be have been indexed before.
201 *
202 * @throws org.sonar.api.resources.DuplicatedSourceException if the source has already been set on this resource
203 * @since 1.10. Returns a boolean since 2.6.
204 * @deprecated since 4.2 Source import is done by the platform
205 */
206 @Deprecated
207 void saveSource(Resource reference, String source);
208
209 // ----------- LINKS --------------
210
211 /**
212 * add a link to an external page like project homepage, sources (subversion, ...), continuous integration server... Example :
213 * context.addLink(new ProjectLink("maven_site, "Maven site", "http://my.maven.com)
214 */
215 void saveLink(ProjectLink link);
216
217 /**
218 * remove a link. It does not fail if key is unknown.
219 */
220 void deleteLink(String key);
221
222 // ----------- EVENTS --------------
223
224 /**
225 * @param resource set null for project events
226 */
227 List<Event> getEvents(Resource resource);
228
229 /**
230 * Creates an event for a given date
231 *
232 * @param name the event name
233 * @param description the event description
234 * @param category the event category
235 * @param date the event date
236 * @return the created event
237 */
238 Event createEvent(Resource resource, String name, String description, String category, Date date);
239
240 /**
241 * Deletes an event
242 *
243 * @param event the event to delete
244 */
245 void deleteEvent(Event event);
246
247 /**
248 * Experimental
249 * @since 4.2
250 */
251 Measure saveMeasure(InputFile inputFile, Metric metric, Double value);
252
253 /**
254 * Experimental
255 * @since 4.2
256 */
257 Measure saveMeasure(InputFile inputFile, Measure measure);
258 }