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     */
020    
021    package org.sonar.api.issue;
022    
023    import org.sonar.api.component.Perspective;
024    import org.sonar.api.rule.RuleKey;
025    
026    import javax.annotation.Nullable;
027    import java.util.List;
028    
029    /**
030     * This perspective allows to add and get issues related to the selected component. It can be used from
031     * {@link org.sonar.api.batch.Sensor}s and {@link org.sonar.api.batch.Decorator}s. Web extensions
032     * must use {@link RubyIssueService}.
033     * <p/>
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     */
060    public 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         */
071        IssueBuilder line(@Nullable Integer line);
072    
073        /**
074         * Optional, but recommended, plain-text message.
075         * <p/>
076         * Formats like Markdown or HTML are not supported. Size must not be greater than {@link Issue#MESSAGE_MAX_SIZE} characters.
077         */
078        IssueBuilder message(@Nullable String message);
079    
080        /**
081         * Overrides the severity declared in Quality profile. Do not execute in standard use-cases.
082         * @see org.sonar.api.rule.Severity
083         */
084        IssueBuilder severity(@Nullable String severity);
085    
086        /**
087         * Login of the user who reported the issue. Optional.
088         */
089        IssueBuilder reporter(@Nullable String reporter);
090    
091        IssueBuilder effortToFix(@Nullable Double d);
092    
093        IssueBuilder attribute(String key, @Nullable String value);
094    
095        Issue build();
096      }
097    
098      /**
099       * Builder is used to create the issue to be passed to {@link #addIssue(Issue)}
100       */
101      IssueBuilder newIssueBuilder();
102    
103      /**
104       * Register an issue created with {@link #newIssueBuilder()}.
105       * <p/>
106       * This method is usually called from {@link org.sonar.api.batch.Sensor}s. {@link org.sonar.api.batch.Decorator}s calling this
107       * method must be annotated with {@code @DependedUpon(DecoratorBarriers.ISSUES_ADDED)}.
108       *
109       * @return true if the new issue is registered, false if the related rule does not exist or is disabled in the Quality profile.
110       */
111      boolean addIssue(Issue issue);
112    
113      /**
114       * Unresolved issues, including the issues reported by end-users.
115       * <p/>
116       * {@link org.sonar.api.batch.Decorator}s calling this method must be annotated with {@code @DependsUpon(DecoratorBarriers.ISSUES_TRACKED)}.
117       */
118      List<Issue> issues();
119    
120      /**
121       * Issues marked as resolved during this scan.
122       * <p/>
123       * {@link org.sonar.api.batch.Decorator}s calling this method must be annotated with {@code @DependsUpon(DecoratorBarriers.ISSUES_TRACKED)}.
124       */
125      List<Issue> resolvedIssues();
126    }