001/*
002 * SonarQube
003 * Copyright (C) 2009-2016 SonarSource SA
004 * mailto:contact 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 javax.annotation.concurrent.Immutable;
023import org.sonar.api.batch.BatchSide;
024import org.sonar.api.batch.sensor.Sensor;
025import org.sonar.api.ce.ComputeEngineSide;
026import org.sonar.api.server.ServerSide;
027import org.sonar.api.utils.Version;
028
029import static java.util.Objects.requireNonNull;
030
031/**
032 * Version of SonarQube at runtime. This component can be injected as a dependency
033 * of plugin extensions. The main usage for a plugin is to benefit from new APIs
034 * while keeping backward-compatibility with previous versions of SonarQube.
035 * <br><br>
036 * 
037 * Example 1: a {@link Sensor} wants to use an API introduced in version 5.5 and still requires to support older versions
038 * at runtime.
039 * <pre>
040 * public class MySensor implements Sensor {
041 *
042 *   public void execute(SensorContext context) {
043 *     if (context.getSonarQubeVersion().isGreaterThanOrEqual(SonarQubeVersion.V5_5)) {
044 *       context.newMethodIntroducedIn5_5();
045 *     }
046 *   }
047 * }
048 * </pre>
049 *
050 * Example 2: a plugin needs to use an API introduced in version 5.6 ({@code AnApi} in the following
051 * snippet) and still requires to support version 5.5 at runtime.
052 * <br>
053 * <pre>
054 * // Component provided by sonar-plugin-api
055 * // @since 5.5
056 * public interface AnApi {
057 *   // implicitly since 5.5
058 *   public void foo();
059 *
060 *   // @since 5.6
061 *   public void bar();
062 * }
063 * 
064 * // Component provided by plugin
065 * public class MyExtension {
066 *   private final SonarQubeVersion sonarQubeVersion;
067 *   private final AnApi api;
068 *
069 *   public MyExtension(SonarQubeVersion sonarQubeVersion, AnApi api) {
070 *     this.sonarQubeVersion = sonarQubeVersion;
071 *     this.api = api;
072 *   }
073 *
074 *   public void doSomething() {
075 *     // assume that runtime is 5.5+
076 *     api.foo();
077 *
078 *     if (sonarQubeVersion.isGreaterThanOrEqual(SonarQubeVersion.V5_6)) {
079 *       api.bar();
080 *     }
081 *   }
082 * }
083 * </pre>
084 * <p>
085 * The minimal supported version of SonarQube is verified at runtime. As plugin is built
086 * with sonar-plugin-api 5.6, we assume that the plugin requires v5.6 or greater at runtime.
087 * For this reason the plugin must default which is the minimal supported version
088 * in the configuration of sonar-packaging-maven-plugin 1.16+:
089 * <p>
090 * <pre>
091 * &lt;packaging&gt;sonar-plugin&lt;/packaging&gt;
092 *
093 * &lt;dependencies&gt;
094 *   &lt;dependency&gt;
095 *     &lt;groupId&gt;org.sonarsource.sonarqube&lt;/groupId&gt;
096 *     &lt;artifactId&gt;sonar-plugin-api&lt;/artifactId&gt;
097 *     &lt;version&gt;5.6&lt;/version&gt;
098 *     &lt;scope&gt;provided&lt;/scope&gt;
099 *   &lt;/dependency&gt;
100 * &lt;/dependencies&gt;
101 *
102 * &lt;build&gt;
103 *  &lt;plugins&gt;
104 *    &lt;plugin&gt;
105 *      &lt;groupId&gt;org.sonarsource.sonar-packaging-maven-plugin&lt;/groupId&gt;
106 *      &lt;artifactId&gt;sonar-packaging-maven-plugin&lt;/artifactId&gt;
107 *      &lt;version&gt;1.16&lt;/version&gt;
108 *      &lt;extensions&gt;true&lt;/extensions&gt;
109 *      &lt;configuration&gt;
110 *        &lt;!-- Override the default value 5.6 which is guessed from sonar-plugin-api dependency --&gt;
111 *        &lt;sonarQubeMinVersion&gt;5.5&lt;/sonarQubeMinVersion&gt;
112 *      &lt;/configuration&gt;
113 *    &lt;/plugin&gt;
114 *  &lt;/plugins&gt;
115 * &lt;/build&gt;
116 * </pre>
117 *
118 *
119 * @since 5.5
120 */
121@BatchSide
122@ServerSide
123@ComputeEngineSide
124@Immutable
125public class SonarQubeVersion {
126
127  /**
128   * Constant for version 5.5
129   */
130  public static final Version V5_5 = Version.create(5, 5);
131
132  /**
133   * Constant for version 5.6
134   */
135  public static final Version V5_6 = Version.create(5, 6);
136
137  private final Version version;
138
139  public SonarQubeVersion(Version version) {
140    requireNonNull(version);
141    this.version = version;
142  }
143
144  public Version get() {
145    return this.version;
146  }
147
148  public boolean isGreaterThanOrEqual(Version than) {
149    return this.version.isGreaterThanOrEqual(than);
150  }
151
152}