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.util.List; 023import javax.annotation.CheckForNull; 024import javax.annotation.Nullable; 025import org.sonar.api.batch.sensor.issue.NewIssue; 026import org.sonar.api.batch.sensor.issue.NewIssueLocation; 027import org.sonar.api.component.Perspective; 028import org.sonar.api.rule.RuleKey; 029 030/** 031 * This perspective allows to add issues related to the selected component. It can be used from 032 * {@link org.sonar.api.batch.Sensor}s. 033 * <br> 034 * Example: 035 * <pre> 036 * import org.sonar.api.component.ResourcePerspectives; 037 * public class MySensor extends Sensor { 038 * private final ResourcePerspectives perspectives; 039 * 040 * public MySensor(ResourcePerspectives p) { 041 * this.perspectives = p; 042 * } 043 * 044 * public void analyse(Project project, SensorContext context) { 045 * Resource myResource; // to be set 046 * Issuable issuable = perspectives.as(Issuable.class, myResource); 047 * if (issuable != null) { 048 * // can be used 049 * Issue issue = issuable.newIssueBuilder() 050 * .setRuleKey(RuleKey.of("pmd", "AvoidArrayLoops") 051 * .setLine(10) 052 * .build(); 053 * issuable.addIssue(issue); 054 * } 055 * } 056 * } 057 * </pre> 058 * @since 3.6 059 */ 060public interface Issuable extends Perspective { 061 062 interface IssueBuilder { 063 /** 064 * The rule key is mandatory. Example: {@code RuleKey.of("pmd", "AvoidArrayLoops")} 065 */ 066 IssueBuilder ruleKey(RuleKey ruleKey); 067 068 /** 069 * Optional line index, starting from 1. It must not be zero or negative. 070 * @deprecated since 5.2 use {@link #at(NewIssueLocation)} 071 */ 072 @Deprecated 073 IssueBuilder line(@Nullable Integer line); 074 075 /** 076 * Optional, but recommended, plain-text message. 077 * <br> 078 * Formats like Markdown or HTML are not supported. Size must not be greater than {@link Issue#MESSAGE_MAX_SIZE} characters. 079 * @deprecated since 5.2 use {@link #at(NewIssueLocation)} 080 */ 081 @Deprecated 082 IssueBuilder message(@Nullable String message); 083 084 /** 085 * @since 5.2 086 * Create a new location for this issue. First registered location is considered as primary location. 087 */ 088 NewIssueLocation newLocation(); 089 090 /** 091 * @since 5.2 092 * Register primary location for this issue. 093 */ 094 IssueBuilder at(NewIssueLocation primaryLocation); 095 096 /** 097 * @since 5.2 098 * @see NewIssue#addLocation(NewIssueLocation) 099 */ 100 IssueBuilder addLocation(NewIssueLocation secondaryLocation); 101 102 /** 103 * @since 5.2 104 * @see NewIssue#addFlow(Iterable) 105 */ 106 IssueBuilder addFlow(Iterable<NewIssueLocation> flowLocations); 107 108 /** 109 * Overrides the severity declared in Quality profile. Do not execute in standard use-cases. 110 * @see org.sonar.api.rule.Severity 111 */ 112 IssueBuilder severity(@Nullable String severity); 113 114 /** 115 * @deprecated since 5.5, manual issue feature has been dropped. 116 */ 117 @Deprecated 118 @CheckForNull 119 IssueBuilder reporter(@Nullable String reporter); 120 121 IssueBuilder effortToFix(@Nullable Double d); 122 123 /** 124 * No more supported from batch side since 5.2 125 */ 126 IssueBuilder attribute(String key, @Nullable String value); 127 128 Issue build(); 129 } 130 131 /** 132 * Builder is used to create the issue to be passed to {@link #addIssue(Issue)} 133 */ 134 IssueBuilder newIssueBuilder(); 135 136 /** 137 * Register an issue created with {@link #newIssueBuilder()}. 138 * <br> 139 * This method is usually called from {@link org.sonar.api.batch.Sensor}s. {@link org.sonar.api.batch.Decorator}s calling this 140 * method must be annotated with {@code @DependedUpon(DecoratorBarriers.ISSUES_ADDED)}. 141 * 142 * @return true if the new issue is registered, false if the related rule does not exist or is disabled in the Quality profile. 143 */ 144 boolean addIssue(Issue issue); 145 146 /** 147 * @deprecated since 5.2 no more decorators on batch side 148 */ 149 @Deprecated 150 List<Issue> issues(); 151 152 /** 153 * @deprecated since 5.2 no more decorators on batch side 154 */ 155 @Deprecated 156 List<Issue> resolvedIssues(); 157}