Merged out from trunkQPID-2519

git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/QPID-2519@1187375 13f79535-47bb-0310-9956-ffa450edef68

7 files changed, 313 insertions, 6 deletions

diff --git a/cpp/docs/api/developer.doxygen.in b/cpp/docs/api/developer.doxygen.in
index fd3a9ac621..1e1fddab80 100644
--- a/cpp/docs/api/developer.doxygen.in
+++ b/cpp/docs/api/developer.doxygen.in
@@ -1029,7 +1029,7 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator 
 # instead of the = operator.
 
-PREDEFINED             = QPID_CLIENT_EXTERN= QPID_COMMON_EXTERN= QPID_CONSOLE_EXTERN= QPID_BROKER_EXTERN= QPID_MESSAGING_EXTERN= QMF_EXTERN=
+PREDEFINED             = QPID_CLIENT_EXTERN= QPID_COMMON_EXTERN= QPID_CONSOLE_EXTERN= QPID_BROKER_EXTERN= QPID_MESSAGING_EXTERN= QMF_EXTERN= QMFE_EXTERN=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
 # this tag can be used to specify a list of macro names that should be expanded. 
diff --git a/cpp/docs/api/doxygen_mainpage.h b/cpp/docs/api/doxygen_mainpage.h
index cb36d7edb0..9acae52da4 100644
--- a/cpp/docs/api/doxygen_mainpage.h
+++ b/cpp/docs/api/doxygen_mainpage.h
@@ -266,7 +266,46 @@
  * else 
  *    session.rollback();
  * </pre>
- * 
+ *
+ * <h3>Exceptions</h3>
+ *
+ * All exceptions for the messaging API have MessagingException as
+ * their base class.
+
+ * A common class of exception are those related to processing
+ * addresses used to create senders and/or receivers. These all have
+ * AddressError as their base class.
+ *
+ * Where there is a syntax error in the address itself, a
+ * MalformedAddress will be thrown. Where the address is valid, but
+ * there is an error in interpreting (i.e. resolving) it, a
+ * ResolutionError - or a sub-class of it - will be thrown. If the
+ * address has assertions enabled for a given context and the asserted
+ * node properties are not in fact correct then AssertionFailed will
+ * be thrown. If the node is not found, NotFound will be thrown.
+ *
+ * The loss of the underlying connection (e.g. the TCP connection)
+ * results in TransportFailure being thrown. If automatic reconnect is
+ * enabled, this will be caught be the library which will then try to
+ * reconnect. If reconnection - as configured by the connection
+ * options - fails, then TransportFailure will be thrown. This can
+ * occur on any call to the messaging API.
+ *
+ * Sending a message may also result in an exception
+ * (e.g. TargetCapacityExceeded if a queue to which the message is
+ * delivered cannot enqueue it due to lack of capacity). For
+ * asynchronous send the exception may not be thrown on the send
+ * invocation that actually triggers it, but on a subsequent method
+ * call on the API.
+ *
+ * Certain exceptions may render the session invalid; once these
+ * occur, subsequent calls on the session will throw the same class of
+ * exception. This is not an intrinsic property of the class of
+ * exception, but is a result of the current mapping of the API to the
+ * underlying AMQP 0-10 protocol. You can test whether the session is
+ * valid at any time using the hasError() and/or checkError() methods
+ * on Session.
+ *
  * <h3>Logging</h3>
  * 
  * The Qpidd broker and C++ clients can both use environment variables to
diff --git a/cpp/docs/api/footer.html b/cpp/docs/api/footer.html
index 883410ce25..5a31e81821 100644
--- a/cpp/docs/api/footer.html
+++ b/cpp/docs/api/footer.html
@@ -25,7 +25,7 @@ Qpid C++ API Reference</small></address>
 
 <address style="text-align: right;">
 <small>
-Generated on $datetime for $projectname by&nbsp;<a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> $doxygenversion</small>
+Generated on $date for $projectname by&nbsp;<a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> $doxygenversion</small>
 </address>
 </body>
 </html>
