ARTEMIS-3914 Document client classpath automated

artemis-maven-plugin/pom.xml

@@ -40,17 +40,17 @@
       <dependency>
          <groupId>org.apache.maven</groupId>
          <artifactId>maven-artifact</artifactId>
-         <version>3.8.2</version>
+         <version>3.8.5</version>
       </dependency>
       <dependency>
          <groupId>org.apache.maven</groupId>
          <artifactId>maven-project</artifactId>
-         <version>2.0.8</version>
+         <version>2.2.1</version>
       </dependency>
       <dependency>
          <groupId>org.eclipse.aether</groupId>
          <artifactId>aether-api</artifactId>
-         <version>1.0.2.v20150114</version>
+         <version>1.1.0</version>
       </dependency>
       <dependency>
          <groupId>org.apache.activemq</groupId>
@@ -75,7 +75,7 @@
       <dependency>
          <groupId>org.apache.maven.plugin-tools</groupId>
          <artifactId>maven-plugin-annotations</artifactId>
-         <version>3.4</version>
+         <version>3.6.4</version>
          <scope>provided</scope>
       </dependency>
    </dependencies>

artemis-maven-plugin/src/main/java/org/apache/activemq/artemis/maven/ArtemisAbstractPlugin.java

@@ -102,7 +102,13 @@ public abstract class ArtemisAbstractPlugin extends AbstractMojo {
       return artifact;
    }
 
