Merge pull request #33 from Havret/update_docs
NO-JIRA: Update docs
diff --git a/README.md b/README.md
index 090badd..6862b99 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,13 @@
# Apache-NMS-AMQP
-[](https://travis-ci.org/apache/activemq-nms-amqp)
+## Build Status
-### Overview
+OS | Status
+---|---
+Linux | [](https://travis-ci.org/apache/activemq-nms-amqp)
+Windows | [](https://ci.appveyor.com/project/ApacheSoftwareFoundation/activemq-nms-amqp)
+
+## Overview
The goal of this project is to combine the [.NET Message Service API](http://activemq.apache.org/nms/) (NMS) with
the [Advanced Message Queuing Protocol (AMQP)](https://www.amqp.org/) 1.0 standard wireline protocol. Historically, the Apache community created the NMS API which provided a vendor agnostic .NET interface to a variety of messaging systems. The NMS API gives the flexibility to write .NET applications in C#, VB or any other .NET language, all while using a single API to connect to any number of messaging providers. The Advanced Message Queuing Protocol (AMQP) is an open and standardized internet protocol for reliably passing messages between applications or organizations.
Before AMQP became a standard, organizations used proprietary wireline protocols to connect their systems which lead to vendor lock-in and integration problems when integrating with external organizations.
@@ -15,53 +20,19 @@
If you are a .NET developer that doesn't want to be locked into a messaging implementation then get engaged with this project. Here you will find the open source code base and please provide comments and make your own enhancements. The project will be folded into the Apache community once fully mature.
-### AMQP1.0 Protocol Engine AmqpNetLite
+## AMQP1.0 Protocol Engine AmqpNetLite
Apache-NMS-AMQP uses [AmqpNetLite](https://github.com/Azure/amqpnetlite) as the underlying AMQP 1.0 transport Protocol engine.
-### Overall Architecture
+## Overall Architecture
Apache-NMS-AMQP should bridge the familiar NMS concepts to AMQP protocol concepts as described in the document [amqp-bindmap-jms-v1.0-wd09.pdf](https://www.oasis-open.org/committees/download.php/60574/amqp-bindmap-jms-v1.0-wd09.pdf).
So in general most of the top level classes that implement the Apache.NMS interface _Connection, Session, MessageProducer,_ etc create, manage, and destroy the amqpnetlite equivalent object _Connection, Session, Link,_ etc.
-### Building With Visual Studio 2019
-There are multiple projects: Apache-NMS-AMQP, Apache-NMS-AMQP.Test, and HelloWorld. All projects use the new csproj format available in Visual Studio 2019.
-Apache-NMS-AMQP is the library which implements The Apache.NMS Interface using AmqpNetLite.
-Apache-NMS-AMQP.Test produces an NUnit dll for unit testing.
-HelloWorld is a sample application using the NMS library which can send messages to an AMQP Message Broker.
+## Getting started
+- [Configuration](docs/configuration.md) contains various uri options that can be set when defining a ConnectionFactory.
+- [Interested in the code?](docs/working_with_code.md) Clone and build the projects.
+- Want to contribute? Github pull requests are one way to contribute, but our real issue tracker is [JIRA](https://issues.apache.org/jira/issues/?jql=project%20%3D%20AMQNET%20AND%20component%20%3D%20AMQP).
-To build, launch Visual Studio 2019 with the nms-amqp.sln file and build the solution.
-Build artifacts will be under `<root_folder>\<project_folder>\bin\$(Configuration)\$(TargetFramework)`.
-
-### Building With DotNet SDK
-Alternatively, to build without Visual Studio 2019 the project can be built using [.NET Core sdk tool](https://www.microsoft.com/net/download/windows), version 2.2.+.
-Execute the dotnet sdk command to build all projects:
-```
-<root_folder>>dotnet build nms-amqp.sln
-```
-
-### Testing
-Tests use the NUnit Framework. The tests include both unit and system tests (require a broker).
-
-Apache-NMS-AMQP-Test contains only unit tests and doesn't require any configuration and dependencies.
-
-Apache-NMS-AMQP-Interop-Test contains system tests and require broker to be up and running. Broker can be configured either directly from the code (to do so you have to edit _AmqpTestSupport_ base class), or using environment variables:
-
-| Variable | Meaning |
-|----------|---------|
-|NMS_AMQP_TEST_URI|Broker uri|
-|NMS_AMQP_TEST_CU|Username|
-|NMS_AMQP_TEST_CPWD|Password|
-
-#### VS2019 Test Explorer
-Visual Studio 2019 will also run NUnit tests with the built-in TestExplorer tool.
-
-#### dotnet test
-
-If building with the dotnet sdk, From the top level directory simply enter _dotnet test_ to build and run all the tests. Individual tests can be run with:
-```
-dotnet test filter=<Test Name>
-```
-
-### Amqp Provider NMS Feature Support
+## Amqp Provider NMS Feature Support
| Feature | Supported | Comments |
|---------------|:---------:|:-----------------|
@@ -101,4 +72,4 @@
# Licensing
-This software is licensed under the terms you may find in the file named "LICENSE" in this directory.
+This software is licensed under the terms you may find in the file named "LICENSE" in this directory.
\ No newline at end of file
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..1c4d1e0
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,65 @@
+# Client configuration
+This file details various configuration options for the client, the syntax for its related configuration, and various uri options that can be set when defining a ConnectionFactory.
+
+## Connection Uri
+The basic format of the clients Connection URI is as follows:
+
+```
+amqp[s]://hostname:port[?option=value[&option2=value...]]
+```
+
+Where the amqps and scheme is specified to use SSL/TLS.
+
+The client can be configured with a number of different settings using the uri while defining the ConnectionFactory, these are detailed in the following sections.
+
+### NMS Configuration options
+The options apply to the behavior of the NMS objects such as Connection, Session, MessageConsumer and MessageProducer.
+
+- **nms.username** User name value used to authenticate the connection.
+- **nms.password** The password value used to authenticate the connection.
+- **nms.clientId** The ClientId value that is applied to the connection.
+- **nms.localMessageExpiry** Controls whether MessageConsumer instances will locally filter expired Messages or deliver them. By default this value is set to true and expired messages will be filtered.
+- **nms.sendTimeout** Timeout value that controls how long the client waits on completion of a synchronous message send before returning an error. By default the client will wait indefinitely for a send to complete.
+- **nms.requestTimeout** Timeout value that controls how long the client waits on completion of various synchronous interactions, such as opening a producer or consumer, before returning an error. Does not affect synchronous message sends. By default the client will wait indefinitely for a request to complete.
+- **nms.clientIdPrefix** Optional prefix value that is used for generated Client ID values when a new Connection is created for the JMS ConnectionFactory. The default prefix is 'ID:'.
+- **nms.connectionIdPrefix** Optional prefix value that is used for generated Connection ID values when a new Connection is created for the JMS ConnectionFactory. This connection ID is used when logging some information from the JMS Connection object so a configurable prefix can make breadcrumbing the logs easier. The default prefix is 'ID:'.
+
+### TCP Transport Configuration options
+When connected to a remote using plain TCP these options configure the behaviour of the underlying socket. These options are appended to the connection URI along with the other configuration options, for example:
+
+```
+amqp://localhost:5672?nms.clientId=foo&transport.receiveBufferSize=30000
+```
+
+The complete set of TCP Transport options is listed below:
+
+- **transport.sendBufferSize** Specifies the ReceiveBufferSize option of the TCP socket.
+- **transport.receiveBufferSize** Specifies the SendBufferSize option of the TCP socket.
+- **transport.receiveTimeout** Specifies the ReceiveTimeout option of the TCP socket.
+- **transport.sendTimeout** Specifies the SendTimeout option of the TCP socket.
+- **transport.tcpNoDelay** Specifies the NoDelay option of the TCP socket.
+
+### Failover Configuration options
+With failover enabled the client can reconnect to another server automatically when connection to the current server is lost for some reason. The failover URI is always initiated with the failover prefix and a list of URIs for the server(s) is contained inside a set of parentheses. The "nms." options are applied to the overall failover URI, outside the parentheses, and affect the NMS Connection object for its lifetime.
+
+The URI for failover looks something like the following:
+
+```
+failover:(amqp://host1:5672,amqp://host2:5672)?nms.clientId=foo&failover.maxReconnectAttempts=20
+```
+
+The individual broker details within the parentheses can use the "transport." or "amqp." options defined earlier, with these being applied as each host is connected to:
+
+```
+failover:(amqp://host1:5672?amqp.option=value,amqp://host2:5672?transport.option=value)?nms.clientId=foo
+```
+
+The complete set of configuration options for failover is listed below:
+
+- **failover.initialReconnectDelay** The amount of time the client will wait before the first attempt to reconnect to a remote peer. The default value is zero, meaning the first attempt happens immediately.
+- **failover.reconnectDelay** Controls the delay between successive reconnection attempts, defaults to 10 milliseconds. If the backoff option is not enabled this value remains constant.
+- **failover.maxReconnectDelay** The maximum time that the client will wait before attempting a reconnect. This value is only used when the backoff feature is enabled to ensure that the delay doesn't not grow too large. Defaults to 30 seconds as the max time between connect attempts.
+- **failover.useReconnectBackOff** Controls whether the time between reconnection attempts should grow based on a configured multiplier. This option defaults to true.
+- **failover.reconnectBackOffMultiplier** The multiplier used to grow the reconnection delay value, defaults to 2.0d.
+- **failover.maxReconnectAttempts** The number of reconnection attempts allowed before reporting the connection as failed to the client. The default is no limit or (-1).
+- **failover.startupMaxReconnectAttempts** For a client that has never connected to a remote peer before this option control how many attempts are made to connect before reporting the connection as failed. The default is to use the value of maxReconnectAttempts.
\ No newline at end of file
diff --git a/docs/working_with_code.md b/docs/working_with_code.md
new file mode 100644
index 0000000..70d7ec2
--- /dev/null
+++ b/docs/working_with_code.md
@@ -0,0 +1,36 @@
+# Prerequisites
+- Visual Studio 2019. [Community Edition](https://visualstudio.microsoft.com/downloads/) works.
+
+# Build the projects
+- Build with Visual Studio. Open apache-nms-amqp in Visual Studio. This solution contains both source code and test projects for all supported platforms. If the SDK of a particular platform is not present, the project will fail to load. You can either install the required SDK (if available) or remove the project(s) from solution.
+
+- Alternatively, to build without Visual Studio the solution can be built using [.NET Core SDK tool](https://www.microsoft.com/net/download/windows), version 2.2.+.
+
+Execute the dotnet sdk command to build all projects:
+```
+<root_folder>>dotnet build nms-amqp.sln
+```
+
+# Run the tests
+Tests use the NUnit Framework. The tests include both unit and system tests (require a broker).
+
+Apache-NMS-AMQP-Test contains only unit tests and doesn't require any configuration and dependencies.
+
+Apache-NMS-AMQP-Interop-Test contains system tests and require broker to be up and running. Broker can be configured either directly from the code (to do so you have to edit _AmqpTestSupport_ base class), or using environment variables:
+
+| Variable | Meaning |
+|----------|---------|
+|NMS_AMQP_TEST_URI|Broker uri|
+|NMS_AMQP_TEST_CU|Username|
+|NMS_AMQP_TEST_CPWD|Password|
+
+## Visual Studio Test Explorer
+Visual Studio 2019 will run NUnit tests with the built-in TestExplorer tool.
+
+## dotnet test
+
+If building with the dotnet sdk, from the top level directory simply enter _dotnet test_ to build and run all the tests. Individual tests can be run with:
+
+```
+dotnet test filter=<Test Name>
+```
\ No newline at end of file
diff --git a/test/Apache-NMS-AMQP-Test/ConnectionFactoryTest.cs b/test/Apache-NMS-AMQP-Test/ConnectionFactoryTest.cs
index b32fa4e..229b62a 100644
--- a/test/Apache-NMS-AMQP-Test/ConnectionFactoryTest.cs
+++ b/test/Apache-NMS-AMQP-Test/ConnectionFactoryTest.cs
@@ -76,7 +76,8 @@
"&nms.connectionIdPrefix=ID:TEST" +
"&nms.clientIDPrefix=clientId" +
"&nms.requestTimeout=1000" +
- "&nms.sendTimeout=1000";
+ "&nms.sendTimeout=1000" +
+ "&nms.localMessageExpiry=false";
NmsConnectionFactory factory = new NmsConnectionFactory(configured);
@@ -87,6 +88,7 @@
Assert.AreEqual("clientId", factory.ClientIdPrefix);
Assert.AreEqual(1000, factory.RequestTimeout);
Assert.AreEqual(1000, factory.SendTimeout);
+ Assert.IsFalse(factory.LocalMessageExpiry);
}
[Test]
