https://issues.apache.org/activemq/browse/AMQ-1894 - tidying up configurations and inserting comments

git-svn-id: https://svn.apache.org/repos/asf/activemq/trunk@812481 13f79535-47bb-0310-9956-ffa450edef68

assembly/src/release/conf/activemq-camel.xml

@@ -14,15 +14,20 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 -->
+<!-- 
+
+    Lets deploy some Enterprise Integration Patterns inside the ActiveMQ Message Broker
+    For more information, see:
+    
+    http://camel.apache.org
+    
+    Include this file in your configuration to enable Camel
+    
+    e.g. <import resource="activemq-camel.xml"/>
+-->
 <beans
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">
-    <!--
-       Lets deploy some Enterprise Integration Patterns inside the ActiveMQ Message Broker
-       For more details see
-      
-       http://activemq.apache.org/enterprise-integration-patterns.html
-    -->
     <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
 
         <!-- You can use a <package> element for each root package to search for Java routes -->
@@ -38,7 +43,7 @@
     <!--
        Lets configure some Camel endpoints
     
-       http://activemq.apache.org/camel/components.html
+       http://camel.apache.org/components.html
     -->
 
     <!-- configure the camel activemq component to use the current broker -->

assembly/src/release/conf/activemq-jetty.xml

@@ -14,10 +14,13 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 -->
+<!-- 
+    An embedded servlet engine for serving up the Admin consoles, REST and Ajax APIs and some demos 
+    Include this file in your configuration to enable ActiveMQ web components
+    
+    e.g. <import resource="activemq-jetty.xml"/>
+-->
 <beans>
-    <!-- 
-        An embedded servlet engine for serving up the Admin consoles, REST and Ajax APIs and some demos 
-    -->
     <jetty xmlns="http://mortbay.com/schemas/jetty/1.0">
         <connectors>
             <nioConnector port="8161"/>

assembly/src/release/conf/activemq.xml

@@ -22,16 +22,17 @@
   http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core.xsd">
 
     <!-- Allows us to use system properties as variables in this configuration file -->
-    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>
+    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
+        <property name="locations">
+            <value>file:${activemq.base}/conf/credentials.properties</value>
+        </property>      
+    </bean>
 
     <!-- 
         The <broker> element is used to configure the ActiveMQ broker. 
-        
-        Tips: 
-          - Change the brokerName attribute to something unique  
     -->
     <broker xmlns="http://activemq.apache.org/schema/core" brokerName="localhost" dataDirectory="${activemq.base}/data">
-
+        
         <!-- 
             The managementContext is used to configure how ActiveMQ is exposed in 
             JMX. By default, ActiveMQ uses the MBean server that is started by 
@@ -51,15 +52,28 @@
             http://activemq.apache.org/persistence.html 
         -->
         <persistenceAdapter>
-            <kahaDB directory="${activemq.base}/data/kahadb" indexWriteBatchSize="1000" enableIndexWriteAsync="true" enableJournalDiskSyncs="false" />
+            <kahaDB directory="${activemq.base}/data/kahadb"/>
         </persistenceAdapter>
         
-        <!--  
+        
+        <!--
+            It's advisable to turn on producer flow control in the production system
+
             The systemUsage controls the maximum amount of space the broker will 
-            use before slowing down producers. For more information, see: 
+            use before slowing down producers. For more information, see:
             
-            http://activemq.apache.org/producer-flow-control.html 
+            http://activemq.apache.org/producer-flow-control.html
-        -->
+              
+        <destinationPolicy>
+            <policyMap>
+                <policyEntries>
+                    <policyEntry queue=">" producerFlowControl="true" />
+                    <policyEntry topic=">" producerFlowControl="true" />
+                </policyEntries>
+            </policyMap>
+        </destinationPolicy> 
+ 
+        
         <systemUsage>
             <systemUsage>
                 <memoryUsage>
@@ -73,7 +87,7 @@
                 </tempUsage>
             </systemUsage>
         </systemUsage>
-
+        -->
 
         <!-- 
             The transport connectors expose ActiveMQ over a given protocol to
@@ -96,7 +110,8 @@
 
     <!-- 
         Enable web consoles, REST and Ajax APIs and demos
