001/* 002 * SonarQube 003 * Copyright (C) 2009-2017 SonarSource SA 004 * mailto:info AT sonarsource DOT com 005 * 006 * This program is free software; you can redistribute it and/or 007 * modify it under the terms of the GNU Lesser General Public 008 * License as published by the Free Software Foundation; either 009 * version 3 of the License, or (at your option) any later version. 010 * 011 * This program is distributed in the hope that it will be useful, 012 * but WITHOUT ANY WARRANTY; without even the implied warranty of 013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 * Lesser General Public License for more details. 015 * 016 * You should have received a copy of the GNU Lesser General Public License 017 * along with this program; if not, write to the Free Software Foundation, 018 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 019 */ 020package org.sonar.api; 021 022import java.util.ArrayList; 023import java.util.Collection; 024import java.util.List; 025import org.sonar.api.utils.Version; 026 027import static java.util.Arrays.asList; 028import static java.util.Objects.requireNonNull; 029 030/** 031 * Entry-point for plugins to inject extensions into SonarQube. 032 * <p>The JAR manifest must declare the name of the implementation class in the property <code>Plugin-Class</code>. 033 * This property is automatically set by sonar-packaging-maven-plugin when building plugin. 034 * <p>Example of implementation 035 * <pre> 036 * public class MyPlugin implements Plugin { 037 * {@literal @}Override 038 * public void define(Context context) { 039 * context.addExtensions(MySensor.class, MyRules.class); 040 * if (context.getSonarQubeVersion().isGreaterThanOrEqual(Version.create(6, 0))) { 041 * // Extension which supports only versions 6.0 and greater 042 * // See org.sonar.api.SonarRuntime for more details. 043 * context.addExtension(MyNewExtension.class); 044 * } 045 * } 046 * } 047 * </pre> 048 * 049 * <p>Example of pom.xml 050 * <pre> 051 * <project> 052 * ... 053 * <packaging>sonar-plugin</packaging> 054 * 055 * <build> 056 * <plugins> 057 * <plugin> 058 * <groupId>org.sonarsource.sonar-packaging-maven-plugin</groupId> 059 * <artifactId>sonar-packaging-maven-plugin</artifactId> 060 * <extensions>true</extensions> 061 * <configuration> 062 * <pluginClass>com.mycompany.sonarqube.MyPlugin</pluginClass> 063 * </configuration> 064 * </plugin> 065 * </plugins> 066 * </build> 067 * </project> 068 * </pre> 069 * 070 * <p>Example of test 071 * <pre> 072 *{@literal @}Test 073 * public void test_plugin_extensions_compatible_with_5_6() { 074 * SonarRuntime runtime = SonarRuntimeImpl.forSonarQube(Version.create(5, 6), SonarQubeSide.SCANNER); 075 * Plugin.Context context = new Plugin.Context(runtime); 076 * new MyPlugin().define(context); 077 * assertThat(context.getExtensions()).hasSize(4); 078 * } 079 * </pre> 080 * 081 * @since 5.5 082 */ 083public interface Plugin { 084 085 class Context { 086 private final SonarRuntime sonarRuntime; 087 private final List extensions = new ArrayList(); 088 089 public Context(SonarRuntime sonarRuntime) { 090 this.sonarRuntime = sonarRuntime; 091 } 092 093 /** 094 * Shortcut on {@code getRuntime().getApiVersion()} since version 6.0. 095 * 096 * @see #getRuntime() 097 * @since 5.5 098 * @return the version of SonarQube API at runtime, not at compilation time 099 */ 100 public Version getSonarQubeVersion() { 101 return sonarRuntime.getApiVersion(); 102 } 103 104 /** 105 * Runtime environment. Can be use to add some extensions only on some conditions. 106 * @since 6.0 107 */ 108 public SonarRuntime getRuntime() { 109 return sonarRuntime; 110 } 111 112 /** 113 * Add an extension as : 114 * <ul> 115 * <li>a Class that is annotated with {@link org.sonar.api.batch.ScannerSide}, {@link org.sonar.api.server.ServerSide} 116 * or {@link org.sonar.api.ce.ComputeEngineSide}. The extension will be instantiated once. Its dependencies are 117 * injected through constructor parameters.</li> 118 * <li>an instance that is annotated with {@link org.sonar.api.batch.ScannerSide}, {@link org.sonar.api.server.ServerSide} 119 * or {@link org.sonar.api.ce.ComputeEngineSide}.</li> 120 * </ul> 121 * Only a single component can be registered for a class. It's not allowed for example to register: 122 * <ul> 123 * <li>two MyExtension.class</li> 124 * <li>MyExtension.class and new MyExtension()</li> 125 * </ul> 126 */ 127 public Context addExtension(Object extension) { 128 requireNonNull(extension); 129 this.extensions.add(extension); 130 return this; 131 } 132 133 /** 134 * @see #addExtension(Object) 135 */ 136 public Context addExtensions(Collection extensions) { 137 this.extensions.addAll(extensions); 138 return this; 139 } 140 141 /** 142 * @see #addExtension(Object) 143 */ 144 public Context addExtensions(Object first, Object second, Object... others) { 145 addExtension(first); 146 addExtension(second); 147 addExtensions(asList(others)); 148 return this; 149 } 150 151 public List getExtensions() { 152 return extensions; 153 } 154 155 } 156 157 /** 158 * This method is executed at runtime when: 159 * <ul> 160 * <li>Web Server starts</li> 161 * <li>Compute Engine starts</li> 162 * <li>Scanner starts</li> 163 * </ul> 164 */ 165 void define(Context context); 166}