lint/libs/lint_api/src/com/android/tools/lint/detector/api/Issue.java

   1 /*
   2  * Copyright (C) 2011 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package com.android.tools.lint.detector.api;
  18
  19
  20
  21 /**
  22  * An issue is a potential bug in an Android application. An issue is discovered
  23  * by a {@link Detector}, and has an associated {@link Severity}.
  24  * <p>
  25  * Issues and detectors are separate classes because a detector can discover
  26  * multiple different issues as it's analyzing code, and we want to be able to
  27  * different severities for different issues, the ability to suppress one but
  28  * not other issues from the same detector, and so on.
  29  * <p/>
  30  * <b>NOTE: This is not a public or final API; if you rely on this be prepared
  31  * to adjust your code for the next tools release.</b>
  32  */
  33 public final class Issue implements Comparable<Issue> {
  34     private final String mId;
  35     private final String mDescription;
  36     private final String mExplanation;
  37     private final String mCategory;
  38     private final int mPriority;
  39     private final Severity mSeverity;
  40     private String mMoreInfoUrl;
  41     private boolean mEnabledByDefault = true;
  42
  43     // Use factory methods
  44     private Issue(String id, String description, String explanation, String category, int priority,
  45             Severity severity) {
  46         super();
  47         mId = id;
  48         mDescription = description;
  49         mExplanation = explanation;
  50         mCategory = category;
  51         mPriority = priority;
  52         mSeverity = severity;
  53     }
  54
  55     /**
  56      * Creates a new issue
  57      *
  58      * @param id the fixed id of the issue
  59      * @param description the quick summary of the issue (one line)
  60      * @param explanation a full explanation of the issue, with suggestions for
  61      *            how to fix it
  62      * @param category the associated category, if any
  63      * @param priority the priority, a number from 1 to 10 with 10 being most
  64      *            important/severe
  65      * @param severity the default severity of the issue
  66      * @return a new {@link Issue}
  67      */
  68     public static Issue create(String id, String description, String explanation, String category,
  69             int priority, Severity severity) {
  70         return new Issue(id, description, explanation, category, priority, severity);
  71     }
  72
  73     /**
  74      * Returns the unique id of this issue. These should not change over time
  75      * since they are used to persist the names of issues suppressed by the user
  76      * etc. It is typically a single camel-cased word.
  77      *
  78      * @return the associated fixed id, never null and always unique
  79      */
  80     public String getId() {
  81         return mId;
  82     }
  83
  84     /**
  85      * Briefly (one line) describes the kinds of checks performed by this rule
  86      *
  87      * @return a quick summary of the issue, never null
  88      */
  89     public String getDescription() {
  90         return mDescription;
  91     }
  92
  93     /**
  94      * Describes the error found by this rule, e.g.
  95      * "Buttons must define contentDescriptions". Preferably the explanation
  96      * should also contain a description of how the problem should be solved.
  97      * Additional info can be provided via {@link #getMoreInfo()}.
  98      *
  99      * @return an explanation of the issue, never null.
 100      */
 101     public String getExplanation() {
 102         return mExplanation;
 103     }
 104
 105     /**
 106      * The category, or null if no category has been assigned
 107      *
 108      * @return the category, or null if no category has been assigned
 109      */
 110     public String getCategory() {
 111         return mCategory;
 112     }
 113
 114     /**
 115      * Returns a priority, in the range 1-10, with 10 being the most severe and
 116      * 1 the least
 117      *
 118      * @return a priority from 1 to 10
 119      */
 120     public int getPriority() {
 121         return mPriority;
 122     }
 123
 124     /**
 125      * Returns the default severity of the issues found by this detector (some
 126      * tools may allow the user to specify custom severities for detectors).
 127      *
 128      * @return the severity of the issues found by this detector
 129      */
 130     public Severity getDefaultSeverity() {
 131         return mSeverity;
 132     }
 133
 134     /**
 135      * Returns a link (a URL string) to more information, or null
 136      *
 137      * @return a link to more information, or null
 138      */
 139     public String getMoreInfo() {
 140         return mMoreInfoUrl;
 141     }
 142
 143     /**
 144      * Returns whether this issue should be enabled by default, unless the user
 145      * has explicitly disabled it.
 146      *
 147      * @return true if this issue should be enabled by default
 148      */
 149     public boolean isEnabledByDefault() {
 150         return mEnabledByDefault;
 151     }
 152
 153     /**
 154      * Sorts the detectors alphabetically by id. This is intended to make it
 155      * convenient to store settings for detectors in a fixed order. It is not
 156      * intended as the order to be shown to the user; for that, a tool embedding
 157      * lint might consider the priorities, categories, severities etc of the
 158      * various detectors.
 159      *
 160      * @param other the {@link Issue} to compare this issue to
 161      */
 162     public int compareTo(Issue other) {
 163         return getId().compareTo(other.getId());
 164     }
 165
 166     /**
 167      * Sets a more info URL string
 168      *
 169      * @param moreInfoUrl url string
 170      * @return this, for constructor chaining
 171      */
 172     public Issue setMoreInfo(String moreInfoUrl) {
 173         mMoreInfoUrl = moreInfoUrl;
 174         return this;
 175     }
 176
 177     /**
 178      * Sets whether this issue is enabled by default.
 179      *
 180      * @param enabledByDefault whether the issue should be enabled by default
 181      * @return this, for constructor chaining
 182      */
 183     public Issue setEnabledByDefault(boolean enabledByDefault) {
 184         mEnabledByDefault = enabledByDefault;
 185         return this;
 186     }
 187 }