-        Take a look at activemq-jetty.xml for more details
+        Take a look at activemq-jetty.xml for more details 
-    <import resource="activemq-jetty.xml"/>
     -->
+    <import resource="activemq-jetty.xml"/>
+    
 </beans>

assembly/src/sample-conf/activemq-command.xml

@@ -14,6 +14,17 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 -->
+<!--  
+    Communicate with a broker using command agent over XMPP 
+    For more information, see:
+    
+    http://activemq.apache.org/command-agent.html and
+    http://activemq.apache.org/xmpp.html
+    
+    To run ActiveMQ with this configuration add xbean:conf/activemq-command.xml to your command
+    
+    e.g. $ bin/activemq xbean:conf/activemq-command.xml
+ -->
 <beans>
     <broker xmlns="http://activemq.apache.org/schema/core" brokerName="command-broker" dataDirectory="${activemq.base}/data">
         <managementContext>
@@ -25,6 +36,7 @@
             <transportConnector name="xmpp" uri="xmpp://localhost:61222"/>
         </transportConnectors>
     </broker>
+    
     <!-- Create a command agent -->
     <commandAgent xmlns="http://activemq.apache.org/schema/core" brokerUrl="vm://localhost"/>
 </beans>

assembly/src/sample-conf/activemq-demo.xml

@@ -14,6 +14,13 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 -->
+<!--  
+    Demonstrates various ActiveMQ configuration options
+    
+    To run ActiveMQ with this configuration add xbean:conf/activemq-demo.xml to your command
+    
+    e.g. $ bin/activemq xbean:conf/activemq-demo.xml
+ -->
 <beans
   xmlns="http://www.springframework.org/schema/beans"
   xmlns:amq="http://activemq.apache.org/schema/core"

assembly/src/sample-conf/activemq-dynamic-network-broker1.xml

@@ -14,6 +14,22 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 -->
+<!--  
+    Create a dynamic network of brokers
+    For more information, see:
+    
+    http://activemq.apache.org/networks-of-brokers.html
+    
+    To run this example network of ActiveMQ brokers run
+    
+    $ bin/activemq xbean:conf/activemq-dynamic-network-broker1.xml
+    
+    and
+    
+    $ bin/activemq xbean:conf/activemq-dynamic-network-broker2.xml
+    
+    in separate consoles
+ -->
 <beans
   xmlns="http://www.springframework.org/schema/beans"
   xmlns:amq="http://activemq.apache.org/schema/core"
@@ -25,6 +41,32 @@
 
     <broker xmlns="http://activemq.apache.org/schema/core" brokerName="dynamic-broker1" dataDirectory="${activemq.base}/data">
 
+        <!-- First let's configure connectors -->
+
+        <!--
+            Configure network connector to use multicast protocol
+            For more information, see
+            
+            http://activemq.apache.org/multicast-transport-reference.html
+        -->
+	    <networkConnectors>
+	      <networkConnector uri="multicast://default"
+	        dynamicOnly="true" 
+	        networkTTL="3" 
+	        prefetchSize="1" 
+	        decreaseNetworkConsumerPriority="true" />
+	    </networkConnectors>
+	    
+	    <!-- 
+            The transport connectors ActiveMQ will listen to
+            Configure discovery URI to use multicast protocol
+        -->
+        <transportConnectors>
+            <transportConnector name="openwire" uri="tcp://0.0.0.0:61616" discoveryUri="multicast://default" />
+        </transportConnectors>
+        
+        <!-- Now configure the rest of the desired broker behavior -->
+
         <!-- Destination specific policies using destination names or wildcards -->
         <destinationPolicy>
             <policyMap>
@@ -45,19 +87,11 @@
             <managementContext createConnector="true"/>
         </managementContext>
 
-	    <networkConnectors>
-	      <networkConnector uri="multicast://default"
-	        dynamicOnly="true" 
-	        networkTTL="3" 
-	        prefetchSize="1" 
-	        decreaseNetworkConsumerPriority="true" />
-	    </networkConnectors>
-
         <persistenceAdapter>
