Author: philharveyonline Date: Wed Apr 3 12:05:11 2013 New Revision: 1463950
URL: http://svn.apache.org/r1463950 Log: PROTON-280: Added Engine documentation and configured Maven to generate HTML from it and from existing Messenger docs. Moved existing docs down one level because Maven's doxia markdown plugin requires that markdown docs are in a markdown sub-folder. Added: qpid/proton/trunk/docs/markdown/ qpid/proton/trunk/docs/markdown/engine/ qpid/proton/trunk/docs/markdown/engine/engine.md qpid/proton/trunk/docs/markdown/index.md qpid/proton/trunk/docs/markdown/messenger/ qpid/proton/trunk/docs/markdown/messenger/index.md qpid/proton/trunk/docs/markdown/messenger/message_disposition.md - copied, changed from r1463574, qpid/proton/trunk/docs/messenger/message_disposition.md qpid/proton/trunk/docs/markdown/messenger/quick_start_linux.md - copied, changed from r1463574, qpid/proton/trunk/docs/messenger/quick_start_linux.md qpid/proton/trunk/docs/markdown/messenger/sending_and_receiving.md - copied, changed from r1463574, qpid/proton/trunk/docs/messenger/sending_and_receiving.md Removed: qpid/proton/trunk/docs/messenger/message_disposition.md qpid/proton/trunk/docs/messenger/quick_start_linux.md qpid/proton/trunk/docs/messenger/sending_and_receiving.md Modified: qpid/proton/trunk/pom.xml qpid/proton/trunk/proton-j/contrib/proton-hawtdispatch/pom.xml qpid/proton/trunk/proton-j/contrib/proton-jms/pom.xml qpid/proton/trunk/proton-j/pom.xml qpid/proton/trunk/proton-j/proton-api/pom.xml qpid/proton/trunk/proton-j/proton/pom.xml qpid/proton/trunk/tests/pom.xml Added: qpid/proton/trunk/docs/markdown/engine/engine.md URL: http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/engine/engine.md?rev=1463950&view=auto ============================================================================== --- qpid/proton/trunk/docs/markdown/engine/engine.md (added) +++ qpid/proton/trunk/docs/markdown/engine/engine.md Wed Apr 3 12:05:11 2013 @@ -0,0 +1,74 @@ +Proton's Engine is a stateful component with a low-level API that allows an +application to communicate using AMQP. This document gives a high level overview +of the Engine's design, intended to be read by application developers intending +to use it. + +The Engine is built around the concept of a protocol engine. The idea behind a +protocol engine is to capture all the complex details of implementing a given +protocol in a way that is as decoupled as possible from OS details such as I/O +and threading models. The result is a highly portable and easily embedded +component that provides a full protocol implementation. + + +The Engine API +-------------- + +The Engine contains in-memory representations of AMQP entities such as +Connection, Session and Delivery. These are manipulated via its API, which +consists of two main parts. + +- The *control and query API*, commonly referred to as *The Top Half*, which + offers functions to directly create, modify and query the Connections, + Sessions etc. + +- The *transport API*, commonly referred to as *The Bottom Half*, which contains + a small set of functions to operate on the AMQP entities therein by accepting + binary AMQP input and producing binary AMQP output. The Engine's transport + layer can be thought of as transforming a *queue of bytes*, therefore the API + is expressed in terms of input appended to the *tail* and output fetched from + the *head*. + + +Typical Engine usage +-------------------- + +The diagram below shows how the Engine is typically used by an application. The +socket's remote peer is serviced by another AMQP application, which may (or may +not) use Proton. + +<pre> +<![CDATA[ + + +------------ + +---------------+ + | | | | + | Application |--------->| Engine | + | business | | "Top Half" | + | logic | | Control and | + | |<---------| query API | + | | | | + | | +---------------+ + | | | + +-------------+ +-------------+ +---------------+ + | | Input | | Tail | Engine | + | |--------->| |--------->| "Bottom half" | + | Socket | | Application | | Transport API | + | |<---------| I/O layer |<---------| | + | | Output | | Head | | + +-------------+ +-------------+ +---------------+ +]]> +</pre> + +For maximum flexibility, the Engine is not multi-threaded. It is therefore +typical for an application thread to loop continuously, repeatedly calling the +Top Half and Bottom Half functions. + + +Implementations +--------------- + +Implementations of the Engine currently exist in C and Java. Bindings exist from +several languages (e.g. Ruby, Python, Java Native Interface) to the C Engine. + +For more information see the documentation in the code. + + Added: qpid/proton/trunk/docs/markdown/index.md URL: http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/index.md?rev=1463950&view=auto ============================================================================== --- qpid/proton/trunk/docs/markdown/index.md (added) +++ qpid/proton/trunk/docs/markdown/index.md Wed Apr 3 12:05:11 2013 @@ -0,0 +1,27 @@ + +Proton is a library for speaking AMQP, including: + +- The AMQP [Messenger API](messenger/index.html), a simple but powerful interface to send and receive + messages over AMQP. +- The [AMQP Protocol Engine](engine/engine.html), a succinct encapsulation of the full + AMQP protocol machinery. + +Proton is designed for maximum embeddability: + +- minimal dependencies +- minimal assumptions about application threading model + +Proton is designed to scale up and down: + +- transparently supports both simple peer to peer messaging and complex +globally federated topologies + +Proton is multi-lingual: + +- Proton-C - a C implementation with lanuage bindings in Python, Php, Perl, +Ruby, and Java (via JNI). +- Proton-J - a pure Java implementation + +Please see http://qpid.apache.org/proton for a more info. + + Added: qpid/proton/trunk/docs/markdown/messenger/index.md URL: http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/messenger/index.md?rev=1463950&view=auto ============================================================================== --- qpid/proton/trunk/docs/markdown/messenger/index.md (added) +++ qpid/proton/trunk/docs/markdown/messenger/index.md Wed Apr 3 12:05:11 2013 @@ -0,0 +1,8 @@ +See the following Messenger documents: + +[Linux Quick Start](quick_start_linux.html) + +[Sending and Receiving](sending_and_receiving.html) + +[Message Disposition](message_disposition.html) + Copied: qpid/proton/trunk/docs/markdown/messenger/message_disposition.md (from r1463574, qpid/proton/trunk/docs/messenger/message_disposition.md) URL: http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/messenger/message_disposition.md?p2=qpid/proton/trunk/docs/markdown/messenger/message_disposition.md&p1=qpid/proton/trunk/docs/messenger/message_disposition.md&r1=1463574&r2=1463950&rev=1463950&view=diff ============================================================================== --- qpid/proton/trunk/docs/messenger/message_disposition.md (original) +++ qpid/proton/trunk/docs/markdown/messenger/message_disposition.md Wed Apr 3 12:05:11 2013 @@ -10,11 +10,11 @@ detect the disposition of their messages Message States --------------------------- -Messages have one of four different states: - * `PN_STATUS_UNKNOWN` - * `PN_STATUS_PENDING` - * `PN_STATUS_ACCEPTED` - * `PN_STATUS_REJECTED` +Messages have one of four different states: + * `PN_STATUS_UNKNOWN` + * `PN_STATUS_PENDING` + * `PN_STATUS_ACCEPTED` + * `PN_STATUS_REJECTED` <br/> @@ -66,7 +66,6 @@ be changed, even if you have a separate <br/> <br/> - ### sending ### @@ -76,7 +75,7 @@ if it has a positive outgoing window siz pn_messenger_set_outgoing_window ( messenger, N ); -and if a tracker has been associated with that message in question. +and if a tracker has been associated with that message in question. This call: pn_messenger_outgoing_tracker ( messenger ); @@ -93,7 +92,7 @@ The returned value will be one of * `PN_STATUS_ACCEPTED` * `PN_STATUS_REJECTED` , or -* `PN_STATUS_PENDING` - If the receiver has not disposed the message yet. +* `PN_STATUS_PENDING` - If the receiver has not disposed the message yet. If either the sender or the receiver simply declares the message (or range of messages) to @@ -107,14 +106,14 @@ settled messages. <br/> -_Note_ +_Note_ If a message is rejected by the receiver, it does not mean that the message was malformed. Malformed messages cannot be sent. Even messages with no content are valid messages. Rejection by a receiver should be understood as the receiver -saying "I don't want this." or possibly "I don't want this _yet_." +saying "I don't want this." or possibly "I don't want this _yet_." dependeing on your application. -The sender could decide to try sending the same message again later, +The sender could decide to try sending the same message again later, or to send the message to another receiver, or to discard it. Copied: qpid/proton/trunk/docs/markdown/messenger/quick_start_linux.md (from r1463574, qpid/proton/trunk/docs/messenger/quick_start_linux.md) URL: http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/messenger/quick_start_linux.md?p2=qpid/proton/trunk/docs/markdown/messenger/quick_start_linux.md&p1=qpid/proton/trunk/docs/messenger/quick_start_linux.md&r1=1463574&r2=1463950&rev=1463950&view=diff ============================================================================== --- qpid/proton/trunk/docs/messenger/quick_start_linux.md (original) +++ qpid/proton/trunk/docs/markdown/messenger/quick_start_linux.md Wed Apr 3 12:05:11 2013 @@ -3,7 +3,7 @@ Linux Quick Start On a Linux system, these instructions take you from -zero to running your first example code. You will +zero to running your first example code. You will need root privileges for one of the commands. Copied: qpid/proton/trunk/docs/markdown/messenger/sending_and_receiving.md (from r1463574, qpid/proton/trunk/docs/messenger/sending_and_receiving.md) URL: http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/messenger/sending_and_receiving.md?p2=qpid/proton/trunk/docs/markdown/messenger/sending_and_receiving.md&p1=qpid/proton/trunk/docs/messenger/sending_and_receiving.md&r1=1463574&r2=1463950&rev=1463950&view=diff ============================================================================== (empty) Modified: qpid/proton/trunk/pom.xml URL: http://svn.apache.org/viewvc/qpid/proton/trunk/pom.xml?rev=1463950&r1=1463949&r2=1463950&view=diff ============================================================================== --- qpid/proton/trunk/pom.xml (original) +++ qpid/proton/trunk/pom.xml Wed Apr 3 12:05:11 2013 @@ -16,6 +16,7 @@ limitations under the License. --> <project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd";> + <description>Proton is a library for speaking AMQP.</description> <parent> <groupId>org.apache</groupId> <artifactId>apache</artifactId> @@ -32,19 +33,44 @@ <junit-version>4.10</junit-version> </properties> + <distributionManagement> + <site> + <id>proton-site-id</id> + <!-- Maven requires a site url even if you only run site:stage --> + <url>file:///tmp/proton-site</url> + </site> + </distributionManagement> + <build> <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-compiler-plugin</artifactId> - <configuration> - <source>1.6</source> - <target>1.6</target> - <optimize>true</optimize> - <showDeprecation>true</showDeprecation> - <showWarnings>true</showWarnings> - </configuration> - </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-compiler-plugin</artifactId> + <configuration> + <source>1.6</source> + <target>1.6</target> + <optimize>true</optimize> + <showDeprecation>true</showDeprecation> + <showWarnings>true</showWarnings> + </configuration> + </plugin> + + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-site-plugin</artifactId> + <dependencies> + <dependency> + <groupId>org.apache.maven.doxia</groupId> + <artifactId>doxia-module-markdown</artifactId> + <version>1.3</version> + </dependency> + </dependencies> + <configuration> + <inputEncoding>UTF-8</inputEncoding> + <outputEncoding>UTF-8</outputEncoding> + <siteDirectory>docs</siteDirectory> + </configuration> + </plugin> </plugins> </build> @@ -68,4 +94,14 @@ </profile> </profiles> + <url>http://qpid.apache.org/proton</url> + <scm> + <url>http://svn.apache.org/viewvc/qpid/proton/</url> + </scm> + <issueManagement> + <url>https://issues.apache.org/jira/browse/PROTON</url> + </issueManagement> + <ciManagement> + <url>https://builds.apache.org/view/M-R/view/Qpid/job/Qpid-proton-j/</url> + </ciManagement> </project> Modified: qpid/proton/trunk/proton-j/contrib/proton-hawtdispatch/pom.xml URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-j/contrib/proton-hawtdispatch/pom.xml?rev=1463950&r1=1463949&r2=1463950&view=diff ============================================================================== Binary files - no diff available. Modified: qpid/proton/trunk/proton-j/contrib/proton-jms/pom.xml URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-j/contrib/proton-jms/pom.xml?rev=1463950&r1=1463949&r2=1463950&view=diff ============================================================================== Binary files - no diff available. Modified: qpid/proton/trunk/proton-j/pom.xml URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-j/pom.xml?rev=1463950&r1=1463949&r2=1463950&view=diff ============================================================================== --- qpid/proton/trunk/proton-j/pom.xml (original) +++ qpid/proton/trunk/proton-j/pom.xml Wed Apr 3 12:05:11 2013 @@ -24,6 +24,7 @@ <modelVersion>4.0.0</modelVersion> <artifactId>proton-j</artifactId> + <name>proton-j</name> <packaging>pom</packaging> <dependencies> @@ -41,5 +42,8 @@ <module>contrib/proton-jms</module> <module>contrib/proton-hawtdispatch</module> </modules> + <scm> + <url>http://svn.apache.org/viewvc/qpid/proton/</url> + </scm> </project> Modified: qpid/proton/trunk/proton-j/proton-api/pom.xml URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-j/proton-api/pom.xml?rev=1463950&r1=1463949&r2=1463950&view=diff ============================================================================== --- qpid/proton/trunk/proton-j/proton-api/pom.xml (original) +++ qpid/proton/trunk/proton-j/proton-api/pom.xml Wed Apr 3 12:05:11 2013 @@ -24,5 +24,9 @@ <modelVersion>4.0.0</modelVersion> <artifactId>proton-api</artifactId> + <name>proton-api</name> + <scm> + <url>http://svn.apache.org/viewvc/qpid/proton/</url> + </scm> </project> Modified: qpid/proton/trunk/proton-j/proton/pom.xml URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-j/proton/pom.xml?rev=1463950&r1=1463949&r2=1463950&view=diff ============================================================================== --- qpid/proton/trunk/proton-j/proton/pom.xml (original) +++ qpid/proton/trunk/proton-j/proton/pom.xml Wed Apr 3 12:05:11 2013 @@ -24,6 +24,7 @@ <modelVersion>4.0.0</modelVersion> <artifactId>proton-j-impl</artifactId> + <name>proton-j-impl</name> <dependencies> <dependency> @@ -46,4 +47,7 @@ </dependency> </dependencies> + <scm> + <url>http://svn.apache.org/viewvc/qpid/proton/</url> + </scm> </project> Modified: qpid/proton/trunk/tests/pom.xml URL: http://svn.apache.org/viewvc/qpid/proton/trunk/tests/pom.xml?rev=1463950&r1=1463949&r2=1463950&view=diff ============================================================================== --- qpid/proton/trunk/tests/pom.xml (original) +++ qpid/proton/trunk/tests/pom.xml Wed Apr 3 12:05:11 2013 @@ -22,6 +22,7 @@ <modelVersion>4.0.0</modelVersion> <artifactId>tests</artifactId> + <name>tests</name> <description>The Proton system tests execute against either the Java or the C implementations, based on the chosen profile. @@ -137,4 +138,7 @@ To override this, run Maven like so: &qu <artifactId>proton-project</artifactId> <version>1.0-SNAPSHOT</version> </parent> + <scm> + <url>http://svn.apache.org/viewvc/qpid/proton/</url> + </scm> </project> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
