Add support for API Tools Annotations to Tycho

RELEASE_NOTES.md

@@ -6,6 +6,25 @@ If you are reading this in the browser, then you can quickly jump to specific ve
 
 ## 5.0.0 (under development)
 
+### support for PDE Api Tools Annotations
+
+Tycho now supports PDE Api Tools Annotations to be added to the project automatically.
+
+To enable this add
+
+```xml
+<plugin>
+	<groupId>org.eclipse.tycho</groupId>
+	<artifactId>tycho-apitools-plugin</artifactId>
+	<version>${tycho-version}</version>
+</plugin>	
+```
+
+to your project and make sure it has the `org.eclipse.pde.api.tools.apiAnalysisNature` nature enabled in the `.project` file, for details how to use these see:
+
+- https://help.eclipse.org/latest/topic/org.eclipse.pde.doc.user/reference/api-tooling/api_javadoc_tags.htm
+- https://help.eclipse.org/latest/topic/org.eclipse.pde.doc.user/reference/api/org/eclipse/pde/api/tools/annotations/package-summary.html
+
 ### new tycho-repository-plugin
 
 Tycho now contains a new `tycho-repository-plugin` that can be used to package OSGi repositories.

tycho-apitools-plugin/src/main/java/org/eclipse/tycho/apitools/ApiAnalysisMojo.java

@@ -138,7 +138,7 @@ public void execute() throws MojoExecutionException, MojoFailureException {
 		}
 		Optional<EclipseProject> eclipseProject = projectManager.getEclipseProject(project);
 		if (eclipseProject.isEmpty()
-				|| !eclipseProject.get().hasNature("org.eclipse.pde.api.tools.apiAnalysisNature")) {
+				|| !eclipseProject.get().hasNature(ApiPlugin.NATURE_ID)) {
 			return;
 		}
 

tycho-apitools-plugin/src/main/java/org/eclipse/tycho/apitools/ApiAnnotationsClasspathContributor.java

