activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chir...@apache.org
Subject svn commit: r1049736 - in /activemq/activemq-apollo/trunk/apollo-website/src: documentation/index.page documentation/user-manual.md index.page styles/impact/css/site.css
Date Wed, 15 Dec 2010 23:07:38 GMT
Author: chirino
Date: Wed Dec 15 23:07:38 2010
New Revision: 1049736

URL: http://svn.apache.org/viewvc?rev=1049736&view=rev
Log:
More doco.

Added:
    activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md
Modified:
    activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page
    activemq/activemq-apollo/trunk/apollo-website/src/index.page
    activemq/activemq-apollo/trunk/apollo-website/src/styles/impact/css/site.css

Modified: activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page
URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page?rev=1049736&r1=1049735&r2=1049736&view=diff
==============================================================================
--- activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page (original)
+++ activemq/activemq-apollo/trunk/apollo-website/src/documentation/index.page Wed Dec 15
23:07:38 2010
@@ -23,6 +23,8 @@ ${project_slogan}
 
 # Documentation
 
+* [Getting Started Guide](getting-started.html)
+* [User Manual](user-manual.html)
 * [Performance and Scaling](performance-scaling.html)
 * [Architecture](architecture.html)
 * [Module Organization](module-organization.html)

Added: activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md
URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md?rev=1049736&view=auto
==============================================================================
--- activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md (added)
+++ activemq/activemq-apollo/trunk/apollo-website/src/documentation/user-manual.md Wed Dec
15 23:07:38 2010
@@ -0,0 +1,308 @@
+# Apollo ${project_version} User Manual
+
+{:toc}
+
+## Creating a Broker
+
+{pygmentize_and_compare::}
+-----------------------------
+haml: An example .scaml file
+-----------------------------
+%html
+  %body
+    The quick brown fox jumps 
+    over the lazy dog
+-----------------------------
+text: An equivalent .jade file
+-----------------------------
+html
+  body
+    | The quick brown fox jumps 
+    | over the lazy dog
+{pygmentize_and_compare}
+
+Both examples above will render to the following:
+
+{pygmentize:: xml}
+<html>
+  <body>
+    The quick brown fox jumps 
+    over the lazy dog
+  </body>
+</html>
+{pygmentize}
+
+A broker instance is the directory containing all the configuration and
+runtime data such as logs and data files associated with a broker process. It
+is recommended that you do *not* create the instance directory under the
+directory where the ${project_name} distribution is installed.
+
+On unix systems, it is a common convention to store this kind of runtime data
+under the `/var/lib` directory. For example, to create an instance at
+'/var/lib/mybroker', run:
+
+    cd /var/lib
+    apollo create mybroker
+
+A broker instance directory will contain the following sub directories:
+
+ * `bin` : holds execution scripts associated with this instance.
+ * `etc` : hold the instance configuration files
+ * `data` : holds the data files used for storing persistent messages
+ * `log` : holds rotating log files
+ * `tmp` : holds temporary files that are safe to delete between broker runs
+
+At this point you may want to adjust the default configuration located in
+etc directory.
+
+## Broker Configuration
+
+Each broker instance can be tuned and configured by editing one of the
+following files.
+
+* `bin/apollo-broker` : You can update the start script to control JVM level
+  configuration options like JVM memory sizing.
+* `etc/apollo.xml` : The primary configuration file for the broker. It
+  controls the opened ports, the queues, security, virtual host settings and
+  more.
+* `etc/log4j.properties` : This is a standard 
+  [log4j](http://logging.apache.org/log4j/1.2/manual.html) configuration file
+  which controls the broker's logging.
+* `etc/keystore` : A Java key store used to hold cryptographic security keys
+  and certificates.  It is only need for brokers using SSL.
+* `etc/login.conf` : A standard JAAS [login.conf] configuration file used to
+  define the JAAS authentication domains available to the broker.
+* `etc/users.properties` : Holds userid/password mappings of users that can 
+  access the broker.  Referenced by the `etc/login.conf` file.
+* `etc/groups.properties` : Holds groups to users mappings so that you can
+  simplify access control lists (ACL) by using group instead listing individual
+  users.
+ 
+[login.conf]: http://download.oracle.com/javase/1.5.0/docs/guide/security/jaas/tutorials/LoginConfigFile.html
+
+## Using the STOMP Protocol
+
+Clients can connect to ${project_name} using the
+[STOMP](http://stomp.github.com/) protocol. STOMP provides an interoperable
+messaging wire level protocol that allows any STOMP clients can communicate
+with any STOMP message broker. It aims to provide easy and widespread
+messaging interoperability among many languages, platforms and brokers.
+
+${project_name} supports the following versions of the STOMP specification: 
+
+* [STOMP 1.0](http://stomp.github.com/stomp-specification-1.0.html)
+* [STOMP 1.1](http://stomp.github.com/stomp-specification-1.1.html) *Not final*
+
+The specification is short and simple to read, it is highly recommend that users
+to get familiar with it before using one of the many available client libraries.
+
+### Client Libraries
+
+There are many open source STOMP clients for different platforms and
+languages.  You can find a full listing of available clients at:
+
+* http://stomp.github.com/implementations.html#Clients
+
+The ${project_name} distribution ships with an `examples` directory
+where you can find some simple examples of how to use some of those
+clients to send and receive messages from a broker instance.
+
+This section will focus on clarifying the parts of the STOMP specification
+which allow servers to choose their behavior and to describe how to access
+${project_name} specific features.
+
+### Connecting
+
+The default broker configuration secures access to the broker so that only
+the `admin` user can connect.  The default password for the `admin` user 
+is `password`.
+
+Example STOMP frame to connect to the broker:
+
+    CONNECT
+    
+    login:admin
+    passcode:password
+    
+    ^@
+
+STOMP 1.0 clients do specify which virtual host they are connecting to so
+the broker connects those clients to the first virtual host defined in
+it's configuration.  STOMP 1.1 clients do specify a virtual host when they 
+connect.  If no configured virtual host `host-name` matches the client's 
+requested host, the connection is terminated with an ERROR.  Therefore,
+it is critical that the virtual hosts configuration define all the 
+possible host names that clients may connect to host with.
+
+### Destination Types
+
+${project_name} supports two main types of destinations, queues and topics.
+The most striking difference between queues and topics is how messages are 
+delivered to consumers.  A queue will load it's messages over the connected
+subscribers so that only one subscriber gets a message.  A topic follows the
+publish/subscribe patterns and it's subscribers each get a copy of every
+message sent.
+
+If you want to send or subscribe to a queue or topic, the STOMP destination
+should be prefixed with `/queue/` or `/topic/` respectively.
+
+Example STOMP frame sending to a queue:
+
+    SEND
+    destination:/queue/a
+
+    hello queue a
+    ^@
+
+Another major difference between queues and topics is that queues hold 
+on to unconsumed messages even when there are no subscriptions attached,
+while a topic will drop messages when there are no connected subscriptions.
+${project_name} allows you to create Durable Subscriptions against topics
+so that a subscription can "out live" the connection that created the 
+subscription.  This allows you consume all the messages sent to the 
+topic without messages getting dropped.
+
+### Reliable Messaging
+
+${project_name} supports reliable messaging by allowing messages to be
+persisted so that they can be recovered if there is failure which kills
+the broker.  Processing persistent messages has orders of magnitude more
+overhead than non-persistent variety.  You should only use it if your
+application really needs it.
+
+To have a message be persistent, the sender must add the `persistent:true`
+header to the `SEND` STOMP frame.  Furthermore, if you are not sending the 
+message in a transaction, it is recommend that you also add a `receipt`
+header.  Once the broker responds with a `RECEIPT` frame correlated to 
+the send, you are guaranteed the broker will not drop the message even if
+a failure occurs.
+
+Example:
+
+    SEND
+    destination:/queue/a
+    receipt:001
+
+    hello queue a
+    ^@
+
+The client should not consider the send to have succeeded until he receives
+the correlated `RECEIPT` frame from the server.  Example:
+
+    RECEIPT
+    receipt-id:001
+    
+    ^@
+
+It is important to note that to do reliable messaging, your system will
+be prone to receive duplicate messages.  For example, if your sending 
+application dies before it receives the `RECEIPT` frame, then when it starts
+up again will probably try to send the same message again which may
+cause a duplicate message to get placed on the broker.
+
+You should only use subscribers which use the `client` or `client-individual`
+ack mode to consume reliable messages. Any messages on a queue delivered to a
+client which have not been acked when the client disconnects will get
+redelivered to another subscribed client.
+
+### Topic Durable Subscriptions
+
+A durable subscription is a queue which is subscribed to a topic so that
+even if the client which created the durable subscription is not
+online, he can still get a copy of all the messages sent to the topic
+when he comes back online.  Multiple clients can subscribe to the same
+durable subscription and since it's backed by a queue, those subscribers
+will have the topic's messages load balanced across them.
+
+To create or reattach to a a durable subscription with STOMP, you uniquely name
+the durable subscription using the `id` header on the `SUBSCRIBE` frame and
+also adding a `persistent:true` header. Example:
+
+    SUBSCRIBE
+    id:mysub
+    persistent:true
+    destination:/topic/foo
+    
+    ^@
+
+A standard `UNSUBSCRIBE` frame does not destroy the durable subscription, it 
+only disconnects the client from the durable subscription.  To destroy a 
+durable subscription, you must once again add `persistent:true` header
+to the `UNSUBSCRIBE` frame.  Example:
+
+    UNSUBSCRIBE
+    id:mysub
+    persistent:true
+    
+    ^@
+
+### Destination Wildcards
+
+We support destination wildcards to easily subscribe to multiple destinations
+with one subscription. This concept has been popular in financial market data
+for some time as a way of organizing events (such as price changes) into
+hierarchies and to use wildcards for easy subscription of the range of
+information you're interested in.
+
+* `.` is used to separate names in a path
+* `*` is used to match any name in a path
+* `**` is used to recursively match path names
+
+For example imagine you are sending price messages from a stock exchange feed.
+You might use some kind of destination naming conventions such as:
+
+* `/topic/PRICE.STOCK.NASDAQ.IBM` to publish IBM's price on NASDAQ and
+* `/topic/PRICE.STOCK.NYSE.SUNW` to publish Sun's price on the New York Stock Exchange
+
+A subscriber could then use exact destinations to subscribe to exactly the
+prices it requires. Or it could use wildcards to define hierarchical pattern
+matches to the destinations to subscribe from.
+
+For example using the example above, these subscriptions are possible
+
+* `/topic/PRICE.**` : Any price for any product on any exchange
+* `/topic/PRICE.STOCK.**` : Any price for a stock on any exchange
+* `/topic/PRICE.STOCK.NASDAQ.*` : Any stock price on NASDAQ
+* `/topic/PRICE.STOCK.*.IBM` : Any IBM stock price on any exchange
+
+Destination wildcards can only be used in a SUBSCRIBE frame.
+
+### Composite Destinations
+
+You can use composite destinations to send or subscribe to multiple
+destinations at one time. You use separator of `,` between destination
+names.  For example, to send one message to 2 queues and 1 topic:
+
+    SEND
+    destination:/queue/a,/queue/b,/topic/c
+
+    Composites rock!
+    ^@
+
+### Message Selectors
+
+Message selectors allow a subscription to only receive a subset of the
+messages sent to a destination.  The selector acts like a filter which
+is applied against the message properties and only those messages
+which match pass through to the subscription.  
+
+Selectors are defined using SQL 92 syntax and typically apply to message
+headers; whether the standard properties available on a JMS message or custom
+headers you can add via the JMS code.
+
+Here is an example:
+
+    type = 'car' AND color = 'blue' AND weight > 2500
+
+To create a subscription with a message selector, you set the `selector`
+header in the STOMP `SUBSCRIBE` frame to the desired selector. Example:
+
+    SUBSCRIBE
+    id:sub0
+    selector:type = 'car' AND color = 'blue' AND weight > 2500
+    destination:/topic/foo
+    
+    ^@
+
+
+

Modified: activemq/activemq-apollo/trunk/apollo-website/src/index.page
URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/index.page?rev=1049736&r1=1049735&r2=1049736&view=diff
==============================================================================
--- activemq/activemq-apollo/trunk/apollo-website/src/index.page (original)
+++ activemq/activemq-apollo/trunk/apollo-website/src/index.page Wed Dec 15 23:07:38 2010
@@ -13,40 +13,41 @@
 # 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.
+title: Apollo
+--- name:overview
 
-title: Apollo ${project_version}
-in_menu: true
-sort_info: 1
---- name:overview pipeline:scaml
-
-%h1 Apollo #{project_version}
+# Apollo ${project_version}
 
 #{project_slogan}
 
 --- name:content pipeline:markdown 
 
-[Apollo][] is a [Scala 2.8](http://www.scala-lang.org) based messaging broker.
-It can be thought of as a forked and stripped down version of [Apache ActiveMQ][] . 
-It is focused on providing a simple, stable, scalable messaging core which is easy
-to extend.
-
-[Apollo]:http://github.com/chirino/activemq-apollo
-[Apache ActiveMQ]:http://activemq.apache.org/
+[Apollo](http://activemq.apache.org/apollo/) is a 
+[Scala 2.8](http://www.scala-lang.org) based messaging broker. 
+It can be thought of as a forked and stripped down version of 
+[Apache ActiveMQ](http://activemq.apache.org/) . It is focused on 
+providing a simple, stable, scalable messaging core which is easy to extend.
 
 ## Implemented Features
 
-* Topic style message routing
-* Queue style message routing
-* Persistent Messages
-* Message paging/swapping
-  queue sizes
-* Message Selectors
+* [Topics and Queues](documentation/user-manual.html#Destination_Types)
 * Queue Browsers
+* [Durable Subscriptions on Topics](documentation/user-manual.html#Topic_Durable_Subscriptions)
+* [Persistence](documentation/user-manual.html#Reliable_Messaging)
+* Message swapping
+* [Message Selectors](documentation/user-manual.html#Message_Selectors)
+* ACL based security
+* JAAS Authorization
+* SSL/TLS Support
 * REST based management
-* [Stomp 1.1](http://stomp.github.com/stomp-specification-1-1.html) Protocol Support
+* [Stomp 1.0](http://stomp.github.com/stomp-specification-1.0.html) Protocol
+  Support
+* [Stomp 1.1](http://stomp.github.com/stomp-specification-1.1.html) Protocol
+  Support
 
-## Guides
+## Documentation
 
  * [Getting Started Guide](documentation/getting-started.html)
+ * [User Manual](documentation/user-manual.html)
  
 

Modified: activemq/activemq-apollo/trunk/apollo-website/src/styles/impact/css/site.css
URL: http://svn.apache.org/viewvc/activemq/activemq-apollo/trunk/apollo-website/src/styles/impact/css/site.css?rev=1049736&r1=1049735&r2=1049736&view=diff
==============================================================================
--- activemq/activemq-apollo/trunk/apollo-website/src/styles/impact/css/site.css (original)
+++ activemq/activemq-apollo/trunk/apollo-website/src/styles/impact/css/site.css Wed Dec 15
23:07:38 2010
@@ -1,5 +1,5 @@
 body, html {
-    font-family:Arial,Verdana,Helvetica,sans-serif;
+    font-family:Georgia, Arial, sans-serif; 
     color: #666666;
 }
 body, html, table, tr, td, tbody {
@@ -12,6 +12,7 @@ body {
 }
 
 h1, h2, h3, h4, h5, h6 {
+    font-family: 'Graublau Web', Helvetica, sans-serif;
     overflow: visible;
     color: #993333;
 }



Mime
View raw message