# Apache-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.

The key to enabling vendor independence and mass adoption of technology is to combine open source APIs and standard wireline protocols which is precisely what this  project is all about.  Here's how AMQP 1.0 support within NMS helps the .NET community:
 - __More Choice:__ As more message brokers and services implement the AMQP 1.0 standard wireline, .NET developers and architects will have more options for messaging technology.
 - __No Migration Risk:__ Since AMQP 1.0 is a wireline standard, you won't run into the problems that used to happen when switching between implementations.
 - __Innovation:__ Competition is a key component of technology innovation. Directly competitive messaging implementations, with seamless pluggability, forces vendors to innovate and differentiate.
 
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
Apache-NMS-AMQP uses [AmqpNetLite](https://github.com/Azure/amqpnetlite) as the underlying AMQP 1.0 transport Protocol engine. 

### 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 2017
There are multiple projects: Apache-NMS-AMQP, Apache-NMS-AMQP.Test, and HelloWorld. All projects use the new csproj format available in Visual Studio 2017.
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 2017 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 2017 the project can be built using [.NET Core sdk tool](https://www.microsoft.com/net/download/windows), version 2.1.+.
Execute the dotnet sdk command to build all projects :
```
C:\<root_folder>>dotnet build nms-amqp.sln 
```
__Note__ The .Net Framework SDK must be downloaded and installed to build the solution.  This means that the solution can only be built on a Windows platform.  The solution, nms-amqp.sln and the all the soure in this project is compatible with .NET Core.  The project files, _*.csproj_, can be modified to include the appropriate 'netcoreapp2.0'  or 'netstandard2.0' Framework in the target <TargetFrames> element. However as the NMS API does not have a .NET Core build, the dependency will produce the following warning:
 
```
Apache-NMS-AMQP.csproj : warning NU1701: Package 'Apache.NMS 1.7.1' was restored using '.NETFramework,Version=v4.6.1' instead of the project target framework '.NETStandard,Version=v2.0'. This package may not be fully compatible with your project.
```
The resulting DLL will __not__ run.

When a .NET Standard build of the NMS API is available, this project can be built
on any platform.

### Testing
Tests use the NUnit Framework.  The tests include both unit and system tests (require a broker).  The test configuration is read from 'TestSuite.config' in the current directory.  For convenience the build copies 'test/TestSuite.config' to the 'bin' directory.

The Apache-NMS-AMQP.Test project builds a NUnit 3.7.0 unit test dll to be used by NUnit console, 3.7.0 or 3.8.0.
To run the unit tests use the nunit3-console.exe under the `<nuget_packages_location>\nunit.consolerunner\3.7.0\tools\` folder. 
**Eg:**
```
C:\Users\me\nms-amqp\test\bin\Debug\net452> nunit3-console.exe NMS.AMQP.Test.dll
```
#### Configuring ActiveMQ

The distributed 'TestSuite.config' expects to connect using a plain text socket to the broker at 127.0.0.1:5672.  Secure connections are configured at 127.0.0.1:5671.  More information on secure connections can be found in _test/config/cert/ReadMe.md_.

#### VS2017 Test Explorer
Visual Studio 2017 will also run nunit tests with the built-in TestExplorer tool. If you wish to run tests inside VS2017 (useful for debugging) then you must configure _Test->Test Settings->Select Test Settings File_.  The *Test Settings File* is _test/config/Adapter.runsettings_.  

The file _Adapter.runsettings_ must be modified to reflect your local directory 
structure.

#### 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

| Feature       | Supported | Comments         |
|---------------|:---------:|:-----------------|
| TLS/SSL       | Y | Configuration is supported using transport properties. |
| Client Certificate Authentication | Y | Configuration is supported using transport properties. |
| Transactions (AcknowledgementMode.Transactional) | N | Session will throw NotSupportedException should a session's AcknowledgeMode be set to Transactional. |
| Distributed Transactions (INetTxConnectionFactory, INetTxConnection, INetTxSession) | N | |
| AcknowledgementMode.AutoAcknowledge | Y | |
| AcknowledgementMode.DupsOkAcknowledge | Y | |
| AcknowledgementMode.ClientAcknowledge | Y | |
| AcknowledgementMode.IndividualAcknowledge | Y | |
| IObjectMessage | Y * | Amqp value object bodies and dotnet serializable object bodies are supported. Java serialized objects can not be read by by the provider and are not supported. |
| IBytesMessage | Y | |
| IStreamMessage | Y | |
| IMapMessage | Y | |
| ITextMessage | Y | |
| IMessage | Y | |
| IConnectionFactory | Y | |
| IConnection | Y | The ConnectionInterruptedListener event and the ConnectionResumedListener are not supported. |
| ProducerTransformerDelegate | N | Any member access should throw a NotSupportedException. |
| ConsumerTransformerDelegate | N | Any member access should throw a NotSupportedException. |
| ISession | Y | Note all methods and events related to AcknowledgementMode.Transactional are not supported and should throw a NotSupportedException. |
| IQueue | Y | |
| ITopic | Y | |
| ITemporaryQueue | Y | |
| ITemporaryTopic | Y | |
| IMessageProducer | Y * | Anonymous producers are only supported on connections with the ANONYMOUS-RELAY capability. |
| MsgDeliveryMode.Persistent | Y | Producers will block on send until an outcome is received or will timeout after waiting the RequestTimeout timespan amount. Exceptions may be throw depending on the outcome or if the producer times out. |
| MsgDeliveryMode.NonPersistent | Y | Producers will not block on send nor expect to receive an outcome. Should an exception be raised from the outcome the exception will be delivered using the the connection ExceptionListener. |
| IMessageConsumer | Y * | Message Selectors and noLocal filter are not supported. |
| Durable Consumers | Y | |
| IQueueBrowser | N | The provider will throw NotImplementedException for the ISession create methods. |
| Configurable NMSMessageID and amqp serializtion | N | For future consideration. The prodiver will generate a MessageID from a sequence and serialize it as a string. |
| Flow control configuration | N | For future consideration. The provider will use amqpnetlite defaults except for initial link credits which is 200. |
| Object Deserialization Policy | N | For future consideration. The provider considers all Dotnet serialized objects in Object Message bodies are safe to deserialize. |

# Licensing 

This software is licensed under the terms you may find in the file named "LICENSE" in this directory.