ARTEMIS-4533: some fixups, cleanups, and linking more bits to the exa…

…mples page of docs
apache · Dec 18, 2023 · b0f817e · b0f817e
1 parent 7903f58
commit b0f817e
Show file tree

Hide file tree

Showing 13 changed files with 20 additions and 32 deletions.
diff --git a/RELEASING.md b/RELEASING.md
@@ -6,13 +6,14 @@ Things to do before issuing a new release:
   entries for guidance.
 
 * Build the release locally: mvn clean install -Prelease
+1. Check the manuals have been created properly
+2. Check the javadocs are created correctly (including the diagrams)
 
 * Test the standalone release (this should be done on windows as well as linux):
 1. Unpack the distribution zip or tar.gz
 2. Start and stop the server
-3. Run the examples (follow the instructions under examples/index.html)
-5. Check the manuals have been created properly
-6. Check the javadocs are created correctly (including the diagrams)
+
+*  Run the examples, from the [development branch](https://github.com/apache/activemq-artemis-examples/tree/development).
 
 If everything is successful follow these next steps to build and publish artifacts to Nexus and send out a release vote.
 

diff --git a/docs/user-manual/amqp-broker-connections.adoc b/docs/user-manual/amqp-broker-connections.adoc
@@ -53,7 +53,7 @@ If false it is necessary to call a management operation to start it.
 
 Note that the connection URI options for transport settings such as enabling and configuring TLS are common with other Artemis connector URIs.
 See xref:configuring-transports.adoc#configuring-netty-ssl[the transport doc] for more.
-An example configuration for a TLS AMQP broker-connection can be found in the broker examples at ./examples/features/broker-connection/amqp-sending-overssl.
+An example configuration for a TLS AMQP broker-connection can be found in the broker xref:examples.adoc[examples] at ./examples/features/broker-connection/amqp-sending-overssl.
 
 NOTE: If auto-start is disabled on the broker connection, the start of the broker connection will only happen after the management method `startBrokerConnection(connectionName)` is called on the ServerController.
 

diff --git a/docs/user-manual/amqp.adoc b/docs/user-manual/amqp.adoc
@@ -20,7 +20,7 @@ and many others.
 
 == Examples
 
-We have a few examples as part of the Artemis distribution:
+We have a few examples as part of the xref:examples.adoc[Artemis examples]:
 
 * .NET:
  ** ./examples/protocols/amqp/dotnet

diff --git a/docs/user-manual/configuring-transports.adoc b/docs/user-manual/configuring-transports.adoc
@@ -278,7 +278,7 @@ Default is `true`
 
 Netty SSL is similar to the Netty TCP transport but it provides additional security by encrypting TCP connections using the Secure Sockets Layer SSL
 
-Please see the examples for a full working example of using Netty SSL.
+Please see the xref:examples.adoc[examples] for a full working example of using Netty SSL.
 
 Netty SSL uses all the same properties as Netty TCP but adds the following additional properties:
 

diff --git a/docs/user-manual/diverts.adoc b/docs/user-manual/diverts.adoc
@@ -40,7 +40,7 @@ There can be zero or more diverts in the file.
 
 Diverted messages get xref:copied-message-properties.adoc#properties-for-copied-messages[special properties].
 
-Please see the examples for a full working example showing you how to configure and use diverts.
+Please see the xref:examples.adoc[examples] for a full working example at ./examples/features/standard/divert/ showing you how to configure and use diverts.
 
 Let's take a look at some divert examples:
 

diff --git a/docs/user-manual/examples.adoc b/docs/user-manual/examples.adoc
@@ -4,7 +4,7 @@
 
 The Apache ActiveMQ Artemis Examples repository contains over 90 examples demonstrating many of the client and broker features.
 
-The examples can be found at: [https://github.com/apache/activemq-artemis-examples](https://github.com/apache/activemq-artemis-examples)
+The examples can be found at: https://github.com/apache/activemq-artemis-examples[https://github.com/apache/activemq-artemis-examples^]
 
 The individual examples are available under the `examples` directory, and are grouped within the following sub tree:
 
@@ -22,7 +22,7 @@ The individual examples are available under the `examples` directory, and are gr
 
 == Running the Examples
 
-First, run `mvn package` in the repository root to prepare a broker distribution in the artemis-distribution/target directory for use by the examples.
+First, run `mvn clean package` in the repository root to prepare a broker distribution in the artemis-distribution/target directory for use by the examples.
 
 To run any example, simply `cd` into the appropriate example directory and type `mvn verify` or `mvn install` (For details please read the readme.md in each example directory).
 
@@ -166,7 +166,7 @@ server-out:Server stopped!
 [INFO] ------------------------------------------------------------------------
 ----
 
-This list includes a preview of some examples that exist for Artemis in the [Examples Repository](https://github.com/apache/activemq-artemis-examples), see the repository for more.
+This list includes a preview of some examples that exist for Artemis in the https://github.com/apache/activemq-artemis-examples[Examples Repository^], see the repository for more.
 
 == Application-Layer Failover
 

diff --git a/docs/user-manual/mqtt.adoc b/docs/user-manual/mqtt.adoc
@@ -16,7 +16,7 @@ By default there are `acceptor` elements configured to accept MQTT connections
 
 See the general xref:protocols-interoperability.adoc#protocols-and-interoperability[Protocols and Interoperability] chapter for details on configuring an `acceptor` for MQTT.
 
-Refer to the MQTT examples for a look at some of this functionality in action.
+Refer to the MQTT xref:examples.adoc[examples] for a look at some of this functionality in action.
 
 == MQTT Quality of Service
 
@@ -99,7 +99,7 @@ When brokers are configured for high availability this information will be avail
 
 The client ID used by an MQTT application is very important as it uniquely identifies the application.
 In some situations broker administrators may want to perform extra validation or even modify incoming client IDs to support specific use-cases.
-This is possible by implementing a custom security manager as demonstrated in the `security-manager` example shipped with the broker.
+This is possible by implementing a custom security manager as demonstrated in the `security-manager` xref:examples.adoc[example].
 
 The simplest implementation is a "wrapper" just like the `security-manager` example uses.
 In the `authenticate` method you can modify the client ID using `setClientId()` on the `org.apache.activemq.artemis.spi.core.protocol.RemotingConnection` that is passed in.

diff --git a/docs/user-manual/openwire.adoc b/docs/user-manual/openwire.adoc
@@ -7,7 +7,7 @@ By default there is an `acceptor` configured to accept OpenWire connections on p
 
 See the general xref:protocols-interoperability.adoc#protocols-and-interoperability[Protocols and Interoperability] chapter for details on configuring an `acceptor` for OpenWire.
 
-Refer to the OpenWire examples for a look at this functionality in action.
+Refer to the OpenWire xref:examples.adoc[examples] for a look at this functionality in action.
 
 == Connection Monitoring
 

diff --git a/docs/user-manual/resource-adapter.adoc b/docs/user-manual/resource-adapter.adoc
@@ -44,7 +44,7 @@ Pick the right version of the resource adapter depending on your environment.
 == Building the RA
 
 To use the RA you have to build it.
-The simplest way to do this is with the examples is shipped with the distribution.
+The simplest way to do this is with the xref:examples.adoc[examples].
 
 [,shell]
 ----

diff --git a/docs/user-manual/security.adoc b/docs/user-manual/security.adoc
@@ -1011,7 +1011,7 @@ The secure encoded form of the password must be generated using the main method
 java -cp "<distro-lib-dir>/*" org.apache.activemq.artemis.spi.core.security.jaas.SCRAMPropertiesLoginModule <username> <password> [<iterations>]
 ----
 
-An sample of the output can be found in the amqp examples, examples/protocols/amqp/sasl-scram/src/main/resources/activemq/server0/artemis-users.properties
+An sample of the output can be found in the amqp xref:examples.adoc[examples], examples/protocols/amqp/sasl-scram/src/main/resources/activemq/server0/artemis-users.properties
 
 === Kerberos Authentication
 
@@ -1419,7 +1419,7 @@ By default, the broker uses `org.apache.activemq.artemis.spi.core.security.Activ
 </broker>
 ----
 
-The `security-manager` example demonstrates how to do this is more detail.
+The `security-manager` xref:examples.adoc[example] demonstrates how to do this is more detail.
 
 == Per-Acceptor Security Domains
 

diff --git a/docs/user-manual/stomp.adoc b/docs/user-manual/stomp.adoc
@@ -11,7 +11,7 @@ By default there are `acceptor` elements configured to accept STOMP connections
 
 See the general xref:protocols-interoperability.adoc#protocols-and-interoperability[Protocols and Interoperability] chapter for details on configuring an `acceptor` for STOMP.
 
-Refer to the STOMP examples for a look at some of this functionality in action.
+Refer to the STOMP xref:examples.adoc[examples] for a look at some of this functionality in action.
 
 == Limitations
 
@@ -274,7 +274,7 @@ By default the broker encodes them as binary.
 However, this can be changed by using the `webSocketEncoderType` acceptor URL parameter.
 Valid values are `binary` and `text`.
 
-The `stomp-websockets` example shows how to configure an Apache ActiveMQ Artemis broker to have web browsers and Java applications exchanges messages.
+The `stomp-websockets` xref:examples.adoc[example] shows how to configure an Apache ActiveMQ Artemis broker to have web browsers and Java applications exchanges messages.
 
 == Flow Control
 

diff --git a/docs/user-manual/using-jms.adoc b/docs/user-manual/using-jms.adoc
@@ -249,7 +249,7 @@ System.out.println("Got order: " + receivedMessage.getText());
 ----
 
 It is as simple as that.
-For a wide range of working JMS examples please see the examples directory in the distribution.
+For a wide range of working JMS examples please see the xref:examples.adoc[examples].
 
 ____
 *Warning*

diff --git a/docs/user-manual/using-server.adoc b/docs/user-manual/using-server.adoc
@@ -17,14 +17,7 @@ The following highlights some important folders on the distribution:
 ----
 |___ bin
 |
-|___ examples
-|      |___ common
-|      |___ features
-|      |___ perf
-|      |___ protocols
-|
 |___ lib
-|      |___ client
 |
 |___ schema
 |
@@ -34,10 +27,6 @@ The following highlights some important folders on the distribution:
 bin::
 binaries and scripts needed to run ActiveMQ Artemis.
 
-examples::
-All manner of examples.
-Please refer to the xref:examples.adoc#examples[examples] chapter for details on how to run them.
-
 lib::
 jars and libraries needed to run ActiveMQ Artemis
 
@@ -400,8 +389,6 @@ Assuming you created the broker instance under `/var/lib/mybroker` all you need
 /var/lib/mybroker/bin/artemis run
 ----
 
-Now that the broker is running, you can optionally run some of the included examples to verify the broker is running properly.
-
 To stop the Apache ActiveMQ Artemis instance you will use the same `artemis` script, but with the `stop` argument.
 Example: