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.issue;
021
022import java.io.Serializable;
023import java.util.Collection;
024import java.util.Date;
025import java.util.List;
026import java.util.Map;
027import javax.annotation.CheckForNull;
028import org.sonar.api.batch.ScannerSide;
029import org.sonar.api.rule.RuleKey;
030import org.sonar.api.utils.Duration;
031
032import static java.util.Arrays.asList;
033
034/**
035 * @since 3.6
036 */
037public interface Issue extends Serializable {
038
039  /**
040   * Maximum number of characters in the message.
041   * In theory it should be 4_000 UTF-8 characters but unfortunately
042   * Oracle DB does not support more than 4_000 bytes, even if column
043   * issues.message is created with type VARCHAR2(4000 CHAR).
044   * In order to have the same behavior on all databases, message
045   * is truncated to 4_000 / 3 (maximum bytes per UTF-8 character)
046   * = 1_333 characters.
047   */
048  int MESSAGE_MAX_SIZE = 1_333;
049
050  /**
051   * Default status when creating an issue.
052   */
053  String STATUS_OPEN = "OPEN";
054  String STATUS_CONFIRMED = "CONFIRMED";
055  String STATUS_REOPENED = "REOPENED";
056  String STATUS_RESOLVED = "RESOLVED";
057  String STATUS_CLOSED = "CLOSED";
058
059  String RESOLUTION_FIXED = "FIXED";
060
061  /**
062   * Resolution when issue is flagged as false positive.
063   */
064  String RESOLUTION_FALSE_POSITIVE = "FALSE-POSITIVE";
065
066  /**
067   * Resolution when rule has been uninstalled or disabled in the Quality profile.
068    */
069  String RESOLUTION_REMOVED = "REMOVED";
070
071  /**
072   * Issue is irrelevant in the context and was muted by user.
073   * @since 5.1
074   */
075  String RESOLUTION_WONT_FIX = "WONTFIX";
076
077  List<String> RESOLUTIONS = asList(RESOLUTION_FALSE_POSITIVE, RESOLUTION_WONT_FIX, RESOLUTION_FIXED, RESOLUTION_REMOVED);
078
079  /**
080   * Return all available statuses
081   *
082   * @since 4.4
083   */
084  List<String> STATUSES = asList(STATUS_OPEN, STATUS_CONFIRMED, STATUS_REOPENED, STATUS_RESOLVED, STATUS_CLOSED);
085
086  /**
087   * Unique generated key. It looks like "d2de809c-1512-4ae2-9f34-f5345c9f1a13".
088   */
089  String key();
090
091  /**
092   * Components are modules ("my_project"), directories ("my_project:my/dir") or files ("my_project:my/file.c").
093   * Keys of Java packages and classes are currently in a special format: "my_project:com.company" and "my_project:com.company.Foo".
094   */
095  String componentKey();
096
097  RuleKey ruleKey();
098
099  String language();
100
101  /**
102   * See constants in {@link org.sonar.api.rule.Severity}.
103   */
104  String severity();
105
106  @CheckForNull
107  String message();
108
109  /**
110   * Optional line number. If set, then it's greater than or equal 1.
111   */
112  @CheckForNull
113  Integer line();
114
115  /**
116   * @deprecated since 5.5, replaced by {@link #gap()}
117   */
118  @Deprecated
119  @CheckForNull
120  Double effortToFix();
121
122  /**
123   * Arbitrary distance to threshold for resolving the issue.
124   * <br>
125   * For examples:
126   * <ul>
127   *   <li>for the rule "Avoid too complex methods" : current complexity - max allowed complexity</li>
128   *   <li>for the rule "Avoid Duplications" : number of duplicated blocks</li>
129   *   <li>for the rule "Insufficient Line Coverage" : number of lines to cover to reach the accepted threshold</li>
130   * </ul>
131   *
132   * @since 5.5
133   */
134  @CheckForNull
135  Double gap();
136
137  /**
138   * See constant values in {@link Issue}.
139   */
140  String status();
141
142  /**
143   * The type of resolution, or null if the issue is not resolved. See constant values in {@link Issue}.
144   */
145  @CheckForNull
146  String resolution();
147
148  /**
149   * @deprecated since 5.5, manual issue feature has been dropped.
150   */
151  @Deprecated
152  @CheckForNull
153  String reporter();
154
155  /**
156   * Login of the user who is assigned to this issue. Null if the issue is not assigned.
157   */
158  @CheckForNull
159  String assignee();
160
161  Date creationDate();
162
163  Date updateDate();
164
165  /**
166   * Date when status was set to {@link Issue#STATUS_CLOSED}, else null.
167   */
168  @CheckForNull
169  Date closeDate();
170
171  @CheckForNull
172  String attribute(String key);
173
174  /**
175   * Empty on batch side since version 5.2. Attributes are moved to server's Compute Engine. No use-case for keeping them
176   * on batch side for now
177   */
178  Map<String, String> attributes();
179
180  /**
181   * Login of the SCM account that introduced this issue. Requires the
182   * <a href="http://www.sonarsource.com/products/plugins/developer-tools/developer-cockpit/">Developer Cockpit Plugin</a> to be installed.
183   */
184  @CheckForNull
185  String authorLogin();
186
187  /**
188   * @deprecated since 5.5 Action plans are dropped in 5.5. This field has no effect
189   */
190  @Deprecated
191  @CheckForNull
192  String actionPlanKey();
193
194  /**
195   * Non-null list of comments, ordered by chronological order.
196   * <br>
197   * IMPORTANT: existing comments are not loaded when this method is called when analyzing project
198   * (from {@link ScannerSide}).
199   */
200  List<IssueComment> comments();
201
202  /**
203   * During a scan return if the current issue is a new one.
204   * @return always false on server side
205   * @since 4.0
206   */
207  boolean isNew();
208
209  /**
210   * During a scan returns true if the issue is copied from another branch.
211   * @since 6.6
212   */
213  boolean isCopied();
214
215  /**
216   * @deprecated since 5.5, replaced by {@link #effort()}
217   */
218  @Deprecated
219  Duration debt();
220
221  /**
222   * @since 5.5
223   */
224  @CheckForNull
225  Duration effort();
226
227  /**
228   * @since 5.0
229   */
230  String projectKey();
231
232  /**
233   * @since 5.0
234   */
235  String projectUuid();
236
237  /**
238   * @since 5.0
239   */
240  String componentUuid();
241
242  /**
243   * @since 5.1
244   */
245  Collection<String> tags();
246}