/hudson-core/src/main/java/hudson/scm/ChangeLogAnnotator.java

http://github.com/hudson/hudson · Java · 113 lines · 24 code · 7 blank · 82 comment · 0 complexity · d48b664410a4f891d04f072d88729481 MD5 · raw file

  1. /*
  2. * The MIT License
  3. *
  4. * Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi
  5. *
  6. * Permission is hereby granted, free of charge, to any person obtaining a copy
  7. * of this software and associated documentation files (the "Software"), to deal
  8. * in the Software without restriction, including without limitation the rights
  9. * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  10. * copies of the Software, and to permit persons to whom the Software is
  11. * furnished to do so, subject to the following conditions:
  12. *
  13. * The above copyright notice and this permission notice shall be included in
  14. * all copies or substantial portions of the Software.
  15. *
  16. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17. * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18. * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19. * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20. * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  21. * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  22. * THE SOFTWARE.
  23. */
  24. package hudson.scm;
  25. import hudson.ExtensionPoint;
  26. import hudson.MarkupText;
  27. import hudson.ExtensionListView;
  28. import hudson.Extension;
  29. import hudson.ExtensionList;
  30. import hudson.util.CopyOnWriteList;
  31. import hudson.scm.ChangeLogSet.Entry;
  32. import hudson.model.AbstractBuild;
  33. import hudson.model.Hudson;
  34. import java.util.logging.Logger;
  35. /**
  36. * Performs mark up on changelog messages to be displayed.
  37. *
  38. * <p>
  39. * SCM changelog messages are usually plain text, but when we display that in Hudson,
  40. * it is often nice to be able to put mark up on the text (for example to link to
  41. * external issue tracking system.)
  42. *
  43. * <p>
  44. * Plugins that are interested in doing so may extend this class and put {@link Extension} on it.
  45. * When multiple annotators are registered, their results will be combined.
  46. *
  47. * @author Kohsuke Kawaguchi
  48. * @since 1.70
  49. */
  50. public abstract class ChangeLogAnnotator implements ExtensionPoint {
  51. /**
  52. * Called by Hudson to allow markups to be added to the changelog text.
  53. *
  54. * <p>
  55. * This method is invoked each time a page is rendered, so implementations
  56. * of this method should not take too long to execute. Also note that
  57. * this method may be invoked concurrently by multiple threads.
  58. *
  59. * <p>
  60. * If there's any error during the processing, it should be recorded in
  61. * {@link Logger} and the method should return normally.
  62. *
  63. * @param build
  64. * Build that owns this changelog. From here you can access broader contextual
  65. * information, like the project, or it settings. Never null.
  66. * @param change
  67. * The changelog entry for which this method is adding markup.
  68. * Never null.
  69. * @param text
  70. * The text and markups. Implementation of this method is expected to
  71. * add additional annotations into this object. If other annotators
  72. * are registered, the object may already contain some markups when this
  73. * method is invoked. Never null. {@link MarkupText#getText()} on this instance
  74. * will return the same string as {@link Entry#getMsgEscaped()}.
  75. */
  76. public abstract void annotate(AbstractBuild<?,?> build, Entry change, MarkupText text );
  77. /**
  78. * Registers this annotator, so that Hudson starts using this object
  79. * for adding markup.
  80. *
  81. * @deprecated as of 1.286
  82. * Prefer automatic registration via {@link Extension}
  83. */
  84. public final void register() {
  85. all().add(this);
  86. }
  87. /**
  88. * Unregisters this annotator, so that Hudson stops using this object.
  89. */
  90. public final boolean unregister() {
  91. return all().remove(this);
  92. }
  93. /**
  94. * All registered {@link ChangeLogAnnotator}s.
  95. *
  96. * @deprecated as of 1.286
  97. * Use {@link #all()} for read access, and {@link Extension} for registration.
  98. */
  99. public static final CopyOnWriteList<ChangeLogAnnotator> annotators = ExtensionListView.createCopyOnWriteList(ChangeLogAnnotator.class);
  100. /**
  101. * Returns all the registered {@link ChangeLogAnnotator} descriptors.
  102. */
  103. public static ExtensionList<ChangeLogAnnotator> all() {
  104. return Hudson.getInstance().getExtensionList(ChangeLogAnnotator.class);
  105. }
  106. }