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