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