-            <kahaDB directory="${activemq.base}/data/dynamic-broker1/kahadb" indexWriteBatchSize="1000" enableIndexWriteAsync="true" enableJournalDiskSyncs="false" />
+            <kahaDB directory="${activemq.base}/data/dynamic-broker1/kahadb"/>
         </persistenceAdapter>
         
-        <!--  The maximum about of space the broker will use before slowing down producers -->
+        <!--  The maximum amount of space the broker will use before slowing down producers -->
         <systemUsage>
             <systemUsage>
                 <memoryUsage>
@@ -72,12 +106,6 @@
             </systemUsage>
         </systemUsage>
 
-
-        <!-- The transport connectors ActiveMQ will listen to -->
-        <transportConnectors>
-            <transportConnector name="openwire" uri="tcp://0.0.0.0:61616" discoveryUri="multicast://default" />
-        </transportConnectors>
-
     </broker>
 
 </beans>

assembly/src/sample-conf/activemq-dynamic-network-broker2.xml

@@ -14,6 +14,22 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 -->
+<!--  
+    Create a dynamic network of brokers
+    For more information, see:
+    
+    http://activemq.apache.org/networks-of-brokers.html
+    
+    To run this example network of ActiveMQ brokers run
+    
+    $ bin/activemq xbean:conf/activemq-dynamic-network-broker1.xml
+    
+    and
+    
+    $ bin/activemq xbean:conf/activemq-dynamic-network-broker2.xml
+    
+    in separate consoles
+ -->
 <beans
   xmlns="http://www.springframework.org/schema/beans"
   xmlns:amq="http://activemq.apache.org/schema/core"
@@ -26,6 +42,32 @@
 
     <broker xmlns="http://activemq.apache.org/schema/core" brokerName="dynamic-broker2" dataDirectory="${activemq.base}/data">
 
+        <!-- First let's configure connectors -->
+
+        <!--
+            Configure network connector to use multicast protocol
+            For more information, see
+            
+            http://activemq.apache.org/multicast-transport-reference.html
+        -->
+        <networkConnectors>
+          <networkConnector uri="multicast://default"
+            dynamicOnly="true" 
+            networkTTL="3" 
+            prefetchSize="1" 
+            decreaseNetworkConsumerPriority="true" />
+        </networkConnectors>
+        
+        <!-- 
+            The transport connectors ActiveMQ will listen to
+            Configure discovery URI to use multicast protocol
+        -->
+        <transportConnectors>
+            <transportConnector name="openwire" uri="tcp://0.0.0.0:61618" discoveryUri="multicast://default" />
+        </transportConnectors>
+
+        <!-- Now configure the rest of the desired broker behavior -->
+
         <!-- Destination specific policies using destination names or wildcards -->
         <destinationPolicy>
             <policyMap>
@@ -45,20 +87,12 @@
         <managementContext>
             <managementContext createConnector="true" connectorPort="1100"/>
         </managementContext>
-
-	    <networkConnectors>
-	      <networkConnector uri="multicast://default"
-	        dynamicOnly="true" 
-	        networkTTL="3" 
-	        prefetchSize="1" 
-	        decreaseNetworkConsumerPriority="true" />
-	    </networkConnectors>
 	
 	    <persistenceAdapter>
-	        <kahaDB directory="${activemq.base}/data/dynamic-broker2/kahadb" indexWriteBatchSize="1000" enableIndexWriteAsync="true" enableJournalDiskSyncs="false" />
+	        <kahaDB directory="${activemq.base}/data/dynamic-broker2/kahadb" />
 	    </persistenceAdapter>
 	    
-	    <!--  The maximum about of space the broker will use before slowing down producers -->
+	    <!--  The maximum amount of space the broker will use before slowing down producers -->
 	    <systemUsage>
 	        <systemUsage>
 	            <memoryUsage>
@@ -72,12 +106,6 @@
 	            </tempUsage>
 	        </systemUsage>
 	    </systemUsage>
-	
-	
-	    <!-- The transport connectors ActiveMQ will listen to -->
-	    <transportConnectors>
-	        <transportConnector name="openwire" uri="tcp://0.0.0.0:61618" discoveryUri="multicast://default" />
-	    </transportConnectors>
 
     </broker>
 

