<?xml version="1.0" encoding="utf-8"?>
<!--
 
 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.
 
-->

<section>

  <title>
    System Properties
  </title>

  <section role="h2" id="SystemProperties-ExplanationofSystempropertiesusedinQpid">

    <title> Explanation of System properties used in Qpid </title>

    <para>
      This page documents the various System Properties that are
      currently used in the Qpid Java code base.
    </para>

<!-- ######################################################### -->

    <section role="h3" id="SystemProperties-ClientProperties">
      <title> Client Properties </title>

      <variablelist>
	<varlistentry>
	  <term>STRICT_AMQP</term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>Type</term>
		<listitem><para>Boolean</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Default</term>
		<listitem><para>FALSE</para></listitem>
	      </varlistentry>
	    </variablelist>
	    <para> This forces the client to only send AMQP compliant
	    frames. This will disable a number of JMS features.</para>

          <itemizedlist>
	  <title> Features disabled by STRICT_AMQP</title>
            <listitem><para>Queue Browser
            </para></listitem>
            <listitem><para>Message Selectors
            </para></listitem>
            <listitem><para>Durable Subscriptions
            </para></listitem>
            <listitem><para>Session Recover may result in duplicate message delivery
            </para></listitem>
            <listitem><para>Destination validation, so no InvalidDestinationException
            will be thrown
            </para></listitem>
          </itemizedlist>
	  <para>
            This is associated with property <xref linkend="SystemProperties-STRICTAMQPFATAL"/>
          </para>
	  </listitem>
	</varlistentry>



	<varlistentry id="SystemProperties-STRICTAMQPFATAL">
	  <term>STRICT_AMQP_FATAL</term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>Type</term>
		<listitem><para>Boolean</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Default</term>
		<listitem><para>FALSE</para></listitem>
	      </varlistentry>
	    </variablelist>
	    <para>
	      This will cause any attempt to utilise an enhanced feature to
	      throw and UnsupportedOperationException. When set to false then
	      the exception will not occur but the feature will be disabled.
	    </para>
	    <para>
	      e.g.
	      The Queue Browser will always show no messages.
	      Any message selector will be removed.
	    </para>
	  </listitem>
	</varlistentry>


	<varlistentry>
	  <term>IMMEDIATE_PREFETCH</term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>Type</term>
		<listitem><para>Boolean</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Default</term>
		<listitem><para>FALSE</para></listitem>
	      </varlistentry>
	    </variablelist>
	    <para>
	      The default with AMQP is to start prefetching messages. However,
	      with certain 3rd party Java tools, such as Mule this can cause a
	      problem. Mule will create a consumer but never consume from it so
	      any any prefetched messages will be stuck until that session is
	      closed. This property is used to re-instate the default AMQP
	      behaviour. The default Qpid behaviour is to prevent prefetch
	      occurring, by starting the connection Flow Controlled, until a
	      request for a message is made on the consumer either via a
            receive() or setting a message listener.</para>
	  </listitem>
	</varlistentry>          
          


	<varlistentry>
	  <term>qpid.sync_op_timeout</term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>Type</term>
		<listitem><para>long</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Default</term>
		<listitem><para>60000</para></listitem>
	      </varlistentry>
	    </variablelist>
	    <para>The length of time (in milliseconds) to wait for a synchronous operation to complete.
                  For compatibility with older	clients, the synonym amqj.default_syncwrite_timeout is supported.</para>
	  </listitem>
	</varlistentry>       

	<varlistentry>
	  <term>amq.dynamicsaslregistrar.properties</term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>Type</term>
		<listitem><para>String</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Default</term>
		<listitem><para>org/apache/qpid/client/security/DynamicSaslRegistrar.properties</para></listitem>
	      </varlistentry>
	    </variablelist>
	    <para>The name of the SASL configuration properties file.
	    </para>
	  </listitem>
	</varlistentry>          
             
	<varlistentry>
	  <term>amqj.heartbeat.timeoutFactor</term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>Type</term>
		<listitem><para>float</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Default</term>
		<listitem><para>2.0</para></listitem>
	      </varlistentry>
	    </variablelist>
	    <para>
            The factor used to get the timeout from the delay between
            heartbeats
            </para>
	  </listitem>
	</varlistentry>         


	<varlistentry>
	  <term>amqj.tcp_nodelay</term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>Type</term>
		<listitem><para>Boolean</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Default</term>
		<listitem><para>TRUE</para></listitem>
	      </varlistentry>
	    </variablelist>
	    <para> Disable Nagle's algorithm on the TCP connection.
	    </para>
	  </listitem>
	</varlistentry>       

	<varlistentry>
	  <term>amqj.protocol.logging.level</term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>Type</term>
		<listitem><para>Boolean</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Default</term>
		<listitem><para>null</para></listitem>
	      </varlistentry>
	    </variablelist>
	    <para>If set this will turn on protocol logging on the
	    client. </para>
	  </listitem>
	</varlistentry>          
                       
	<varlistentry>
	  <term>jboss.host</term>
	  <listitem>
	    <para>
            Used by the JBossConnectionFactoryInitialiser to specify the host
            to connect to perform JNDI lookups.
            </para>
	  </listitem>
	</varlistentry>       

	<varlistentry>
	  <term>jboss.port</term>
	  <listitem>
	    <para>
            Used by the JBossConnectionFactoryInitialiser to specify the port
            to connect to perform JNDI lookups.
            </para>
	  </listitem>
	</varlistentry>          
             
	<varlistentry>
	  <term>amqj.MaximumStateWait</term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>Default</term>
		<listitem><para>30000</para></listitem>
	      </varlistentry>
	    </variablelist>
	    <para>
	      Used to set the maximum time the State Manager should wait before
	      timing out a frame wait.
            </para>
	  </listitem>
	</varlistentry>          
      </variablelist>
    </section>          
