Introducing UDP AdapterContestant

Hello

This article follows up on the question I had asked the community UDP Adapter not working

In this article, I will present to you
1) What is "UDP"?
2) The current state of Iris with UDP
3) My solution with the UDP adapter

1) What is "UDP"?

UDP stands for User Datagram Protocol. It is one of the core protocols of the Internet Protocol (IP) suite, used for transmitting data over a network. Here are some key features of UDP:

1. Connectionless: UDP does not establish a connection before sending data, which means it can send messages (datagrams) without prior handshaking.
2. Unreliable: There is no guarantee that messages sent via UDP will arrive at their destination. There is no error recovery or retransmission of lost packets.
3. Speed: Because it is connectionless and does not require error checking or correction, UDP is generally faster than TCP (Transmission Control Protocol), making it suitable for applications where speed is critical.
4. Datagram-oriented: UDP sends messages as discrete packets, which can be of varying lengths. Each packet is treated independently.
5. Use Cases: UDP is commonly used in applications where speed is more critical than reliability, such as video streaming, online gaming, voice over IP (VoIP), and real-time communications.

Overall, UDP is a lightweight protocol that is useful for specific applications where low latency is essential.

2) The current state of Iris with UDP

Of course, InterSystems Iris allows to use this protocol to send and receive data.
As REST protocol, there are two ways to do it :
- with the ##class(%Net.UDP).%New().
- with the EnsLib.UDP.OutboundAdapter and EnsLib.UDP.InboundAdapter

##class(%Net.UDP).%New()

Even if the documentation of the class is very complete, here is the link of the InterSystems documentation on how to use it.

To send/receive data with it, we use an instance of class(%Net.UDP).%New() and some method linked to it.
In summary, to send data (on localhost with port 3001) :

SET client = ##class(%Net.UDP).%New()
SET addrbin = ##class(%Net.UDP).GetHostAddr("127.0.0.1")
Set status = client.Send("message text", addrbin, 3001)

To receive data (on localhost with port 3001) :

Set sobj = ##class(%Net.UDP).%New(3001,"127.0.0.1")
Set data = sobj.Recv()

EnsLib.UDP.OutboundAdapter and EnsLib.UDP.InboundAdapter

This one is simpler : it is an adapter.
Here the documentation : EnsLib.UDP.OutboundAdapter et EnsLib.UDP.InboundAdapter
To send data :

Set status = ..Adapter.SendStream(stream)

To receive data :

Set status = ..Adapter.Receive(stream)

However, it doesn't work. I asked the community with my issue "UDP Adapter not working" and created a ticket to the WRC.
They replied this :

The underlying executable has not been installed anymore in the product since Ensemble 2018.1.

I checked internally and JIRA DP-437486 was submitted to update those adapters to use the %Net.UDP class, but this will be subject to product management approval and available development resources.

Unfortunately, the only option right now is to create your own custom adapter using the %Net.UDP class.

The two main differences between the class(%Net.UDP) and the EnsLib.UDP.OutboundAdapter  are

• The %Net.UDP class uses the $System.UDP system class, so it uses Cache/IRIS kernel code to send/receive the UDP messages, while the UDP Adapter uses a command pipe to call external executables to send/receive the UDP message.
• The %Net.UDP class sends/reads a string while the UDP adapter uses a stream to send/read messages.

3) My solution with the UDP adapter

So, I wrote my own (approved by the support) to send data :
 

/// Adapter to send data with UDP Connection
Class USER.UDP.OutboundAdapter Extends Ens.Adapter
{

/// Host of the UDP server
Property Host As %String [ Required ];
/// Port of the UDP server
Property Port As %Integer [ Required ];
/// if 1, show the text that will be sent
Property UDPTrace As %Integer(VALUELIST = ",0,1") [ InitialExpression = 0, Required ];
Parameter SETTINGS = "Host:Basic,Port:Basic,UDPTrace:Basic";
/// Send "text" throught the UDP connection
Method SendDataText(text As %String) As %Status
{
    Try {
        Set status = $$$OK
        If ..UDPTrace=1
        {
            Do ..ShowText(text)
        }
        
        Set udpClient = ##class(%Net.UDP).%New()
        Set addrbin = ##class(%Net.UDP).GetHostAddr(..Host)

        Set sentBytes = udpClient.Send(text, addrbin, ..Port)
    }
    Catch exception {
        Set status = exception.AsStatus()
    }    
    Return status
}

/// Convert "stream" into text and send it throught the UDP connection
Method SendDataStream(stream As %Stream.Object) As %Status
{
    Try {
        Do stream.Rewind()
        Set text = ""
        While 'stream.AtEnd{
            Set text = text _ stream.Read()
        }

        Set status = ..SendDataText(text)
    }
    Catch exception {
        Set status = exception.AsStatus()
    }    
    Return status
}

/// Convert "object" into json and send it throught the UDP connection
Method SendDataJSONObject(object As %RegisteredObject, format As %String = "iw") As %Status
{
    Try {
        Set status = ##class(%ZEN.Auxiliary.jsonProvider).%WriteJSONStreamFromObject(.stream,object,,,,format)
        $$$ThrowOnError(status)
        
        Set status = ..SendDataStream(stream)
    }
    Catch exception {
        Set status = exception.AsStatus()
    }    
    Return status
}

/// Takes a text as input,
/// Displays the traces of the associated object
Method ShowText(text As %String)
{
    Set nbParty = $SYSTEM.SQL.CEILING($LENGTH(text)/1100)
    For ii=1:1:nbParty
    {
        $$$TRACE($EXTRACT(text,ii,ii+1100))
    }
}

}

I hope this article was, if not helpful, interesting.

I haven't tested the EnsLib.UDP.InboundAdapter, so feel free to add more informations in the discussion.

Corentin