@@ -0,0 +1,60 @@
+/*******************************************************************************
+ * Copyright (c) 2023 Christoph Läubrich and others.
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License 2.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Contributors:
+ *    Christoph Läubrich - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.tycho.apitools;
+
+import java.util.Optional;
+
+import javax.inject.Inject;
+
+import org.apache.maven.SessionScoped;
+import org.apache.maven.execution.MavenSession;
+import org.apache.maven.project.MavenProject;
+import org.codehaus.plexus.component.annotations.Component;
+import org.eclipse.pde.api.tools.internal.provisional.ApiPlugin;
+import org.eclipse.tycho.classpath.ClasspathContributor;
+import org.eclipse.tycho.core.TychoProjectManager;
+import org.eclipse.tycho.core.osgitools.AbstractSpecificationClasspathContributor;
+import org.eclipse.tycho.model.project.EclipseProject;
+import org.osgi.framework.VersionRange;
+
+@Component(role = ClasspathContributor.class, hint = "apitools-annotations")
+@SessionScoped
+public class ApiAnnotationsClasspathContributor extends AbstractSpecificationClasspathContributor {
+
+	private static final String PACKAGE_NAME = "org.eclipse.pde.api.tools.annotations";
+	private static final String GROUP_ID = "org.eclipse.pde";
+	private static final String ARTIFACT_ID = "org.eclipse.pde.api.tools.annotations";
+	private static final VersionRange VERSION = new VersionRange("[1,2)");
+	private TychoProjectManager projectManager;
+
+	@Inject
+	public ApiAnnotationsClasspathContributor(MavenSession session, TychoProjectManager projectManager) {
+		super(session, PACKAGE_NAME, GROUP_ID, ARTIFACT_ID);
+		this.projectManager = projectManager;
+	}
+
+	@Override
+	protected VersionRange getSpecificationVersion(MavenProject project) {
+		return VERSION;
+	}
+
+	@Override
+	protected boolean isValidProject(MavenProject project) {
+		Optional<EclipseProject> eclipseProject = projectManager.getEclipseProject(project);
+		if (eclipseProject.isPresent()) {
+			return eclipseProject.get().hasNature(ApiPlugin.NATURE_ID);
+		}
+		return false;
+	}
+
+}

tycho-core/src/main/java/org/eclipse/tycho/core/osgitools/AbstractSpecificationClasspathContributor.java

@@ -66,18 +66,24 @@ protected AbstractSpecificationClasspathContributor(MavenSession session, String
 
     @Override
     public final List<ClasspathEntry> getAdditionalClasspathEntries(MavenProject project, String scope) {
-        VersionRange specificationVersion = getSpecificationVersion(project);
-        Optional<ResolvedArtifactKey> mavenBundle = findBundle(project, specificationVersion);
-        if (mavenBundle.isPresent()) {
-            ResolvedArtifactKey resolved = mavenBundle.get();
-            logger.debug("Resolved " + packageName + " to " + resolved.getId() + " " + resolved.getVersion() + " @ "
-                    + resolved.getLocation());
-            return List.of(new DefaultClasspathEntry(resolved, List.of(accessRule)));
+        if (isValidProject(project)) {
+            VersionRange specificationVersion = getSpecificationVersion(project);
+            Optional<ResolvedArtifactKey> mavenBundle = findBundle(project, specificationVersion);
+            if (mavenBundle.isPresent()) {
+                ResolvedArtifactKey resolved = mavenBundle.get();
+                logger.debug("Resolved " + packageName + " to " + resolved.getId() + " " + resolved.getVersion() + " @ "
+                        + resolved.getLocation());
+                return List.of(new DefaultClasspathEntry(resolved, List.of(accessRule)));
+            }
+            logger.warn("Cannot resolve specification package " + packageName + ", classpath might be incomplete");
         }
-        logger.warn("Cannot resolve specification package " + packageName + ", classpath might be incomplete");
         return Collections.emptyList();
     }
 
+    protected boolean isValidProject(MavenProject project) {
+        return true;
+    }
+
     protected Optional<ResolvedArtifactKey> findBundle(MavenProject project, VersionRange specificationVersion) {
         Optional<ResolvedArtifactKey> mavenBundle = mavenBundleResolver.resolveMavenBundle(project, session,
                 MavenArtifactKey.of(PublisherHelper.CAPABILITY_NS_JAVA_PACKAGE, packageName,

tycho-its/projects/api-tools/annotations/.classpath

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
+	<classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"/>
+	<classpathentry kind="src" path="src/"/>
+	<classpathentry kind="output" path="bin"/>
+</classpath>

tycho-its/projects/api-tools/annotations/.project

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>api-bundle-2</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.ManifestBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.SchemaBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.api.tools.apiAnalysisBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+		<nature>org.eclipse.pde.PluginNature</nature>
+ 		<nature>org.eclipse.pde.api.tools.apiAnalysisNature</nature>
+	</natures>
+</projectDescription>

tycho-its/projects/api-tools/annotations/META-INF/MANIFEST.MF

@@ -0,0 +1,8 @@
+Manifest-Version: 1.0
+Bundle-ManifestVersion: 2
+Bundle-Name: Plugin with API
+Bundle-SymbolicName: api-bundle-2
+Bundle-Version: 0.0.1.qualifier
+Require-Capability: osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=11))"
+Export-Package: bundle
+Automatic-Module-Name: bundle

tycho-its/projects/api-tools/annotations/build.properties

@@ -0,0 +1,4 @@
+source.. = src/
+output.. = bin/
+bin.includes = .,\
+               META-INF/

tycho-its/projects/api-tools/annotations/pom.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project>
+	<modelVersion>4.0.0</modelVersion>
+	<groupId>org.eclipse.tycho.tycho-its</groupId>
+	<artifactId>api-bundle-2</artifactId>
+	<version>0.0.1-SNAPSHOT</version>
+	<packaging>eclipse-plugin</packaging>
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.eclipse.tycho</groupId>
+				<artifactId>tycho-maven-plugin</artifactId>
+				<version>${tycho-version}</version>
+				<extensions>true</extensions>
+			</plugin>
+			<plugin>
+				<groupId>org.eclipse.tycho</groupId>
+				<artifactId>tycho-apitools-plugin</artifactId>
+				<version>${tycho-version}</version>
+			</plugin>
+		</plugins>
+	</build>
+</project>

tycho-its/projects/api-tools/annotations/src/bundle/ApiInterface2.java

@@ -0,0 +1,10 @@
+package bundle;
+
+import org.eclipse.pde.api.tools.annotations.NoExtend;
+
+@NoExtend
+public interface ApiInterface2 {
+
+	void sayHello();
+
+}

tycho-its/src/test/java/org/eclipse/tycho/test/apitools/ApiToolsTest.java

@@ -142,4 +142,11 @@ public void testSingleJar() throws Exception {
 		verifier.executeGoals(List.of("clean", "verify"));
 		verifier.verifyErrorFreeLog();
 	}
+
+	@Test
+	public void testAnnotations() throws Exception {
+		Verifier verifier = getVerifier("api-tools/annotations", true, true);
+		verifier.executeGoals(List.of("clean", "verify"));
+		verifier.verifyErrorFreeLog();
+	}
 }