-   protected File resolveArtifact(Artifact artifact) throws MojoExecutionException, DependencyCollectionException {
+   protected File resolveArtifactFile(Artifact artifact) throws MojoExecutionException, DependencyCollectionException {
+      ArtifactResult result = resolveArtifact(artifact);
+
+      return result.getArtifact().getFile();
+   }
+
+   protected ArtifactResult resolveArtifact(Artifact artifact) throws MojoExecutionException {
       ArtifactRequest request = new ArtifactRequest();
       request.setArtifact(artifact);
       request.setRepositories(remoteRepos);
@@ -113,8 +119,7 @@ public abstract class ArtemisAbstractPlugin extends AbstractMojo {
       } catch (ArtifactResolutionException e) {
          throw new MojoExecutionException(e.getMessage(), e);
       }
-
+      return result;
-      return result.getArtifact().getFile();
    }
 
    protected List<Artifact> explodeDependencies(Artifact artifact) throws DependencyCollectionException {
@@ -164,7 +169,7 @@ public abstract class ArtemisAbstractPlugin extends AbstractMojo {
             List<Artifact> artifactsList = explodeDependencies(newArtifact(lib));
 
             for (Artifact artifact : artifactsList) {
-               File artifactFile = resolveArtifact(artifact);
+               File artifactFile = resolveArtifactFile(artifact);
                filesSet.add(artifactFile);
             }
          }
@@ -174,7 +179,7 @@ public abstract class ArtemisAbstractPlugin extends AbstractMojo {
          for (String lib : individualListParameter) {
             Artifact artifact = newArtifact(lib);
             getLog().debug("Single dpendency resolved::" + artifact);
-            File artifactFile = resolveArtifact(artifact);
+            File artifactFile = resolveArtifactFile(artifact);
             filesSet.add(artifactFile);
          }
       }

artemis-maven-plugin/src/main/java/org/apache/activemq/artemis/maven/ArtemisDependencyDocPlugin.java

@@ -0,0 +1,257 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.activemq.artemis.maven;
+
+import java.io.BufferedOutputStream;
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.PrintStream;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import org.apache.maven.plugin.descriptor.PluginDescriptor;
+import org.apache.maven.plugins.annotations.LifecyclePhase;
+import org.apache.maven.plugins.annotations.Mojo;
+import org.apache.maven.plugins.annotations.Parameter;
+import org.apache.maven.project.MavenProject;
+import org.eclipse.aether.artifact.Artifact;
+import org.eclipse.aether.repository.RemoteRepository;
+import org.eclipse.aether.resolution.ArtifactResult;
+
+/** The following substitutions are made for each line
+ * X{group} with the groupID
+ * X{artifact} with the artifactID
+ * X{version} with the version
+ * X{classifier} with the classifier of the component
+ * X{package} a combination of the maven group:artifact:classifier
+ * X{url} with the url
+ * X{file} with the fileName
+ * X{fileMD} with the fileName on a LINK with MD style
+ * X{URI} with the URI
+ * X{detail} with the detail provided in the config */
+@Mojo(name = "dependency-doc", defaultPhase = LifecyclePhase.VERIFY)
+public class ArtemisDependencyDocPlugin extends ArtemisAbstractPlugin {
+
+   @Parameter
+   String name;
+
+   /**
+    * The plugin descriptor
+    */
+   private PluginDescriptor descriptor;
+
+   @Parameter
+   private String[] groupOrder;
+
+   @Parameter(defaultValue = "https://repo.maven.apache.org/maven2")
+   private String defaultRepo = "https://repo.maven.apache.org/maven2";
+
+   @Parameter
+   private String header;
+
+   @Parameter
+   private String lib;
+
+   @Parameter
+   private String line;
+
+   @Parameter
+   private String footer;
+
+   @Parameter
+   private String[] detailKey;
+
+   @Parameter String[] detailValue;
+
+   @Parameter
+   private String[] extraRepositories;
+
+   @Parameter
+   private String file;
+
+   private MavenProject project;
+
+   @Override
+   protected boolean isIgnore() {
+      return false;
+   }
+
+
+   private String applyFilters(String content, Map<String, String> filters) throws IOException {
+
+      if (filters != null) {
+         for (Map.Entry<String, String> entry : filters.entrySet()) {
+            try {
+               content = replace(content, entry.getKey(), entry.getValue());
+            } catch (Throwable e) {
+               System.out.println("Error on " + entry.getKey());
+               e.printStackTrace();
+            }
+         }
+      }
+      return content;
+   }
+
+
+   private String replace(String content, String key, String value) {
+      return content.replaceAll(Pattern.quote(key), Matcher.quoteReplacement(value));
+   }
+
+   private String getPackageName(org.eclipse.aether.artifact.Artifact artifact) {
+      return artifact.getGroupId() + ":" + artifact.getArtifactId() + (artifact.getClassifier() != null && !artifact.getClassifier().equals("") ? ":" + artifact.getClassifier() : "");
+   }
+
+   private String getGroupOrder(String group) {
+      if (groupOrder == null) {
+         groupOrder = new String[] {"org.apache.activemq"};
+      }
+
+      int i = 0;
+      for (; i < groupOrder.length; i++) {
+         if (group.equals(groupOrder[i])) {
+            return Integer.toString(i);
+         }
+      }
+      return Integer.toString(i);
+   }
+
+   @Override
+   protected void doExecute() {
+
+      HashMap<String, String> keys = new HashMap<>();
+
+      if (detailKey != null) {
+         if (detailValue == null) {
+            throw new IllegalStateException("you need to specify all detail parameters");
+         }
+
+         if (detailKey.length != detailValue.length) {
+            throw new IllegalStateException("Illegal argument size");
+         }
+
+         for (int i = 0; i < detailKey.length; i++) {
+            keys.put(detailKey[i], detailValue[i]);
+         }
+      }
+
+      if (file == null) {
+         throw new IllegalStateException("you must specify the file output");
+      }
+
+      if (line == null) {
+         throw new IllegalStateException("you must specify the line");
+      }
+
+
+      try {
+         File javaFile = new File(file);
+         javaFile.getParentFile().mkdirs();
+
+         PrintStream stream = new PrintStream(new BufferedOutputStream(new FileOutputStream(file)));
+
+         if (header != null) {
+            stream.println(header);
+         }
+
+         List<org.eclipse.aether.artifact.Artifact> artifacts = explodeDependencies(newArtifact(lib));
+
+         Collections.sort(artifacts, new Comparator<Artifact>() {
+            @Override
+            public int compare(Artifact o1, Artifact o2) {
+               String pref1 = getGroupOrder(o1.getGroupId());
+               String pref2 = getGroupOrder(o2.getGroupId());
+               return (pref1 + o1.getGroupId() + o1.getArtifactId()).compareTo(pref2 + o2.getGroupId() + o2.getArtifactId());
+            }
+         });
+
+         artifacts.forEach((art) -> {
+            try {
+
+               String detail = keys.get(art.getGroupId() + ":" + art.getArtifactId());
+               if (detail == null) {
+                  detail = "";
+               }
+
+               ArtifactResult result = resolveArtifact(art);
+
+               HashMap<String, String> filter = new HashMap<>();
+               filter.put("X{detail}", detail);
+               filter.put("X{group}", art.getGroupId());
+               filter.put("X{artifact}", art.getArtifactId());
+               filter.put("X{classifier}", result.getArtifact().getClassifier());
+               filter.put("X{package}", getPackageName(result.getArtifact()));
+               filter.put("X{file}", result.getArtifact().getFile().getName());
+               filter.put("X{version}", result.getArtifact().getVersion());
+
+               String uri = getURI(result);
+
+               filter.put("X{uri}", uri);
+
+               if (uri.equals("")) {
+                  filter.put("X{fileMD}", result.getArtifact().getFile().getName());
+               } else {
+                  filter.put("X{fileMD}", "[" + result.getArtifact().getFile().getName() + "](" + uri + ")");
+               }
+
+               String output = applyFilters(line, filter);
+
+               if (getLog().isDebugEnabled()) {
+                  filter.forEach((a, b) -> {
+                     getLog().debug("filter.put(" + a + ", " + b + ")");
+                  });
+                  getLog().debug(output);
+               }
+
+
+               stream.println(output);
+
+            } catch (Exception e) {
+               throw new RuntimeException(e.getMessage(), e);
+            }
+         });
+         if (footer != null) {
+            stream.println(footer);
+         }
+         stream.close();
+      } catch (Throwable e) {
+         getLog().error(e.getMessage(), e);
+      }
+   }
+
+   private String getURI(ArtifactResult result) {
+      Artifact art = result.getArtifact();
+      String uri = "";
+      if (result.getRepository() instanceof RemoteRepository) {
+         RemoteRepository remoteRepository = (RemoteRepository) result.getRepository();
+         uri = remoteRepository.getUrl();
+      } else {
+         uri = defaultRepo;
+      }
+
+      return uri + "/" +
+            art.getGroupId().replace('.', '/') + "/" +
+            art.getArtifactId() + "/" +
+            art.getVersion();
+   }
+
+}

artemis-website/pom.xml

@@ -199,6 +199,85 @@
                     <skip>${skipWebsiteDocGeneration}</skip>
                   </configuration>
                </plugin>
+               <plugin>
+                  <groupId>org.apache.activemq</groupId>
+                  <artifactId>artemis-maven-plugin</artifactId>
+                  <version>${project.version}</version>
+                  <executions>
+                     <execution>
+                        <id>doc-jms-client</id>
+                        <phase>generate-sources</phase>
+                        <goals>
+                           <goal>dependency-doc</goal>
+                        </goals>
+                        <configuration>
+                           <file>${scratch-dir-user-manual}/client-classpath-jms.md</file>
+                           <groupOrder>
+                              <arg>org.apache.activemq</arg>
+                              <arg>jakarta.jms</arg>
+                              <arg>org.jgroups</arg>
+                              <arg>io.netty</arg>
+                           </groupOrder>
+                           <header>#Artemis JMS Client Dependencies
+
+File | observation | package
+---|---|---</header>
+                           <line>X{fileMD}| X{detail} |X{package} </line>
+                           <detailKey>
+                              <arg>io.netty:netty-transport-native-epoll</arg>
+                              <arg>io.netty:netty-transport-classes-epoll</arg>
+                              <arg>io.netty:netty-transport-native-kqueue</arg>
+                              <arg>io.netty:netty-transport-classes-kqueue</arg>
+                              <arg>org.jgroups:jgroups</arg>
+                           </detailKey>
+                           <detailValue>
+                              <arg>only if you want epoll on Linux</arg>
+                              <arg>only if you want epoll on Linux</arg>
+                              <arg>only if you want kqueue on MacOS</arg>
+                              <arg>only if you want kqueue on MacOS</arg>
+                              <arg>only if you want JGroups discovery from the clients</arg>
+                           </detailValue>
+                           <lib>org.apache.activemq:artemis-jms-client:${project.version}</lib>
+                        </configuration>
+                     </execution>
+                     <execution>
+                        <id>doc-jakarta-client</id>
+                        <phase>generate-sources</phase>
+                        <goals>
+                           <goal>dependency-doc</goal>
+                        </goals>
+                        <configuration>
+                           <file>${scratch-dir-user-manual}/client-classpath-jakarta.md</file>
+                           <groupOrder>
+                              <arg>org.apache.activemq</arg>
+                              <arg>jakarta.jms</arg>
+                              <arg>org.jgroups</arg>
+                              <arg>io.netty</arg>
+                           </groupOrder>
+                           <header>#Artemis Jakarta Client Dependencies
+File | observation | package
+---|---|---</header>
+                           <line>X{fileMD}| X{detail} |X{package} </line>
+                           <detailKey>
+                              <arg>io.netty:netty-transport-native-epoll</arg>
+                              <arg>io.netty:netty-transport-classes-epoll</arg>
+                              <arg>io.netty:netty-transport-native-kqueue</arg>
+                              <arg>io.netty:netty-transport-classes-kqueue</arg>
+                              <arg>org.jgroups:jgroups</arg>
+                           </detailKey>
+                           <detailValue>
+                              <arg>only if you want epoll on Linux</arg>
+                              <arg>only if you want epoll on Linux</arg>
+                              <arg>only if you want kqueue on MacOS</arg>
+                              <arg>only if you want kqueue on MacOS</arg>
+                              <arg>only if you want JGroups discovery from the clients</arg>
+                           </detailValue>
+                           <lib>org.apache.activemq:artemis-jakarta-client:${project.version}</lib>
+                        </configuration>
+                     </execution>
+                  </executions>
+               </plugin>
+
                <plugin>
                   <artifactId>maven-antrun-plugin</artifactId>
                   <executions>

docs/user-manual/en/SUMMARY.md

@@ -22,6 +22,8 @@
 * [Mapping JMS Concepts to the Core API](jms-core-mapping.md)
 * [Using JMS](using-jms.md)
 * [The Client Classpath](client-classpath.md)
+    * [JMS](client-classpath-jms.md)
+    * [Jakarta](client-classpath-jakarta.md)
 * [Examples](examples.md)
 * [Routing Messages With Wild Cards](wildcard-routing.md)
 * [Wildcard Syntax](wildcard-syntax.md)

docs/user-manual/en/client-classpath-jakarta.md

@@ -0,0 +1 @@
+This file will be generated/replaced in compile time by artemis-website

docs/user-manual/en/client-classpath-jms.md

@@ -0,0 +1 @@
+This file will be generated/replaced in compile time by artemis-website

docs/user-manual/en/client-classpath.md

@@ -10,7 +10,59 @@ Apache ActiveMQ Artemis requires just a single jar on the *client classpath*.
 > jars from different Apache ActiveMQ Artemis versions. Mixing and matching
 > different jar versions may cause subtle errors and failures to occur.
 
+
+## Maven Packages
+
+The best way to define a client dependency to your java application is through a maven dependency declaration.
+
+There are two packages you can choose from, org.apache.activemq:artemis-jms-client or org.apache.activemq:artemis-jakarta-client for both JMS and Jakarta APIs.
+
+Say you define artemis-version as '{{ config.version }}':
+
+For JMS:
+```xml
+...
+<dependency>
+   <groupId>org.apache.activemq</groupId>
+   <artifactId>artemis-jms-client</artifactId>
+   <version>${artemis-version}</version>
+</dependency>
+...
+```
+
+For Jakarta:
+```xml
+...
+<dependency>
+   <groupId>org.apache.activemq</groupId>
+   <artifactId>artemis-jakarta-client</artifactId>
+   <version>${artemis-version}</version>
+</dependency>
+...
+```
+
+## All clients
+
+Even though it is highly recommend using maven, in case this is not a possibility the all inclusive jars could be used. 
+
+These jars will be available under ./lib/client on the main distribution:
+
+- artemis-jakarta-client-all-{{ config.version }}.jar
+- artemis-jms-client-all-{{ config.version }}.jar
+
 Whether you are using JMS or just the Core API simply add the
 `artemis-jms-client-all.jar` from the `lib/client` directory to your client
-classpath. This is a "shaded" jar that contains all the Artemis code plus
+classpath. 
-dependencies (e.g.  JMS spec, Netty, etc.).
+
+
+**Warning:**These jars will include all the [client's dependencies](client-classpath-jms.md). Be careful with mixing other jars in your application as they may clash with other.
+
+
+## Individual dependencies
+
+You may also choose to use the jars individually as they are all included under ./lib on the main distribution.
+
+For more information:
+
+- [client jms dependencies](client-classpath-jms.md )
+- [client jakarta dependencies](client-classpath-jakarta.md)