1 /******************************************************************************* 2 * Copyright (c) 2008, 2018 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.pde.api.tools.internal.provisional.problems; 15 16 import org.eclipse.jdt.core.compiler.CategorizedProblem; 17 import org.eclipse.pde.api.tools.internal.provisional.comparator.IDelta; 18 import org.eclipse.pde.api.tools.internal.provisional.descriptors.IElementDescriptor; 19 20 /** 21 * Describes a given API problem. 22 * 23 * @since 1.0.0 24 * @noimplement This interface is not intended to be implemented by clients. 25 */ 26 public interface IApiProblem { 27 28 /** 29 * Constant representing the incompatibility problem category 30 */ 31 public static final int CATEGORY_COMPATIBILITY = 0x10000000; 32 33 /** 34 * Constant representing the API usage problem category 35 */ 36 public static final int CATEGORY_USAGE = 0x20000000; 37 38 /** 39 * Constant representing the version problem category 40 */ 41 public static final int CATEGORY_VERSION = 0x30000000; 42 43 /** 44 * Constant representing the since tag problem category 45 */ 46 public static final int CATEGORY_SINCETAGS = 0x40000000; 47 48 /** 49 * Constant representing the API profile problem category 50 */ 51 public static final int CATEGORY_API_BASELINE = 0x50000000; 52 53 /** 54 * Constant representing the API component resolution problem category 55 */ 56 public static final int CATEGORY_API_COMPONENT_RESOLUTION = 0x60000000; 57 /** 58 * Constant representing a fatal problem i.e. a fatal JDT problem has been 59 * detected 60 * 61 * @since 1.1 62 */ 63 public static final int CATEGORY_FATAL_PROBLEM = 0x70000000; 64 /** 65 * Constant representing a API use scan breakage problem 66 */ 67 public static final int CATEGORY_API_USE_SCAN_PROBLEM = 0x80000000; 68 /** 69 * Constant representing the offset of the message key portion of the id bit 70 * mask. 71 */ 72 public static final int OFFSET_MESSAGE = 0; 73 74 /** 75 * Constant representing the offset of the flags portion of a problem id bit 76 * mask. 77 */ 78 public static final int OFFSET_FLAGS = 12; 79 80 /** 81 * Constant representing the offset of the kinds portion of a problem id bit 82 * mask. 83 */ 84 public static final int OFFSET_KINDS = 20; 85 86 /** 87 * Constant representing the offset of the element kinds portion of a 88 * problem id bit mask. 89 */ 90 public static final int OFFSET_ELEMENT = 24; 91 92 /** 93 * Constant representing the value of having no flags. Value is: 94 * <code>0</code> 95 */ 96 public static final int NO_FLAGS = 0x0; 97 98 /** 99 * Constant representing the value of no char start / char end. Value is: 100 * <code>-1</code> 101 */ 102 public static final int NO_CHARRANGE = -1; 103 104 /** 105 * Constant representing the value of the invalid @since tag 106 * {@link IApiProblem} kind. <br> 107 * Value is: <code>1</code> 108 * 109 * @see #getKind() 110 * @see #CATEGORY_SINCETAGS 111 */ 112 public static final int SINCE_TAG_INVALID = 1; 113 114 /** 115 * Constant representing the value of the malformed @since tag 116 * {@link IApiProblem} kind. <br> 117 * Value is: <code>2</code> 118 * 119 * @see #getKind() 120 * @see #CATEGORY_SINCETAGS 121 */ 122 public static final int SINCE_TAG_MALFORMED = 2; 123 124 /** 125 * Constant representing the value of the missing @since tag 126 * {@link IApiProblem} kind. <br> 127 * Value is: <code>3</code> 128 * 129 * @see #getKind() 130 * @see #CATEGORY_SINCETAGS 131 */ 132 public static final int SINCE_TAG_MISSING = 3; 133 134 /** 135 * Constant representing the value of the major version change 136 * {@link IApiProblem} kind. <br> 137 * Value is: <code>1</code> 138 * 139 * @see #getKind() 140 * @see #CATEGORY_VERSION 141 */ 142 public static final int MAJOR_VERSION_CHANGE = 1; 143 144 /** 145 * Constant representing the value of the minor version change 146 * {@link IApiProblem} kind. <br> 147 * Value is: <code>2</code> 148 * 149 * @see #getKind() 150 * @see #CATEGORY_VERSION 151 */ 152 public static final int MINOR_VERSION_CHANGE = 2; 153 154 /** 155 * Constant representing the value of the major version change (no API 156 * breakage) {@link IApiProblem} kind. <br> 157 * Value is: <code>3</code> 158 * 159 * @see #getKind() 160 * @see #CATEGORY_VERSION 161 */ 162 public static final int MAJOR_VERSION_CHANGE_NO_BREAKAGE = 3; 163 164 /** 165 * Constant representing the value of the minor version change (no new API) 166 * {@link IApiProblem} kind. <br> 167 * Value is: <code>4</code> 168 * 169 * @see #getKind() 170 * @see #CATEGORY_VERSION 171 */ 172 public static final int MINOR_VERSION_CHANGE_NO_NEW_API = 4; 173 174 /** 175 * Constant representing the value of the major version change 176 * {@link IApiProblem} kind as a consequence of a major version change in a 177 * re-exported bundle. <br> 178 * Value is: <code>5</code> 179 * 180 * @see #getKind() 181 * @see #CATEGORY_VERSION 182 */ 183 public static final int REEXPORTED_MAJOR_VERSION_CHANGE = 5; 184 185 /** 186 * Constant representing the value of the minor version change 187 * {@link IApiProblem} kind as a consequence of a minor version change in a 188 * re-exported bundle.. <br> 189 * Value is: <code>6</code> 190 * 191 * @see #getKind() 192 * @see #CATEGORY_VERSION 193 */ 194 public static final int REEXPORTED_MINOR_VERSION_CHANGE = 6; 195 196 /** 197 * Constant representing the value of the minor version change 198 * {@link IApiProblem} kind as a consequence of Execution Env changes Value 199 * is: <code>7</code> * 200 * 201 * @see #getKind() 202 * @see #CATEGORY_VERSION 203 */ 204 public static final int MINOR_VERSION_CHANGE_EXECUTION_ENV_CHANGED = 7; 205 206 /** 207 * Constant representing the value of the micro version change (inspite of 208 * major/minor change) {@link IApiProblem} kind. <br> 209 * Value is: <code>8</code> 210 * 211 * @see #getKind() 212 * @see #CATEGORY_VERSION 213 */ 214 public static final int MICRO_VERSION_CHANGE_UNNECESSARILY = 8; 215 /** 216 * Constant representing the value of the minor version change (inspite of major 217 * change) {@link IApiProblem} kind. <br> 218 * Value is: <code>8</code> 219 * 220 * @see #getKind() 221 * @see #CATEGORY_VERSION 222 */ 223 public static final int MINOR_VERSION_CHANGE_UNNECESSARILY = 9; 224 225 /** 226 * Constant representing the value of an illegal extend {@link IApiProblem} 227 * kind. <br> 228 * Value is: <code>1</code> 229 * 230 * @see #getKind() 231 * @see #CATEGORY_USAGE 232 */ 233 public static final int ILLEGAL_EXTEND = 1; 234 235 /** 236 * Constant representing the value of an illegal instantiate 237 * {@link IApiProblem} kind. <br> 238 * Value is: <code>2</code> 239 * 240 * @see #getKind() 241 * @see #CATEGORY_USAGE 242 */ 243 public static final int ILLEGAL_INSTANTIATE = 2; 244 245 /** 246 * Constant representing the value of an illegal reference 247 * {@link IApiProblem} kind. <br> 248 * Value is: <code>3</code> 249 * 250 * @see #getKind() 251 * @see #CATEGORY_USAGE 252 */ 253 public static final int ILLEGAL_REFERENCE = 3; 254 255 /** 256 * Constant representing the value of an illegal implement 257 * {@link IApiProblem} kind. <br> 258 * Value is: <code>4</code> 259 * 260 * @see #getKind() 261 * @see #CATEGORY_USAGE 262 */ 263 public static final int ILLEGAL_IMPLEMENT = 4; 264 265 /** 266 * Constant representing the value of an illegal override 267 * {@link IApiProblem} kind. <br> 268 * Value is: <code>5</code> 269 * 270 * @see #getKind() 271 * @see #CATEGORY_USAGE 272 */ 273 public static final int ILLEGAL_OVERRIDE = 5; 274 275 /** 276 * Constant representing the value of an API leak {@link IApiProblem} kind. <br> 277 * Value is: <code>6</code> 278 * 279 * @see #getKind() 280 * @see #CATEGORY_USAGE 281 */ 282 public static final int API_LEAK = 6; 283 284 /** 285 * Constant representing the value of an invalid API javadoc tag use 286 * {@link IApiProblem} kind <br> 287 * Value is: <code>7</code> 288 * 289 * @see #getKind() 290 * @see #CATEGORY_USAGE 291 */ 292 public static final int UNSUPPORTED_TAG_USE = 7; 293 294 /** 295 * Constant representing the value of a duplicate API Javadoc tag use 296 * {@link IApiProblem} kind <br> 297 * Value is: <code>8</code> 298 * 299 * @see #getKind() 300 * @see #CATEGORY_USAGE 301 */ 302 public static final int DUPLICATE_TAG_USE = 8; 303 304 /** 305 * Constant representing the value of an illegal reference inside system 306 * libraries use {@link IApiProblem} kind <br> 307 * Value is: <code>9</code> 308 * 309 * @see #getKind() 310 * @see #CATEGORY_USAGE 311 */ 312 public static final int INVALID_REFERENCE_IN_SYSTEM_LIBRARIES = 9; 313 /** 314 * Constant representing the value of an unused API problem filter 315 * {@link IApiProblem} kind <br> 316 * Value is:<code>10</code> 317 * 318 * @see #getKind() 319 * @see #CATEGORY_USAGE 320 */ 321 public static final int UNUSED_PROBLEM_FILTERS = 10; 322 /** 323 * Constant representing the value of missing EE descriptions if the 324 * preferences are configured to perform the system library scans 325 * {@link IApiProblem} kind <br> 326 * Value is:<code>11</code> 327 * 328 * @see #getKind() 329 * @see #CATEGORY_USAGE 330 * @since 1.0.400 331 */ 332 public static final int MISSING_EE_DESCRIPTIONS = 11; 333 /** 334 * Constant representing the value of a duplicate annotation in use <br> 335 * <br> 336 * Value is: <code>12</code> 337 * 338 * @see #getKind() 339 * @see #CATEGORY_USAGE 340 * @since 1.0.600 341 */ 342 public static final int DUPLICATE_ANNOTATION_USE = 12; 343 /** 344 * COnstant representing the value of an unsupported annotation in use <br> 345 * <br> 346 * Value is: <code>13</code> 347 * 348 * @since 1.0.600 349 */ 350 public static final int UNSUPPORTED_ANNOTATION_USE = 13; 351 /** 352 * Flags to indicate a leak from extending a non-API type. <br> 353 * Value is: <code>1</code> 354 * 355 * @see #getFlags() 356 * @see #CATEGORY_USAGE 357 */ 358 public static final int LEAK_EXTENDS = 1; 359 360 /** 361 * Flags to indicate a leak from implementing a non-API type. <br> 362 * Value is: <code>2</code> 363 * 364 * @see #getFlags() 365 * @see #CATEGORY_USAGE 366 */ 367 public static final int LEAK_IMPLEMENTS = 2; 368 369 /** 370 * Flags to indicate a leak from a field declaration. <br> 371 * Value is: <code>3</code> 372 * 373 * @see #getFlags() 374 * @see #CATEGORY_USAGE 375 */ 376 public static final int LEAK_FIELD = 3; 377 378 /** 379 * Flags to indicate a leak from a return type. <br> 380 * Value is: <code>4</code> 381 * 382 * @see #getFlags() 383 * @see #CATEGORY_USAGE 384 */ 385 public static final int LEAK_RETURN_TYPE = 4; 386 387 /** 388 * Flags to indicate a leak from a method parameter <br> 389 * Value is: <code>5</code> 390 * 391 * @see #getFlags() 392 * @see #CATEGORY_USAGE 393 */ 394 public static final int LEAK_METHOD_PARAMETER = 5; 395 396 /** 397 * Flags to indicate a leak from a constructor parameter <br> 398 * Value is: <code>6</code> 399 * 400 * @see #getFlags() 401 * @see #CATEGORY_USAGE 402 */ 403 public static final int LEAK_CONSTRUCTOR_PARAMETER = 6; 404 405 /** 406 * Flags to indicate a constructor method <br> 407 * Value is: <code>7</code> 408 * 409 * @see #getFlags() 410 * @see #CATEGORY_USAGE 411 */ 412 public static final int CONSTRUCTOR_METHOD = 7; 413 414 /** 415 * Flags to indicate a 'normal' method <br> 416 * Value is: <code>8</code> 417 * 418 * @see #getFlags() 419 * @see #CATEGORY_USAGE 420 */ 421 public static final int METHOD = 8; 422 423 /** 424 * Flags to indicate a field <br> 425 * Value is: <code>9</code> 426 * 427 * @see #getFlags() 428 * @see #CATEGORY_USAGE 429 */ 430 public static final int FIELD = 9; 431 432 /** 433 * Flags to indicate a local type (a class defined in a method) <br> 434 * Value is: <code>10</code> 435 * 436 * @see #getFlags() 437 * @see #CATEGORY_USAGE 438 */ 439 public static final int LOCAL_TYPE = 10; 440 441 /** 442 * Flags to indicate an anonymous type <br> 443 * Value is: <code>11</code> 444 * 445 * @see #getFlags() 446 * @see #CATEGORY_USAGE 447 */ 448 public static final int ANONYMOUS_TYPE = 11; 449 450 /** 451 * Flags to indicate an indirect reference <br> 452 * Value is: <code>12</code> 453 * 454 * @see #getFlags() 455 * @see #CATEGORY_USAGE 456 */ 457 public static final int INDIRECT_REFERENCE = 12; 458 459 /** 460 * Flags to indicate an indirect reference from a local type <br> 461 * Value is: <code>13</code> 462 * 463 * @see #getFlags() 464 * @see #CATEGORY_USAGE 465 */ 466 public static final int INDIRECT_LOCAL_REFERENCE = 13; 467 /** 468 * Flags to indicate a reference to an annotation <br> 469 * <br> 470 * Values is: <code>14</code> 471 * 472 * @see #getFlags() 473 * @see #CATEGORY_USAGE 474 * 475 * @since 1.0.600 476 */ 477 public static final int ANNOTATION = 14; 478 479 /** 480 * Constant representing the value of an API leak {@link IApiProblem} by 481 * extending a no extend class type <br> 482 * Value is: <code>15</code> 483 * 484 * @see #getFlags() 485 * @see #CATEGORY_USAGE 486 */ 487 public static final int LEAK_BY_EXTENDING_NO_EXTEND_CLASS_TYPE = 15; 488 489 /** 490 * Constant representing the value of an API leak {@link IApiProblem} by 491 * extending a no extend interface type <br> 492 * Value is: <code>16</code> 493 * 494 * @see #getFlags() 495 * @see #CATEGORY_USAGE 496 */ 497 public static final int LEAK_BY_EXTENDING_NO_EXTEND_INTERFACE_TYPE = 16; 498 499 /** 500 * Constant representing the value of a default API profile 501 * {@link IApiProblem} kind. <br> 502 * Value is: <code>1</code> 503 * 504 * @see #getKind() 505 * @see #CATEGORY_API_BASELINE 506 */ 507 public static final int API_BASELINE_MISSING = 1; 508 /** 509 * Constant representing possible API baseline mismatch {@link IApiProblem} 510 * kind. <br> 511 * Value is: <code>2</code> 512 * 513 * @see #getKind() 514 * @see #CATEGORY_API_BASELINE 515 */ 516 public static final int API_BASELINE_MISMATCH = 2; 517 518 /** 519 * Constant representing the value of a API component resolution 520 * {@link IApiProblem} kind. <br> 521 * Value is: <code>1</code> 522 * 523 * @see #getKind() 524 * @see #CATEGORY_API_COMPONENT_RESOLUTION 525 */ 526 public static final int API_COMPONENT_RESOLUTION = 1; 527 528 /** 529 * Constant representing the value of a workspace baseline resolution 530 * {@link IApiProblem} kind. <br> 531 * Value is: <code>1</code> 532 * 533 * @see #getKind() 534 * @see #CATEGORY_FATAL_PROBLEM 535 */ 536 public static final int FATAL_JDT_BUILDPATH_PROBLEM = 1; 537 /** 538 * Constant representing the value of a type {@link IApiProblem} kind. <br> 539 * Value is: <code>1</code> 540 * 541 * @see #getKind() 542 * @see #CATEGORY_API_USE_SCAN_PROBLEM 543 */ 544 public static final int API_USE_SCAN_TYPE_PROBLEM = 1; 545 /** 546 * Constant representing the value of a method {@link IApiProblem} kind. <br> 547 * Value is: <code>2</code> 548 * 549 * @see #getKind() 550 * @see #CATEGORY_API_USE_SCAN_PROBLEM 551 */ 552 public static final int API_USE_SCAN_METHOD_PROBLEM = 2; 553 /** 554 * Constant representing the value of a field {@link IApiProblem} kind. <br> 555 * Value is: <code>3</code> 556 * 557 * @see #getKind() 558 * @see #CATEGORY_API_USE_SCAN_PROBLEM 559 */ 560 public static final int API_USE_SCAN_FIELD_PROBLEM = 3; 561 /** 562 * Constant indicating a use scan reference cannot be resolved <br> 563 * Value is: <code>1</code> 564 * 565 * @see #getFlags() 566 * @see #CATEGORY_API_USE_SCAN_PROBLEM 567 * @since 1.0.400 568 */ 569 public static final int API_USE_SCAN_UNRESOLVED = 1; 570 /** 571 * Constant indicating a use scan reference has been deleted <br> 572 * Value is: <code>2</code> 573 * 574 * @see #getFlags() 575 * @see #CATEGORY_API_USE_SCAN_PROBLEM 576 * @since 1.0.400 577 */ 578 public static final int API_USE_SCAN_DELETED = 2; 579 580 /** 581 * Returns the severity of the problem. See the severity constants defined 582 * in {@link org.eclipse.pde.api.tools.internal.provisional.ApiPlugin} 583 * class. 584 * 585 * @return the severity of the problem 586 * @see org.eclipse.pde.api.tools.internal.provisional.ApiPlugin#SEVERITY_ERROR 587 * @see org.eclipse.pde.api.tools.internal.provisional.ApiPlugin#SEVERITY_WARNING 588 * @see org.eclipse.pde.api.tools.internal.provisional.ApiPlugin#SEVERITY_IGNORE 589 */ getSeverity()590 public int getSeverity(); 591 592 /** 593 * Returns the kind of element this problem is related to. 594 * 595 * @see IElementDescriptor#getElementType() 596 * @see IDelta#getElementType() 597 * 598 * @return the element kind this problem is related to. 599 */ getElementKind()600 public int getElementKind(); 601 602 /** 603 * Returns the id used to lookup the message for this problem. 604 * 605 * @return the message id 606 */ getMessageid()607 public int getMessageid(); 608 609 /** 610 * Returns the project relative path to the resource this problem was found 611 * in, or <code>null</code> if none. 612 * 613 * @return the project relative path to the resource the problem was found 614 * in, or null if none 615 */ getResourcePath()616 public String getResourcePath(); 617 618 /** 619 * Returns the fully qualified type name to the type this problem was found 620 * in, or <code>null</code> if none. 621 * 622 * @return the fully qualified type name to the type this problem , null if 623 * none. was found in 624 */ getTypeName()625 public String getTypeName(); 626 627 /** 628 * Returns the listing of message arguments passed in to the problem or an 629 * empty array, never <code>null</code> 630 * 631 * @return the message arguments passed to the problem or an empty array 632 */ getMessageArguments()633 public String[] getMessageArguments(); 634 635 /** 636 * Returns the start of the character selection to make, or -1 if there is 637 * no character starting position. 638 * 639 * @return the start of the character selection or -1. 640 */ getCharStart()641 public int getCharStart(); 642 643 /** 644 * Returns the end of the character selection to make, or -1 if there is no 645 * character ending position. 646 * 647 * @return the end of the character selection or -1 648 */ getCharEnd()649 public int getCharEnd(); 650 651 /** 652 * Returns the number of the line this problem occurred on, or -1 if there 653 * is no line number. 654 * 655 * @return the line number this problem occurred on or -1 656 */ getLineNumber()657 public int getLineNumber(); 658 659 /** 660 * Returns the category for this problem. Guaranteed to be one of: 661 * <ul> 662 * <li>{@link #CATEGORY_COMPATIBILITY}</li> 663 * <li>{@link #CATEGORY_USAGE}</li> 664 * <li>{@link #CATEGORY_VERSION}</li> 665 * <li>{@link #CATEGORY_SINCETAGS}</li> 666 * <li>{@link #CATEGORY_API_BASELINE}</li> 667 * <li>{@link #CATEGORY_API_COMPONENT_RESOLUTION}</li> 668 * <li>{@link #CATEGORY_FATAL_PROBLEM}</li> 669 * <li>{@link #CATEGORY_API_USE_SCAN_PROBLEM}</li> 670 * </ul> 671 * 672 * @return the category for the problem 673 */ getCategory()674 public int getCategory(); 675 676 /** 677 * Returns the unique id of the problem. A problem Id is the composition of 678 * the category, kind, flags and severity. 679 * 680 * @return the id of the problem 681 */ getId()682 public int getId(); 683 684 /** 685 * Returns a human readable, localized description of the problem 686 * 687 * @return the description of the problem 688 */ getMessage()689 public String getMessage(); 690 691 /** 692 * Returns the kind of this problem. 693 * 694 * @return the kind of this problem 695 */ getKind()696 public int getKind(); 697 698 /** 699 * Returns the flags for this problem. 700 * 701 * @return the flags for this problem 702 */ getFlags()703 public int getFlags(); 704 705 /** 706 * Returns the names of the extra marker attributes associated to this 707 * problem when persisted into a marker by the {@link ApiProblemReporter}. 708 * By default, no EXTRA attributes is persisted, and an {@link IApiProblem} 709 * only persists the following attributes: 710 * <ul> 711 * <li> <code>IMarker#MESSAGE</code> -> {@link IApiProblem#getMessage()}</li> 712 * <li> <code>IMarker#SEVERITY</code> -> {@link IApiProblem#getSeverity()} 713 * </li> 714 * <li> <code>IApiMarkerConstants#API_MARKER_ATTR_ID : String</code> -> 715 * {@link IApiProblem#getId()}</li> 716 * <li> <code>IMarker#CHAR_START</code> -> 717 * {@link IApiProblem#getCharStart()}</li> 718 * <li> <code>IMarker#CHAR_END</code> -> {@link IApiProblem#getCharEnd()}</li> 719 * <li> <code>IMarker#LINE_NUMBER</code> -> 720 * {@link IApiProblem#getLineNumber()}</li> 721 * </ul> 722 * The names must be eligible for marker creation, as defined by 723 * <code>IMarker#setAttributes(String[], Object[])</code>, and there must be 724 * as many names as values according to 725 * {@link #getExtraMarkerAttributeValues()}. Note that extra marker 726 * attributes will be inserted after default ones (as described in 727 * {@link CategorizedProblem#getMarkerType()}, and thus could be used to 728 * override defaults. 729 * 730 * @return the names of the corresponding marker attributes 731 */ getExtraMarkerAttributeIds()732 public String[] getExtraMarkerAttributeIds(); 733 734 /** 735 * Returns the respective values for the extra marker attributes associated 736 * to this problem when persisted into a marker by the JavaBuilder. Each 737 * value must correspond to a matching attribute name, as defined by 738 * {@link #getExtraMarkerAttributeIds()}. The values must be eligible for 739 * marker creation, as defined by 740 * <code> IMarker#setAttributes(String[], Object[])}. 741 * 742 * @return the values of the corresponding extra marker attributes 743 */ getExtraMarkerAttributeValues()744 public Object[] getExtraMarkerAttributeValues(); 745 } 746