diff --git a/cpp/docs/api/user.doxygen.in b/cpp/docs/api/user.doxygen.in
index 2728df47e4..ec0fd1361c 100644
--- a/cpp/docs/api/user.doxygen.in
+++ b/cpp/docs/api/user.doxygen.in
@@ -1021,7 +1021,7 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator 
 # instead of the = operator.
 
-PREDEFINED             = QPID_CLIENT_EXTERN= QPID_COMMON_EXTERN= QPID_CONSOLE_EXTERN= QPID_BROKER_EXTERN= QPID_MESSAGING_EXTERN= QMF_EXTERN=
+PREDEFINED             = QPID_CLIENT_EXTERN= QPID_COMMON_EXTERN= QPID_CONSOLE_EXTERN= QPID_BROKER_EXTERN= QPID_MESSAGING_EXTERN= QMF_EXTERN= QMFE_EXTERN=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
 # this tag can be used to specify a list of macro names that should be expanded. 
diff --git a/cpp/docs/man/Makefile.am b/cpp/docs/man/Makefile.am
index 14295f73bf..b821568f81 100644
--- a/cpp/docs/man/Makefile.am
+++ b/cpp/docs/man/Makefile.am
@@ -16,10 +16,29 @@
 # specific language governing permissions and limitations
 # under the License.
 #
+
+# Generate makefile from qpidd --help
+#
+# Note: qiddd.1 is normally a _checked in_ pre-generated file, so that
+# make dist does not have to build the entire source just for the man page.
+#
+# To update the checked-in file (e.g. for a new release) do the following:
+#
+# - start with a completely clean checkout.
+# - make sure there are no modules installed in your configured prefix,
+#   we don't want to pick up configuration from optional modules
+# - do bootstrap; configure
+# - in build-dir: cd src; make # build the broker
+# - in source-dir: cd docs/man; rm qpidd.1 # remove checked-in man page.
+# - in build-dir: cd docs/man; make # make new man page
+# - edit qpidd.1 to remove all default values referring to file/directory locations.
+#   these values will differ between builds depending on configuration.
+# - if source-dir != build-dir: copy qpidd.1 from build-dir/docs/man to source-dir/docs/man
+
 dist_man_MANS = qpidd.1
 
-man_aux = $(dist_man_MANS:.1=.x) 
-EXTRA_DIST = $(man_aux) generate_manpage groffify_options.sed groffify_template.sed 
+man_aux = $(dist_man_MANS:.1=.x)
+EXTRA_DIST = $(man_aux) generate_manpage groffify_options.sed groffify_template.sed
 DISTCLEANFILES = $(dist_man_MANS)
 CLEANFILES=qpidd.1
 
