net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/compiler/CategorizedProblem.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2008 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Eclipse Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/epl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.core.compiler;
  12
  13 import net.sourceforge.phpdt.internal.compiler.problem.DefaultProblem;
  14
  15 /**
  16  * Richer description of a Java problem, as detected by the compiler or some of the underlying
  17  * technology reusing the compiler. With the introduction of <code>org.eclipse.jdt.core.compiler.CompilationParticipant</code>,
  18  * the simpler problem interface {@link IProblem} did not carry enough information to better
  19  * separate and categorize Java problems. In order to minimize impact on existing API, Java problems
  20  * are still passed around as {@link IProblem}, though actual implementations should explicitly
  21  * extend {@link CategorizedProblem}. Participants can produce their own problem definitions,
  22  * and given these are categorized problems, they can be better handled by clients (such as user
  23  * interface).
  24  * <p>
  25  * A categorized problem provides access to:
  26  * <ul>
  27  * <li> its location (originating source file name, source position, line number), </li>
  28  * <li> its message description and a predicate to check its severity (warning or error). </li>
  29  * <li> its ID : a number identifying the very nature of this problem. All possible IDs for standard Java
  30  * problems are listed as constants on {@link IProblem}, </li>
  31  * <li> its marker type : a string identifying the problem creator. It corresponds to the marker type
  32  * chosen if this problem was to be persisted. Standard Java problems are associated to marker
  33  * type "org.eclipse.jdt.core.problem"), </li>
  34  * <li> its category ID : a number identifying the category this problem belongs to. All possible IDs for
  35  * standard Java problem categories are listed in this class. </li>
  36  * </ul>
  37  * <p>
  38  * Note: the compiler produces IProblems internally, which are turned into markers by the JavaBuilder
  39  * so as to persist problem descriptions. This explains why there is no API allowing to reach IProblem detected
  40  * when compiling. However, the Java problem markers carry equivalent information to IProblem, in particular
  41  * their ID (attribute "id") is set to one of the IDs defined on this interface.
  42  * <p>
  43  * Note: Standard Java problems produced by Java default tooling will be subclasses of this class. Technically, most
  44  * API methods dealing with problems are referring to {@link IProblem} for backward compatibility reason.
  45  * It is intended that {@link CategorizedProblem} will be subclassed for custom problem implementation when
  46  * participating in compilation operations, so as to allow participant to contribute their own marker types, and thus
  47  * defining their own domain specific problem/category IDs.
  48  * <p>
  49  * Note: standard Java problems produced by Java default tooling will set the marker
  50  * <code> IMarker#SOURCE_ID</code> attribute to
  51  * <code> JavaBuilder#SOURCE_ID</code>; compiler
  52  * participants may specify the <code> IMarker#SOURCE_ID</code>
  53  * attribute of their markers by adding it to the extra marker attributes of the problems they generate;
  54  * markers resulting from compiler participants' problems that do not have the
  55  * <code> IMarker#SOURCE_ID</code> extra attribute set do not have the
  56  * <code> JavaBuilder#SOURCE_ID</code> attribute set either.
  57  *
  58  * @since 3.2
  59  */
  60 public abstract class CategorizedProblem implements IProblem {
  61
  62         /**
  63          * List of standard category IDs used by Java problems, more categories will be added
  64          * in the future.
  65          */
  66         public static final int CAT_UNSPECIFIED = 0;
  67         /** Category for problems related to buildpath */
  68         public static final int CAT_BUILDPATH = 10;
  69         /** Category for fatal problems related to syntax */
  70         public static final int CAT_SYNTAX = 20;
  71         /** Category for fatal problems in import statements */
  72         public static final int CAT_IMPORT = 30;
  73         /** Category for fatal problems related to types, could be addressed by some type change */
  74         public static final int CAT_TYPE = 40;
  75         /** Category for fatal problems related to type members, could be addressed by some field or method change */
  76         public static final int CAT_MEMBER = 50;
  77         /** Category for fatal problems which could not be addressed by external changes, but require an edit to be addressed */
  78         public static final int CAT_INTERNAL = 60;
  79         /** Category for optional problems in Javadoc */
  80         public static final int CAT_JAVADOC = 70;
  81         /** Category for optional problems related to coding style practices */
  82         public static final int CAT_CODE_STYLE = 80;
  83         /** Category for optional problems related to potential programming flaws */
  84         public static final int CAT_POTENTIAL_PROGRAMMING_PROBLEM = 90;
  85         /** Category for optional problems related to naming conflicts */
  86         public static final int CAT_NAME_SHADOWING_CONFLICT = 100;
  87         /** Category for optional problems related to deprecation */
  88         public static final int CAT_DEPRECATION = 110;
  89         /** Category for optional problems related to unnecessary code */
  90         public static final int CAT_UNNECESSARY_CODE = 120;
  91         /** Category for optional problems related to type safety in generics */
  92         public static final int CAT_UNCHECKED_RAW = 130;
  93         /** Category for optional problems related to internationalization of String literals */
  94         public static final int CAT_NLS = 140;
  95         /** Category for optional problems related to access restrictions */
  96         public static final int CAT_RESTRICTION = 150;
  97
  98 /**
  99  * Returns an integer identifying the category of this problem. Categories, like problem IDs are
 100  * defined in the context of some marker type. Custom implementations of {@link CategorizedProblem}
 101  * may choose arbitrary values for problem/category IDs, as long as they are associated with a different
 102  * marker type.
 103  * Standard Java problem markers (i.e. marker type is "org.eclipse.jdt.core.problem") carry an
 104  * attribute "categoryId" persisting the originating problem category ID as defined by this method).
 105  * @return id - an integer identifying the category of this problem
 106  */
 107 public abstract int getCategoryID();
 108
 109 /**
 110  * Returns the marker type associated to this problem, if it gets persisted into a marker by the JavaBuilder
 111  * Standard Java problems are associated to marker type "org.eclipse.jdt.core.problem").
 112  * Note: problem markers are expected to extend "org.eclipse.core.resources.problemmarker" marker type.
 113  * @return the type of the marker which would be associated to the problem
 114  */
 115 public abstract String getMarkerType();
 116
 117 /**
 118  * Returns the names of the extra marker attributes associated to this problem when persisted into a marker
 119  * by the JavaBuilder. Extra attributes are only optional, and are allowing client customization of generated
 120  * markers. By default, no EXTRA attributes is persisted, and a categorized problem only persists the following attributes:
 121  * <ul>
 122  * <li> <code>IMarker#MESSAGE</code> -&gt; {@link IProblem#getMessage()}</li>
 123  * <li> <code>IMarker#SEVERITY</code> -&gt; <code> IMarker#SEVERITY_ERROR</code> or
 124  *         <code>IMarker#SEVERITY_WARNING</code> depending on {@link IProblem#isError()} or {@link IProblem#isWarning()}</li>
 125  * <li> <code>IJavaModelMarker#ID</code> -&gt; {@link IProblem#getID()}</li>
 126  * <li> <code>IMarker#CHAR_START</code>  -&gt; {@link IProblem#getSourceStart()}</li>
 127  * <li> <code>IMarker#CHAR_END</code>  -&gt; {@link IProblem#getSourceEnd()}</li>
 128  * <li> <code>IMarker#LINE_NUMBER</code>  -&gt; {@link IProblem#getSourceLineNumber()}</li>
 129  * <li> <code>IJavaModelMarker#ARGUMENTS</code>  -&gt; some <code>String[]</code> used to compute quickfixes </li>
 130  * <li> <code>IJavaModelMarker#CATEGORY_ID</code> -&gt; {@link CategorizedProblem#getCategoryID()}</li>
 131  * </ul>
 132  * The names must be eligible for marker creation, as defined by <code>IMarker#setAttributes(String[], Object[])</code>,
 133  * and there must be as many names as values according to {@link #getExtraMarkerAttributeValues()}.
 134  * Note that extra marker attributes will be inserted after default ones (as described in {@link CategorizedProblem#getMarkerType()},
 135  * and thus could be used to override defaults.
 136  * @return the names of the corresponding marker attributes
 137  */
 138 public String[] getExtraMarkerAttributeNames() {
 139         return CharOperation.NO_STRINGS;
 140 }
 141
 142 /**
 143  * Returns the respective values for the extra marker attributes associated to this problem when persisted into
 144  * a marker by the JavaBuilder. Each value must correspond to a matching attribute name, as defined by
 145  * {@link #getExtraMarkerAttributeNames()}.
 146  * The values must be eligible for marker creation, as defined by <code> IMarker#setAttributes(String[], Object[])}.
 147  * @return the values of the corresponding extra marker attributes
 148  */
 149 public Object[] getExtraMarkerAttributeValues() {
 150         return DefaultProblem.EMPTY_VALUES;
 151 }
 152 }