KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > core > compiler > CategorizedProblem


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 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 org.eclipse.jdt.core.compiler;
12
13 import org.eclipse.jdt.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>CompilationParticipant</code>,
18  * the simpler problem interface <code>IProblem</code> 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 <code>IProblem</code>, though actual implementations should explicitly
21  * extend <code>CategorizedProblem</code>. 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  *
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 <code>IProblem</code>, </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  *
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  *
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 <code>IProblem</code> for backward compatibility reason.
45  * It is intended that <code>CategorizedProblem</code> 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  *
49  * Note: standard Java problems produced by Java default tooling will set the
50  * marker IMarker#GENERATED_BY attribute to JavaBuilder#GENERATED_BY; compiler
51  * participants may specify the IMarker#GENERATED_BY attribute of their markers
52  * by adding it to the extra marker attributes of the problems they generate;
53  * markers resulting from compiler participants' problems that do not have the
54  * IMarker#GENERATED_BY extra attribute set do not have the IMarker#GENERATED_BY
55  * attribute set either.
56  *
57  * @since 3.2
58  */
59 public abstract class CategorizedProblem implements IProblem {
60     
61     /**
62      * List of standard category IDs used by Java problems, more categories will be added
63      * in the future.
64      */
65     public static final int CAT_UNSPECIFIED = 0;
66     /** Category for problems related to buildpath */
67     public static final int CAT_BUILDPATH = 10;
68     /** Category for fatal problems related to syntax */
69     public static final int CAT_SYNTAX = 20;
70     /** Category for fatal problems in import statements */
71     public static final int CAT_IMPORT = 30;
72     /** Category for fatal problems related to types, could be addressed by some type change */
73     public static final int CAT_TYPE = 40;
74     /** Category for fatal problems related to type members, could be addressed by some field or method change */
75     public static final int CAT_MEMBER = 50;
76     /** Category for fatal problems which could not be addressed by external changes, but require an edit to be addressed */
77     public static final int CAT_INTERNAL = 60;
78     /** Category for optional problems in Javadoc */
79     public static final int CAT_JAVADOC = 70;
80     /** Category for optional problems related to coding style practices */
81     public static final int CAT_CODE_STYLE = 80;
82     /** Category for optional problems related to potential programming flaws */
83     public static final int CAT_POTENTIAL_PROGRAMMING_PROBLEM = 90;
84     /** Category for optional problems related to naming conflicts */
85     public static final int CAT_NAME_SHADOWING_CONFLICT = 100;
86     /** Category for optional problems related to deprecation */
87     public static final int CAT_DEPRECATION = 110;
88     /** Category for optional problems related to unnecessary code */
89     public static final int CAT_UNNECESSARY_CODE = 120;
90     /** Category for optional problems related to type safety in generics */
91     public static final int CAT_UNCHECKED_RAW = 130;
92     /** Category for optional problems related to internationalization of String literals */
93     public static final int CAT_NLS = 140;
94     /** Category for optional problems related to access restrictions */
95     public static final int CAT_RESTRICTION = 150;
96     
97 /**
98  * Returns an integer identifying the category of this problem. Categories, like problem IDs are
99  * defined in the context of some marker type. Custom implementations of <code>CategorizedProblem</code>
100  * may choose arbitrary values for problem/category IDs, as long as they are associated with a different
101  * marker type.
102  * Standard Java problem markers (i.e. marker type is "org.eclipse.jdt.core.problem") carry an
103  * attribute "categoryId" persisting the originating problem category ID as defined by this method).
104  * @return id - an integer identifying the category of this problem
105  */
106 public abstract int getCategoryID();
107
108 /**
109  * Returns the marker type associated to this problem, if it gets persisted into a marker by the JavaBuilder
110  * Standard Java problems are associated to marker type "org.eclipse.jdt.core.problem").
111  * Note: problem markers are expected to extend "org.eclipse.core.resources.problemmarker" marker type.
112  * @return the type of the marker which would be associated to the problem
113  */
114 public abstract String JavaDoc getMarkerType();
115
116 /**
117  * Returns the names of the extra marker attributes associated to this problem when persisted into a marker
118  * by the JavaBuilder. Extra attributes are only optional, and are allowing client customization of generated
119  * markers. By default, no EXTRA attributes is persisted, and a categorized problem only persists the following attributes:
120  * <ul>
121  * <li> <code>IMarker#MESSAGE</code> -&gt; {@link IProblem#getMessage()}</li>
122  * <li> <code>IMarker#SEVERITY</code> -&gt; <code> IMarker#SEVERITY_ERROR</code> or
123  * <code>IMarker#SEVERITY_WARNING</code> depending on {@link IProblem#isError()} or {@link IProblem#isWarning()}</li>
124  * <li> <code>IJavaModelMarker#ID</code> -&gt; {@link IProblem#getID()}</li>
125  * <li> <code>IMarker#CHAR_START</code> -&gt; {@link IProblem#getSourceStart()}</li>
126  * <li> <code>IMarker#CHAR_END</code> -&gt; {@link IProblem#getSourceEnd()}</li>
127  * <li> <code>IMarker#LINE_NUMBER</code> -&gt; {@link IProblem#getSourceLineNumber()}</li>
128  * <li> <code>IJavaModelMarker#ARGUMENTS</code> -&gt; some <code>String[]</code> used to compute quickfixes </li>
129  * <li> <code>IJavaModelMarker#CATEGORY_ID</code> -&gt; {@link CategorizedProblem#getCategoryID()}</li>
130  * </ul>
131  * The names must be eligible for marker creation, as defined by <code>IMarker#setAttributes(String[], Object[])</code>,
132  * and there must be as many names as values according to {@link #getExtraMarkerAttributeValues()}.
133  * Note that extra marker attributes will be inserted after default ones (as described in {@link CategorizedProblem#getMarkerType()},
134  * and thus could be used to override defaults.
135  * @return the names of the corresponding marker attributes
136  */
137 public String JavaDoc[] getExtraMarkerAttributeNames() {
138     return CharOperation.NO_STRINGS;
139 }
140
141 /**
142  * Returns the respective values for the extra marker attributes associated to this problem when persisted into
143  * a marker by the JavaBuilder. Each value must correspond to a matching attribute name, as defined by
144  * {@link #getExtraMarkerAttributeNames()}.
145  * The values must be eligible for marker creation, as defined by <code>IMarker#setAttributes(String[], Object[])</code>.
146  * @return the values of the corresponding extra marker attributes
147  */
148 public Object JavaDoc[] getExtraMarkerAttributeValues() {
149     return DefaultProblem.EMPTY_VALUES;
150 }
151 }
152
Popular Tags