diff --git a/cpp/docs/man/qpidd.1 b/cpp/docs/man/qpidd.1
new file mode 100644
index 0000000000..d2cff454cf
--- /dev/null
+++ b/cpp/docs/man/qpidd.1
@@ -0,0 +1,247 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.38.2.
+.TH QPIDD "1" "March 2011" "qpidd (qpidc) version 0.11" "User Commands"
+.SH NAME
+
+qpidd \- the Qpid AMQP Message Broker Daemon
+.SH SYNOPSIS
+
+qpidd [-p port] [--config config_file] [--data-dir directory]
+.SH DESCRIPTION
+
+An AMQP message broker daemon that stores, routes and forwards
+messages using the Advanced Message Queueing Protocol (AMQP).
+.SH OPTIONS
+
+The options below are built-in to qpidd. Installing add-on modules provides additional options. To see the full set of options available type "qpidd --help"
+
+Options may be specified via command line, environment variable or configuration file. See FILES and ENVIRONMENT below for details.
+.PP
+
+.TP
+\fB\-h\fR [ \fB\-\-help\fR ]
+Displays the help message
+.TP
+\fB\-v\fR [ \fB\-\-version\fR ]
+Displays version information
+.TP
+\fB\-\-config\fR FILE
+Reads configuration from FILE
+.SS "Module options:"
+.TP
+\fB\-\-module\-dir\fR DIR
+Load all shareable modules in this
+directory
+.TP
+\fB\-\-load\-module\fR FILE
+Specifies additional module(s) to be
+loaded
+.TP
+\fB\-\-no\-module\-dir\fR
+Don't load modules from module
+directory
+.SS "Broker Options:"
+.TP
+\fB\-\-data\-dir\fR DIR
+Directory to contain persistent data
+generated by the broker
+.TP
+\fB\-\-no\-data\-dir\fR
+Don't use a data directory.  No
+persistent configuration will be loaded
+or stored
+.TP
+\fB\-p\fR [ \fB\-\-port\fR ] PORT (5672)
+Tells the broker to listen on PORT
+.TP
+\fB\-\-worker\-threads\fR N (3)
+Sets the broker thread pool size
+.TP
+\fB\-\-max\-connections\fR N (500)
+Sets the maximum allowed connections
+.TP
+\fB\-\-connection\-backlog\fR N (10)
+Sets the connection backlog limit for
+the server socket
+.TP
+\fB\-m\fR [ \fB\-\-mgmt\-enable\fR ] yes|no (1)
+Enable Management
+.TP
+\fB\-\-mgmt\-qmf2\fR yes|no (1)
+Enable broadcast of management
+information over QMF v2
+.TP
+\fB\-\-mgmt\-qmf1\fR yes|no (1)
+Enable broadcast of management
+information over QMF v1
+.TP
+\fB\-\-mgmt\-pub\-interval\fR SECONDS (10)
+Management Publish Interval
+.TP
+\fB\-\-queue\-purge\-interval\fR SECONDS (600)
+Interval between attempts to purge any
+expired messages from queues
+.TP
+\fB\-\-auth\fR yes|no (1)
+Enable authentication, if disabled all
+incoming connections will be trusted
+.TP
+\fB\-\-realm\fR REALM (QPID)
+Use the given realm when performing
+authentication
+.TP
+\fB\-\-default\-queue\-limit\fR BYTES (104857600)
+Default maximum size for queues (in
+bytes)
+.TP
+\fB\-\-tcp\-nodelay\fR
+Set TCP_NODELAY on TCP connections
+.TP
+\fB\-\-require\-encryption\fR
+Only accept connections that are
+encrypted
+.TP
+\fB\-\-known\-hosts\-url\fR URL or 'none'
+URL to send as 'known\-hosts' to clients
+('none' implies empty list)
+.TP
+\fB\-\-sasl\-config\fR DIR
+gets sasl config info from nonstandard
+location
+.TP
+\fB\-\-max\-session\-rate\fR MESSAGES/S (0)
+Sets the maximum message rate per
+session (0=unlimited)
+.TP
+\fB\-\-async\-queue\-events\fR yes|no (0)
+Set Queue Events async, used for
+services like replication
+.TP
+\fB\-\-default\-flow\-stop\-threshold\fR PERCENT (80)
+Percent of queue's maximum capacity at
+which flow control is activated.
+.TP
+\fB\-\-default\-flow\-resume\-threshold\fR PERCENT (70)
+Percent of queue's maximum capacity at
+which flow control is de\-activated.
+.TP
+\fB\-\-default\-event\-threshold\-ratio\fR %age of limit (80)
+The ratio of any specified queue limit
+at which an event will be raised
+.SS "Logging options:"
+.TP
+\fB\-t\fR [ \fB\-\-trace\fR ]
+Enables all logging
+.TP
+\fB\-\-log\-enable\fR RULE (notice+)
+Enables logging for selected levels and
+components. RULE is in the form
+\&'LEVEL[+][:PATTERN]' Levels are one of:
+.IP
+trace debug info notice warning error
+.IP
+critical
+For example:
+\&'\-\-log\-enable warning+' logs all
+warning, error and critical messages.
+\&'\-\-log\-enable debug:framing' logs debug
+messages from the framing namespace.
+This option can be used multiple times
+.TP
+\fB\-\-log\-time\fR yes|no (1)
+Include time in log messages
+.TP
+\fB\-\-log\-level\fR yes|no (1)
+Include severity level in log messages
+.TP
+\fB\-\-log\-source\fR yes|no (0)
+Include source file:line in log
+messages
+.TP
+\fB\-\-log\-thread\fR yes|no (0)
+Include thread ID in log messages
+.TP
+\fB\-\-log\-function\fR yes|no (0)
+Include function signature in log
+messages
+.TP
+\fB\-\-log\-prefix\fR STRING
+Prefix to append to all log messages
+.SS "Logging sink options:"
+.TP
+\fB\-\-log\-to\-stderr\fR yes|no (1)
+Send logging output to stderr
+.TP
+\fB\-\-log\-to\-stdout\fR yes|no (0)
+Send logging output to stdout
+.TP
+\fB\-\-log\-to\-file\fR FILE
+Send log output to FILE.
+.TP
+\fB\-\-log\-to\-syslog\fR yes|no (0)
+Send logging output to syslog;
+customize using \fB\-\-syslog\-name\fR and
+\fB\-\-syslog\-facility\fR
+.TP
+\fB\-\-syslog\-name\fR NAME (lt\-qpidd)
+Name to use in syslog messages
+.TP
+\fB\-\-syslog\-facility\fR LOG_XXX (LOG_DAEMON)
+Facility to use in syslog messages
+.SS "Daemon options:"
+.TP
+\fB\-d\fR [ \fB\-\-daemon\fR ]
+Run as a daemon. Logs to syslog by
+default in this mode.
+.TP
+\fB\-\-transport\fR TRANSPORT (tcp)
+The transport for which to return the
+port
+.TP
+\fB\-\-pid\-dir\fR DIR
+Directory where port\-specific PID file
+is stored
+.TP
+\fB\-w\fR [ \fB\-\-wait\fR ] SECONDS (600)
+Sets the maximum wait time to
+initialize the daemon. If the daemon
+fails to initialize, prints an error
+and returns 1
+.TP
+\fB\-c\fR [ \fB\-\-check\fR ]
+Prints the daemon's process ID to
+stdout and returns 0 if the daemon is
+running, otherwise returns 1
+.TP
+\fB\-q\fR [ \fB\-\-quit\fR ]
+Tells the daemon to shut down
+.SH ENVIRONMENT
+.I QPID_<option>
+.RS
+There is an environment variable for each option.
+.RE
+
+The environment variable is the option name in uppercase, prefixed with QPID_ and '.' or '-' are replaced with '_'. Environment settings are over-ridden by command line settings. For example:
+
+  export QPID_PORT=6000
+  export QPID_MAX_CONNECTIONS=10
+  export QPID_LOG_TO_FILE=/tmp/qpidd.log
+.SH FILES
+.I /etc/qpidd.conf
+.RS
+Default configuration file.
+.RE
+
+Configuration file settings are over-ridden by command line or environment variable settings. '--config <file>' or 'export QPID_CONFIG=<file>' specifies an alternate file.
+
+Each line is a name=value pair. Blank lines and lines beginning with # are ignored. For example:
+
+  # My qpidd configuration file.
+  port=6000
+  max-connections=10
+  log-to-file=/tmp/qpidd.log
+.SH AUTHOR
+
+The Apache Qpid Project, dev@qpid.apache.org
+.SH "REPORTING BUGS"
+
+Please report bugs to users@qpid.apache.org
diff --git a/cpp/docs/man/qpidd.x b/cpp/docs/man/qpidd.x
index af5d9628ee..0ccf3b562a 100644
--- a/cpp/docs/man/qpidd.x
+++ b/cpp/docs/man/qpidd.x
@@ -13,6 +13,8 @@ messages using the Advanced Message Queueing Protocol (AMQP).
 
 [OPTIONS]
 
+The options below are built-in to qpidd. Installing add-on modules provides additional options. To see the full set of options available type "qpidd --help"
+
 Options may be specified via command line, environment variable or configuration file. See FILES and ENVIRONMENT below for details.
 
 [FILES]