From ec8fe87c8dfa16bf0814c625e55849ab83947d98 Mon Sep 17 00:00:00 2001 From: Scott Fauerbach Date: Wed, 10 Jul 2024 15:39:56 -0400 Subject: [PATCH] Encoded connections are no longer supported (#908) --- README.md | 123 -------------------------- src/NATS.Client/ConnectionFactory.cs | 3 + src/NATS.Client/EncodedConn.cs | 4 +- src/NATS.Client/IEncodedConnection.cs | 1 + 4 files changed, 7 insertions(+), 124 deletions(-) diff --git a/README.md b/README.md index fba313129..bbe1b9b36 100755 --- a/README.md +++ b/README.md @@ -287,129 +287,6 @@ instead of `NATS.RX.Ops`. See the full example here: [RxSample](src/Samples/RxSample/RxSample.cs) -## Basic Encoded Usage -The .NET NATS client mirrors go encoding through serialization and -deserialization. Simply create an encoded connection and publish -objects, and receive objects through an asynchronous subscription using -the encoded message event handler. The .NET 4.6 client has a default formatter -serializing objects using the BinaryFormatter, but methods used to serialize and deserialize -objects can be overridden. The NATS core version does not have serialization -defaults and they must be specified. - -```c# -using (IEncodedConnection c = new ConnectionFactory().CreateEncodedConnection()) -{ - EventHandler eh = (sender, args) => - { - // Here, obj is an instance of the object published to - // this subscriber. Retrieve it through the - // ReceivedObject property of the arguments. - MyObject obj = (MyObject)args.ReceivedObject; - - System.Console.WriteLine("Company: " + obj.Company); - }; - - // Subscribe using the encoded message event handler - IAsyncSubscription s = c.SubscribeAsync("foo", eh); - - MyObject obj = new MyObject(); - obj.Company = "MyCompany"; - - // To publish an instance of your object, simply - // call the IEncodedConnection publish API and pass - // your object. - c.Publish("foo", obj); - c.Flush(); -} -``` - -### Other Types of Serialization -Optionally, one can override serialization. Depending on the level of support or -third party packages used, objects can be serialized to JSON, SOAP, or a custom -scheme. XML was chosen as the example here as it is natively supported by .NET 4.6. - -```c# -// Example XML serialization. -byte[] serializeToXML(Object obj) -{ - MemoryStream ms = new MemoryStream(); - XmlSerializer x = new XmlSerializer(((SerializationTestObj)obj).GetType()); - - x.Serialize(ms, obj); - - byte[] content = new byte[ms.Position]; - Array.Copy(ms.GetBuffer(), content, ms.Position); - - return content; -} - -Object deserializeFromXML(byte[] data) -{ - XmlSerializer x = new XmlSerializer(new SerializationTestObj().GetType()); - MemoryStream ms = new MemoryStream(data); - return x.Deserialize(ms); -} - -<...> - -// Create an encoded connection and override the OnSerialize and -// OnDeserialize delegates. -IEncodedConnection c = new ConnectionFactory().CreateEncodedConnection(); -c.OnDeserialize = deserializeFromXML; -c.OnSerialize = serializeToXML; - -// From here on, the connection will use the custom delegates -// for serialization. -``` - -One can also use `Data Contract` to serialize objects. Below are simple example -overrides that work with .NET core: - -```c# -[DataContract] -public class JsonObject -{ - [DataMember] - public string Value = ""; -} - -internal object jsonDeserializer(byte[] buffer) -{ - using (MemoryStream stream = new MemoryStream()) - { - var serializer = new DataContractJsonSerializer(typeof(JsonObject)); - stream.Write(buffer, 0, buffer.Length); - stream.Position = 0; - return serializer.ReadObject(stream); - } -} - -internal byte[] jsonSerializer(object obj) -{ - if (obj == null) - return null; - - var serializer = new DataContractJsonSerializer(typeof(JsonObject)); - - using (MemoryStream stream = new MemoryStream()) - { - serializer.WriteObject(stream, obj); - return stream.ToArray(); - } -} - -<...> - -// Create an encoded connection and override the OnSerialize and -// OnDeserialize delegates. -IEncodedConnection c = new ConnectionFactory().CreateEncodedConnection(); -c.OnDeserialize = jsonDeserializer; -c.OnSerialize = jsonSerializer; - -// From here on, the connection will use the custom delegates -// for serialization. -``` - ## Wildcard Subscriptions The `*` wildcard matches any token, at any level of the subject: diff --git a/src/NATS.Client/ConnectionFactory.cs b/src/NATS.Client/ConnectionFactory.cs index b4577cb38..d27713129 100644 --- a/src/NATS.Client/ConnectionFactory.cs +++ b/src/NATS.Client/ConnectionFactory.cs @@ -225,6 +225,7 @@ public IConnection CreateConnection(Options opts, bool reconnectOnConnect = fals } /// + /// ENCODED CONNECTIONS, WHILE STILL FUNCTIONAL, WILL NO LONGER BE SUPPORTED /// Attempt to connect to the NATS server, with an encoded connection, using the default options. /// /// if true, the connection will treat the initial connection as any other and attempt reconnects on failure @@ -241,6 +242,7 @@ public IEncodedConnection CreateEncodedConnection(bool reconnectOnConnect = fals } /// + /// ENCODED CONNECTIONS, WHILE STILL FUNCTIONAL, WILL NO LONGER BE SUPPORTED /// Attempt to connect to the NATS server, with an encoded connection, referenced by . /// /// @@ -262,6 +264,7 @@ public IEncodedConnection CreateEncodedConnection(string url, bool reconnectOnCo } /// + /// ENCODED CONNECTIONS, WHILE STILL FUNCTIONAL, WILL NO LONGER BE SUPPORTED /// Attempt to connect to the NATS server, with an encoded connection, using the given options. /// /// The NATS client options to use for this connection. diff --git a/src/NATS.Client/EncodedConn.cs b/src/NATS.Client/EncodedConn.cs index 4903de0c0..e5e934aef 100644 --- a/src/NATS.Client/EncodedConn.cs +++ b/src/NATS.Client/EncodedConn.cs @@ -38,6 +38,7 @@ namespace NATS.Client public delegate Object Deserializer(byte[] data); /// + /// ENCODED CONNECTIONS, WHILE STILL FUNCTIONAL, WILL NO LONGER BE SUPPORTED /// Provides decoded messages received by subscriptions or requests. /// public class EncodedMessageEventArgs : EventArgs @@ -89,7 +90,8 @@ public Msg Message } /// - /// Represents an which uses a client specified + /// ENCODED CONNECTIONS, WHILE STILL FUNCTIONAL, WILL NO LONGER BE SUPPORTED + /// Represents a which uses a client specified /// encoding scheme. /// public class EncodedConnection : Connection, IEncodedConnection diff --git a/src/NATS.Client/IEncodedConnection.cs b/src/NATS.Client/IEncodedConnection.cs index a7cfa48be..d11949b1f 100644 --- a/src/NATS.Client/IEncodedConnection.cs +++ b/src/NATS.Client/IEncodedConnection.cs @@ -17,6 +17,7 @@ namespace NATS.Client { /// + /// ENCODED CONNECTIONS, WHILE STILL FUNCTIONAL, WILL NO LONGER BE SUPPORTED /// Represents a connection to a NATS Server which uses a client specified /// encoding scheme. ///