activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From michaelpea...@apache.org
Subject [activemq-nms-amqp] branch master updated: NO-JIRA: Update docs
Date Sun, 22 Sep 2019 20:56:53 GMT
This is an automated email from the ASF dual-hosted git repository.

michaelpearce pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/activemq-nms-amqp.git


The following commit(s) were added to refs/heads/master by this push:
     new 1e595e6  NO-JIRA: Update docs
     new cfdd097  Merge pull request #33 from Havret/update_docs
1e595e6 is described below

commit 1e595e680fb4711a0a9e7fde6041286f953bb32f
Author: Havret <h4vret@gmail.com>
AuthorDate: Wed Sep 18 23:38:12 2019 +0200

    NO-JIRA: Update docs
---
 README.md                                          | 59 +++++---------------
 docs/configuration.md                              | 65 ++++++++++++++++++++++
 docs/working_with_code.md                          | 36 ++++++++++++
 test/Apache-NMS-AMQP-Test/ConnectionFactoryTest.cs |  4 +-
 4 files changed, 119 insertions(+), 45 deletions(-)

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
 
-[![Build Status](https://travis-ci.org/apache/activemq-nms-amqp.svg?branch=master)](https://travis-ci.org/apache/activemq-nms-amqp)
+## Build Status
 
-### Overview
+OS | Status
+---|---
+Linux | [![Build Status](https://travis-ci.org/apache/activemq-nms-amqp.svg?branch=master)](https://travis-ci.org/apache/activemq-nms-amqp)
+Windows | [![Build status](https://ci.appveyor.com/api/projects/status/yn2wkhq1nbhkfsur?svg=true)](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 in [...]
 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 @@ The key to enabling vendor independence and mass adoption of technology
is to co
 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.
-
-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>
-```
+## 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).
 
-### Amqp Provider NMS Feature Support
+## Amqp Provider NMS Feature Support
 
 | Feature       | Supported | Comments         |
 |---------------|:---------:|:-----------------|
@@ -101,4 +72,4 @@ dotnet test filter=<Test Name>
 
 # 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 @@ namespace NMS.AMQP.Test
                                 "&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 @@ namespace NMS.AMQP.Test
             Assert.AreEqual("clientId", factory.ClientIdPrefix);
             Assert.AreEqual(1000, factory.RequestTimeout);
             Assert.AreEqual(1000, factory.SendTimeout);
+            Assert.IsFalse(factory.LocalMessageExpiry);
         }
 
         [Test]


Mime
View raw message