assembly/src/sample-conf/activemq-jdbc.xml

@@ -14,13 +14,23 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 -->
+<!--  
+    Use JDBC for message persistence
+    For more information, see:
+    
+    http://activemq.apache.org/persistence.html
+    
+    To run ActiveMQ with this configuration add xbean:conf/activemq-jdbc.xml to your command
+    
+    e.g. $ bin/activemq xbean:conf/activemq-jdbc.xml
+ -->
 <beans>
   
   <broker useJmx="false" brokerName="jdbcBroker" xmlns="http://activemq.apache.org/schema/core">
     <persistenceAdapter>
-       <jdbcPersistenceAdapter dataSource="#derby-ds"/>
+       <journaledJDBC dataDirectory="${activemq.base}/data" dataSource="#derby-ds"/>
     </persistenceAdapter>
-  
+
     <transportConnectors>
        <transportConnector name="default" uri="tcp://0.0.0.0:61616"/>
     </transportConnectors>

assembly/src/sample-conf/activemq-security.xml

@@ -15,6 +15,16 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
+<!--  
+    Secure ActiveMQ broker
+    For more information, see:
+    
+    http://activemq.apache.org/security.html
+    
+    To run ActiveMQ with this configuration add xbean:conf/activemq-security.xml to your command
+    
+    e.g. $ bin/activemq xbean:conf/activemq-security.xml
+ -->
 <beans
   xmlns="http://www.springframework.org/schema/beans"
   xmlns:amq="http://activemq.apache.org/schema/core"
@@ -31,6 +41,7 @@
   <broker useJmx="true" persistent="false" xmlns="http://activemq.apache.org/schema/core">
 
     <plugins>
+        <!-- Configure authentication; Username, passwords and groups -->
         <simpleAuthenticationPlugin>
             <users>
                 <authenticationUser username="system" password="manager"
@@ -42,7 +53,7 @@
         </simpleAuthenticationPlugin>
 
 
-      <!--  lets configure a destination based authorization mechanism -->
+      <!--  Lets configure a destination based authorization mechanism -->
       <authorizationPlugin>
         <map>
           <authorizationMap>
@@ -70,8 +81,14 @@
     
   </broker>
 
+  <!-- 
+      Configure command agent to be used in secured broker environment
+      Notice how we used ${activemq.username} and ${activemq.password} configured in credential.properties
+  -->
   <commandAgent xmlns="http://activemq.apache.org/schema/core" brokerUrl="vm://localhost" username="${activemq.username}" password="${activemq.password}"/>
 
+  <!-- Use Web applications and Camel in secured broker environment -->
   <import resource="activemq-jetty.xml"/>
+  <import resource="activemq-camel.xml"/>
 
 </beans>

assembly/src/sample-conf/activemq-static-network-broker1.xml

@@ -14,6 +14,22 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 -->
+<!--  
+    Create a static network of brokers
+    For more information, see:
+    
+    http://activemq.apache.org/networks-of-brokers.html
+    
+    To run this example network of ActiveMQ brokers run
+    
+    $ bin/activemq xbean:conf/activemq-static-network-broker1.xml
+    
+    and
+    
+    $ bin/activemq xbean:conf/activemq-static-network-broker2.xml
+    
+    in separate consoles
+ -->
 <beans
   xmlns="http://www.springframework.org/schema/beans"
   xmlns:amq="http://activemq.apache.org/schema/core"
@@ -27,6 +43,23 @@
 
     <broker xmlns="http://activemq.apache.org/schema/core" brokerName="static-broker1" dataDirectory="${activemq.base}/data">
 
+        <!-- First let's configure connectors -->
+
+        <!-- 
+            The store and forward broker networks ActiveMQ will listen to.
+            We'll leave it empty as duplex network will be configured by another broker
+            Take a look at activemq-static_network-broker2.xml for example
+        -->
+        <networkConnectors>
+        </networkConnectors>
+        
+        <!-- The transport connectors ActiveMQ will listen to -->
+        <transportConnectors>
+            <transportConnector name="openwire" uri="tcp://0.0.0.0:61616"/>
+        </transportConnectors>
+        
+        <!-- Now configure the rest of the desired broker behavior -->
+
         <!-- Destination specific policies using destination names or wildcards -->
         <destinationPolicy>
             <policyMap>
