Background
We (my coworkers and I) are architecting a high level C# API to interact with a hardware device's native Windows DLL.
First I will discuss the hardware-architecture, then get to the software-architecture part.
Main Device
The device has the following components:
-
Exactly 10 receive channels
-
Exactly 4 transmission channels
Receive Channels
There can only the exact specified number of receive channels on the device per the hardware specification (no more no less). The receive channels keep their own buffers as well as various getters/setters for their internal hardware configurations.
I have decided to declare the channels as a public 10 element array inside the "main device" class, for the following reasons:
- Whenever new data is received we check the addresses on all channels in the "main device" to know which channel the received data is intended for. This is currently done in a foreach loop which is nice and clean.
- When assigning the properties of the channels I can do so easily by using a foreach loop (again, provides cleanness).
- Need to access the actual object, not just return an instance of the object.
Transmit Channels
I have decided to declare the channels as a public 4 element array inside the "main device" class, for the same reasons as the receive channels.
Problem
- The channels are publicly exposed.
- As one of my colleagues has asked, "what if someone enters an invalid index into the array?"
Question
Is the array the proper way of going about this? Is there another way? I am looking for some suggestions on the general architecture.
Reminder: I need to access the channel objects directly, however we go about it.
Best Answer
I believe you should keep the amount of channels abstracted:
The amount of channels may vary in the future, e.g. hardware up/downgrade (new devices)
You may want to reserve some channels in the future, e.g. for out-of-band communications and notifications
The exactness should be kept and ensured in initialization.
You should expose the channels with the least specific type possible, such as
IEnumerable<ReceivingChannel>
andIEnumerable<TransmittingChannel>
.The
MainDevice
should expose a way to initialize or manage these collections, you have several non-exclusive options:Perhaps throw an exception (e.g.
InvalidOperationException
) in case you use these methods after the object has been first used by actual worker methods. Or better yet, have these methods in a builder class, where you finally callGetDevice
which will create and initialize the device, possibly with dependency injection (I will not discuss DI here.)Methods
AddReceivingChannel
,RemoveReceivingChannel
,AddTransmittingChannel
,RemoveTransmittingChannel
GetReceivingChannels
returningIEnumerable<IReceivingChannel>
, or a similarReceivingChannels
propertyGetTransmittingChannels
returningIEnumerable<ITransmittingChannel>
, or a similarTransmittingChannels
propertyGetReceivingChannelById
,GetReceivingChannelByAddress
,GetTransmittingChannelById
,GetTransmittingChannelByAddress
Don't use settable properties, as that is asking for trouble. The
MainDevice
should be the only entity responsible for managing its actual composition.This way, you may start by using arrays or lists to store the channels, but switch to dictionaries or trees (e.g.
SortedDictionary<TKey, TValue>
) if accessing them by some key becomes a bottleneck. And the users ofMainDevice
are just as happy.You can define a base interface
IChannel
for the common things that all channels do, such as opening and/or closing with an optional timeout, and haveIReceivingChannel
andITransmittingChannel
hold the specific operations, such as receiving and transmitting with an optional timeout:In case you need to access some inner object from a channel, define specific interfaces on which you may use the
as
operator instead of the actual class. For instance, aIFrobberContainer
interface with aGetNativeFrobber
method (or similarNativeFrobber
property), which does not extendIReceivingChannel
.This way, any object can contain a frobber:
In case you have something extra to do with frobber channels, you can ask if the channel has a frobber using the
as
operator.With the new C# 6 null-conditional operator, you can do this:
instead of this:
By segregating these distinct aspects into interfaces, you make your actual objects more flexible, more easily replaceable and mockable (good for unit testing).
If you insist on having 10 receiving channels and 4 transmitting channels, then you probably shouldn't use collections, but conversely use very good names for 14 properties. For generic iteration, you can keep internal collections initialized once, to avoid obvious code repetition.
You should still use interfaces and document which ones each channel implements, instead of using actual classes as the types for these properties, to retain the replaceability benefits for refactoring, maintenance and testing purposes.