<!-- ######################################################### -->

    <section role="h3" id="SystemProperties-ManagementProperties">

      <title>
	Management Properties
      </title>

      <variablelist>
	<varlistentry>
	  <term>security</term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>Default</term>
		<listitem><para>null</para></listitem>
	      </varlistentry>
	    </variablelist>
	    <para>
	      String representing the Security level to be used to on
	      the connection to the broker. The null default results
	      in no security or PLAIN. When used with jmxconnector
	      'javax.management.remote.jmxmp.JMXMPConnector' a
	      security value of 'CRAM-MD5' will result in all
	      communication to the broker being encrypted.
            </para>
	  </listitem>
	</varlistentry>          
          
	<varlistentry>
	  <term>jmxconnector</term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>Default</term>
		<listitem><para>null</para></listitem>
	      </varlistentry>
	    </variablelist>
	    <para>
	      String representing the JMXConnector class used to
	      perform the connection to the broker. The null default
	      results in the standard JMX connector. Utilising
	      'javax.management.remote.jmxmp.JMXMPConnector' and
	      security 'CRAM-MD5' will result in all communication to
	      the broker being encrypted.
            </para>
	  </listitem>
	</varlistentry>          
          
	<varlistentry>
	  <term>timeout</term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>Default</term>
		<listitem><para>5000</para></listitem>
	      </varlistentry>
	    </variablelist>
	    <para>            
	      Long value representing the milli seconds before
	      connection to the broker should timeout.
            </para>
	  </listitem>
	</varlistentry>          
          
      </variablelist>

    </section>


<!-- ######################################################### -->
            

    <section role="h3" id="SystemProperties-PropertiesusedinExamples">

      <title> Properties used in Examples </title>

      <variablelist>
	<varlistentry>
	  <term>archivepath</term>
	  <listitem>
	    <para> 
	      Used in <filename>FileMessageDispatcher</filename>. This
	      properties specifies the directory to move payload
	      file(s) to archive location as no error</para>
	  </listitem>
	</varlistentry>
      </variablelist>
</section>
</section>
</section>
