Here are some general comments.
Frankly I am not too happy with the current format.
I'd like to see the following in the docs.
1. The user guide should be tied to a particular version, as we are
shipping them for each release.
2. The guide should focus on end users, not developers. So we should
get rid of all design docs.
3. Our documentation should reflect the goals, vision and direction of
the project.
a) Brokers with a common set of features
b) Management tools that work with both brokers
c) Common Client API's
d) Interoperability via examples
4. I would like to see the TOC as follows.
I. Introduction
What you have here is fine, but I am not sure about the getting
started and download stuff. I need to think about it a bit more.
II. AMQP Messaging Brokers
I think rather than having separate sections for each broker, it's
best to describe common functionality first then we can have separate
chapters for each broker.
Recently Rob Godfrey has done a tremendous amount of work to bring
the Java broker inline with the c++ broker in terms of features.
Ex. Federation, QMF support, LVQ etc... (in addition common
features include ACL, Authentication, SSL ..etc)
So perhaps the section can be organized as,
Chapter 1. Broker concepts (Federation, Security {ACL,
Authentication, SSL}, QMF, LVQ ..etc)
Chapter 2. Java Broker
Chapter 3. C++ Broker
(Chapters 2&3 describes the specifics like how to install, run, and
configure)
II. AMQP Messaging Clients
We should again explain the common concepts and vision behind the
client API's while stating that JMS and WCF are following idioms/API's
that are already defined for those domains.
The specific chapters on each client will focus on the languages
specific items like (how to open a connection, receive a message, send
a message ..etc) and the relevant configuration options.
Chapter 1. API and addressing syntax.
Chapter 2. Python Client
Chapter 3. C++ Client
Chapter 4. JMS Client
Chapter 5. WCF Client
Chapter 6. Ruby Client
III. AMQP Messaging Broker Management.
This should be a top level section on it's own rather than
anything that C++/Java broker specific. A majority of these tools can
be used against both.
We should state that our brokers can be managed using QMF (and JMX
- the Java broker directly and the C++ broker via QMan).
Chapter 1. Python management tools - (qpid-config,......)
Chapter 2. QMan.
QMF-to-JMX bridge
QMF-to-WSDM bridge
Chapter 3. Eclipse pluggins
IV. QMF
This is actually a sub project of Qpid that can be used to manage
anything. So IMO it deserves it's own section.
Chapter 1. QMF Concepts
Chapter 2. QMF C++ API
Chapter 2. QMF Python API
Chapter 4. QMF Java API
V. Testing Frameworks and Tools
Here we can talk about our testing frameworks and perf tools
VI. Examples/Tutorial
I am not still sure about how this section should look like,
other than we need one :).
VII. Appendix
Regards,
Rajith
On Tue, Mar 16, 2010 at 10:18 AM, Jonathan Robie
<[email protected]> wrote:
> I'd like feedback on the overall file structure and organization of the Qpid
> DocBook docs - is this a structure we feel comfortable adding to? Does it
> need to be changed in any way? I'd like to get that part right first.
>
> Here is the table of contents:
>
> Table of Contents
> I. Basics
> ............................................................................................................................
> 1
> 1. Apache Qpid: Open Source AMQP Messaging
> ............................................................. 3
> AMQP Messaging Brokers
> ...................................................................................
> 3
> AMQP Client APIs: C++, Java, JMS, Ruby, Python, and C#
> ...................................... 3
> Operating Systems and Platforms:
> ......................................................................... 3
> 2. AMQP (Advanced Message Queueing Protocol
> ............................................................ 5
> Download the AMQP Specifications
> ...................................................................... 5
> 3. Getting Started
> .......................................................................................................
> 7
> 4. Download Apache Qpid
> ...........................................................................................
> 9
> Production Releases
> ............................................................................................
> 9
> 0.5 Release
> ........................................................................................................
> 9
> Multiple Component Packages
> ...................................................................... 9
> Single Component Package
> .......................................................................... 9
> QpidComponents.org
> .........................................................................................
> 10
> Contributed C++ Packages
> .................................................................................
> 11
> Pre-built Linux Packages
> ............................................................................
> 11
> Windows Installer
> .....................................................................................
> 11
> Source Code Repository
> .....................................................................................
> 11
> II. AMQP Messaging Broker (Implemented in C++)
> ............................................................... 12
> 5. Running the AMQP Messaging Broker
> .................................................................... 13
> Running a Qpid C++ Broker
> ............................................................................
> 13
> Building the C++ Broker and Client Libraries
> .............................................. 13
> Running the C++ Broker
> ..........................................................................
> 13
> Most common questions getting qpidd running
> ............................................. 13
> Authentication
> ........................................................................................
> 14
> Slightly more complex configuration
> .......................................................... 15
> Loading extra modules
> ............................................................................
> 16
> Cheat Sheet for configuring Queue Options
> ......................................................... 17
> Configuring Queue Options
> ...................................................................... 17
> Cheat Sheet for configuring Exchange Options
> ..................................................... 19
> Configuring Exchange Options
> .................................................................. 19
> Using Broker Federation
> ..................................................................................
> 21
> Introduction
> ...........................................................................................
> 21
> What Is Broker Federation?
> ...................................................................... 21
> The qpid-route Utility
> ..............................................................................
> 21
> Example Scenarios
> ..................................................................................
> 27
> Advanced Topics
> ....................................................................................
> 29
> SSL
> ..............................................................................................................
> 29
> SSL How to
> ..........................................................................................
> 29
> LVQ
> ............................................................................................................
> 31
> Understanding LVQ
> ................................................................................
> 31
> LVQ semantics:
> .....................................................................................
> 31
> LVQ_NO_BROWSE semantics:
> ................................................................ 32
> Example source
> ......................................................................................
> 33
> queue state replication
> .....................................................................................
> 36
> Asynchronous Replication of Queue State
> ................................................... 36
> Starting a cluster
> ............................................................................................
> 40
> Running a Qpidd cluster
> ..........................................................................
> 40
> ACL
> .............................................................................................................
> 42
> v2 ACL file format for brokers
> ................................................................. 42
> Design Documentation
> .............................................................................
> 45
> v2 ACL User Guide
> ................................................................................
> 46
> 6. Managing the AMQP Messaging Broker
> .................................................................. 48
> Managing the C++ Broker
> ................................................................................
> 48
> Using qpid-config
> ...................................................................................
> 48
> Using qpid-route
> .....................................................................................
> 50
> Using qpid-tool
> ......................................................................................
> 51
> Using qpid-printevents
> .............................................................................
> 55
> QMan - Qpid Management bridge
> ..................................................................... 55
> QMan : Qpid Management Bridge
> ............................................................. 55
> Qpid Management Framework
> ..........................................................................
> 56
> What Is QMF
> ........................................................................................
> 56
> Getting Started with QMF
> ........................................................................ 57
> QMF Concepts
> .......................................................................................
> 57
> The QMF Protocol
> ..................................................................................
> 61
> How to Write a QMF Console
> .................................................................. 61
> How to Write a QMF Agent
> ..................................................................... 61
> Management Design notes
> ................................................................................
> 61
> Status of This Document
> ..........................................................................
> 61
> Introduction
> ...........................................................................................
> 62
> Links
> ....................................................................................................
> 62
> Management Requirements
> ....................................................................... 62
> Definition of Terms
> ................................................................................
> 63
> Operational Scenarios: Basic vs. Extended
> ................................................... 63
> Architectural Framework
> ..........................................................................
> 63
> The Management Exchange
> ...................................................................... 64
> The Protocol
> ..........................................................................................
> 65
> QMF Python Console Tutorial
> ..........................................................................
> 79
> Prerequisite - Install Qpid Messaging
> ......................................................... 79
> Synchronous Console Operations
> ............................................................... 79
> Asynchronous Console Operations
> ............................................................. 84
> Discovering what Kinds of Objects are Available
> .......................................... 88
> III. AMQP Messaging Broker (Implemented in Java)
> .............................................................. 89
> 7. General User Guides
> ..............................................................................................
> 90
> Java Broker Feature Guide
> ...............................................................................
> 90
> The Qpid pure Java broker currently supports the following
> features: ................ 90
> Qpid Java FAQ
> ..............................................................................................
> 90
> Purpose
> ...................................................................................................
> 90
> Java Environment Variables
> ............................................................................
> 100
> Setting Qpid Environment Variables
> ......................................................... 100
> Qpid Troubleshooting Guide
> ...........................................................................
> 100
> I'm getting a java.lang.UnsupportedClassVersionError when I
> try to start the
> broker. What does this mean ?
> .................................................................. 100
> I'm having a problem binding to the required host:port at
> broker startup ? ......... 101
> I'm having problems with my classpath. How can I ensure that
> my classpath is
> ok ?
> .....................................................................................................
> 101
> I can't get the broker to start. How can I diagnose the
> problem ? ..................... 101
> When I try to send messages to a queue I'm getting a error
> as the queue does not
> exist. What can I do ?
> .............................................................................
> 101
> 8. How Tos
> ............................................................................................................
> 102
> Add New Users
> ............................................................................................
> 102
> Available Password file formats
> ............................................................... 102
> Dynamic changes to password files.
> ......................................................... 103
> How password files and PrincipalDatabases relate to
> authentication
> mechanisms
> ..........................................................................................
> 104
> Configure ACLs
> ...........................................................................................
> 104
> Configure ACLs
> ...................................................................................
> 104
> Configure Java Qpid to use a SSL connection.
> .................................................... 104
> Using SSL connection with Qpid Java.
> ...................................................... 104
> Setup
> ..................................................................................................
> 104
> Performing the connection.
> ..................................................................... 105
> Configure Log4j CompositeRolling Appender
> .................................................... 105
> How to configure the CompositeRolling log4j Appender
> ............................... 105
> Configure the Broker via config.xml
> ................................................................. 107
> Broker config.xml Overview
> ................................................................... 107
> Qpid Version
> .......................................................................................
> 107
> Configure the Virtual Hosts via virtualhosts.xml
> ................................................. 107
> virtualhosts.xml Overview
> ...................................................................... 107
> Debug using log4j
> .........................................................................................
> 109
> Debugging with log4j configurations
> ........................................................ 109
> How to Tune M3 Java Broker Performance
> ....................................................... 113
> Problem Statement
> ................................................................................
> 113
> Successful Tuning Options
> ..................................................................... 113
> Next Steps
> ...........................................................................................
> 114
> Qpid Java Build How To
> ...............................................................................
> 114
> Build Instructions - General
> .................................................................... 114
> Build Instructions - Trunk
> ...................................................................... 115
> Use Priority Queues
> ......................................................................................
> 118
> General Information
> ..............................................................................
> 118
> Defining Priority Queues
> ........................................................................ 118
> Client configuration/messaging model for priority queues
> ............................. 119
> 9. Qpid JMX Management Console
> ...........................................................................
> 120
> Qpid JMX Management Console
> ..................................................................... 120
> Overview
> .............................................................................................
> 120
> 10. Management Tools
> .............................................................................................
> 135
> MessageStore Tool
> ........................................................................................
> 135
> MessageStore Tool
> ................................................................................
> 135
> Qpid Java Broker Management CLI
> ................................................................. 136
> How to build Apache Qpid CLI
> ............................................................... 136
> IV. AMQP Messaging Clients Clients
> .................................................................................
> 138
> 11. AMQP Java JMS Messaging Client
> ...................................................................... 140
> General User Guides
> ........................................................................................
> 140
> System Properties
> .................................................................................
> 140
> Connection URL Format
> ........................................................................ 143
> Binding URL Format
> .............................................................................
> 145
> AMQP Java JMS Examples
> .............................................................................
> 147
> 12. AMQP C++ Messaging Client
> .............................................................................
> 148
> User Guides
> .................................................................................................
> 148
> Examples
> .....................................................................................................
> 148
> 13. AMQP .NET Messaging Client
> ...........................................................................
> 149
> User Guides
> .................................................................................................
> 149
> Apache Qpid: Open Source AMQP Messaging - .NET User Guide
> .................. 149
> Excel AddIn
> .........................................................................................
> 164
> WCF
> ..................................................................................................
> 166
> Examples
> .....................................................................................................
> 167
> 14. AMQP Python Messaging Client
> .........................................................................
> 168
> User Guides
> .................................................................................................
> 168
> Examples
> .....................................................................................................
> 168
> PythonBrokerTest
> .........................................................................................
> 168
> Python Broker System Test Suite
> ............................................................. 168
> 15. AMQP Ruby Messaging Client
> ...........................................................................
> 169
> Examples
> .....................................................................................................
> 169
> V. Appendices
> ................................................................................................................
> 170
> 16. AMQP compatibility
> .........................................................................................
> 172
> AMQP Compatibility of Qpid releases:
> ............................................................. 172
> Interop table by AMQP specification version
> ..................................................... 173
> 17. Qpid Interoperability Documentation
> .................................................................... 174
> Qpid Interoperability Documentation
> ................................................................ 174
> SASL
> ..................................................................................................
> 174
>
>
> The table of contents is built, bottom up, from the files. Here is the file
> structure:
>
> Book.xml
> Book-Info.xml
> Introduction.xml
> AMQP.xml
> Getting-Started.xml
> Download.xml
> AMQP-Messaging-Broker-CPP.xml
> Running-CPP-Broker.xml
> Cheat-Sheet-for-configuring-Queue-Options.xml
> Cheat-Sheet-for-configuring-Exchange-Options.xml
> Using-Broker-Federation.xml
> SSL.xml
> LVQ.xml
> queue-state-replication.xml
> Starting-a-cluster.xml
> ACL.xml
> Managing-CPP-Broker.xml
> QMan-Qpid-Management-bridge.xml
> Qpid-Management-Framework.xml
> Management-Design-notes.xml
> QMF-Python-Console-Tutorial.xml
> AMQP-Messaging-Broker-Java.xml
> Java-Broker-Feature-Guide.xml
> Qpid-Java-FAQ.xml
> Java-Environment-Variables.xml
> Qpid-Troubleshooting-Guide.xml
> Add-New-Users.xml
> Configure-ACLs.xml
> Configure-Java-Qpid-to-use-a-SSL-connection.xml
> Configure-Log4j-CompositeRolling-Appender.xml
> Configure-the-Broker-via-config.xml.xml
> Configure-the-Virtual-Hosts-via-virtualhosts.xml.xml
> Debug-using-log4j.xml
> How-to-Tune-M3-Java-Broker-Performance.xml
> Qpid-Java-Build-How-To.xml
> Use-Priority-Queues.xml
> Qpid-JMX-Management-Console.xml
> Configuring-Management-Users.xml
> Configuring-Qpid-JMX-Management-Console.xml
> Management-Console-Security.xml
> Qpid-JMX-Management-Console-FAQ.xml
> Qpid-JMX-Management-Console-User-Guide.xml
> Qpid-Management-Features.xml
> MessageStore-Tool.xml
> Qpid-Java-Broker-Management-CLI.xml
> AMQP-Java-JMS-Messaging-Client.xml
> System-Properties.xml
> Connection-URL-Format.xml
> Binding-URL-Format.xml
> AMQP-C++-Messaging-Client.xml
> AMQP-.NET-Messaging-Client.xml
> NET-User-Guide.xml
> Excel-AddIn.xml
> WCF.xml
> AMQP-Python-Messaging-Client.xml
> PythonBrokerTest.xml
> AMQP-Ruby-Messaging-Client.xml
> AMQP-Compatibility.xml
> Qpid-Interoperability-Documentation.xml
>
> Does this organization work?
>
> Jonathan
>
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:[email protected]
>
>
--
Regards,
Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