@@ -47,15 +80,11 @@
             <managementContext createConnector="true"/>
         </managementContext>
 
-        <!-- The store and forward broker networks ActiveMQ will listen to -->
-        <networkConnectors>
-        </networkConnectors>
-
         <persistenceAdapter>
-            <kahaDB directory="${activemq.base}/data/static-broker1/kahadb" indexWriteBatchSize="1000" enableIndexWriteAsync="true" enableJournalDiskSyncs="false" />
+            <kahaDB directory="${activemq.base}/data/static-broker1/kahadb" />
         </persistenceAdapter>
         
-        <!--  The maximum about of space the broker will use before slowing down producers -->
+        <!--  The maximum amount of space the broker will use before slowing down producers -->
         <systemUsage>
             <systemUsage>
                 <memoryUsage>
@@ -70,12 +99,6 @@
             </systemUsage>
         </systemUsage>
 
-
-        <!-- The transport connectors ActiveMQ will listen to -->
-        <transportConnectors>
-            <transportConnector name="openwire" uri="tcp://0.0.0.0:61616"/>
-        </transportConnectors>
-
     </broker>
 
 </beans>

assembly/src/sample-conf/activemq-static-network-broker2.xml

@@ -14,6 +14,22 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 -->
+<!--  
+    Create a static network of brokers
+    For more information, see:
+    
+    http://activemq.apache.org/networks-of-brokers.html
+    
+    To run this example network of ActiveMQ brokers run
+    
+    $ bin/activemq xbean:conf/activemq-static-network-broker1.xml
+    
+    and
+    
+    $ bin/activemq xbean:conf/activemq-static-network-broker2.xml
+    
+    in separate consoles
+ -->
 <beans
   xmlns="http://www.springframework.org/schema/beans"
   xmlns:amq="http://activemq.apache.org/schema/core"
@@ -27,6 +43,23 @@
 
     <broker xmlns="http://activemq.apache.org/schema/core" brokerName="static-broker1" dataDirectory="${activemq.base}/data">
 
+        <!-- First let's configure connectors -->
+        
+        <!-- 
+            The store and forward broker networks ActiveMQ will listen to
+            Create a duplex connector to the first broker 
+        -->
+        <networkConnectors>
+            <networkConnector uri="static:(tcp://localhost:61616)" duplex="true"/>
+        </networkConnectors>
+        
+        <!-- The transport connectors ActiveMQ will listen to -->
+        <transportConnectors>
+            <transportConnector name="openwire" uri="tcp://0.0.0.0:61618"/>
+        </transportConnectors>
+        
+        <!-- Now configure the rest of the desired broker behavior -->
+
         <!-- Destination specific policies using destination names or wildcards -->
         <destinationPolicy>
             <policyMap>
@@ -47,16 +80,11 @@
             <managementContext createConnector="true" connectorPort="1100"/>
         </managementContext>
 
-        <!-- The store and forward broker networks ActiveMQ will listen to -->
-        <networkConnectors>
-            <networkConnector uri="static:(tcp://localhost:61616)" duplex="true" prefetchSize="1"/>
-        </networkConnectors>
-
         <persistenceAdapter>
-            <kahaDB directory="${activemq.base}/data/static-broker2/kahadb" indexWriteBatchSize="1000" enableIndexWriteAsync="true" enableJournalDiskSyncs="false" />
+            <kahaDB directory="${activemq.base}/data/static-broker2/kahadb" />
         </persistenceAdapter>
         
-        <!--  The maximum about of space the broker will use before slowing down producers -->
+        <!--  The maximum amount of space the broker will use before slowing down producers -->
         <systemUsage>
             <systemUsage>
                 <memoryUsage>
@@ -71,12 +99,6 @@
             </systemUsage>
         </systemUsage>
 
-
-        <!-- The transport connectors ActiveMQ will listen to -->
-        <transportConnectors>
-            <transportConnector name="openwire" uri="tcp://0.0.0.0:61618"/>
-        </transportConnectors>
-
     </broker>
 
 </beans>