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