Model Xtractor provides one of the most consistent representations of built-in arrays and collection types, through multiple associations. Both the arrays and the types identified as collections can be considered utility classes and automatically bypassed in diagrams (their shapes being minimized). The idea is simple: as long as a method returns an array or collection of elements, we are most often interested in the elements returned, not in the container holding those elements. And if we want to access the container as well, it’s nothing easier then to restore it to its regular size.
Arrays
.NET arrays are built-in types, dynamically constructed and instantiated. They may depend internally on the System.Array class, but a FileInfo[ ] array, for example, has no equivalent in a well-declared standalone type. It is rather virtually built by combining the FileInfo type instances in a generic array type. Model Xtractor dynamically creates and adds to a diagram such virtual arrays, whenever an expanded association item returns a type followed by [ ], like our GetDrives, GetDirectories and GetFiles members below:
The [ ] small shapes are automatically minimized shapes for the built-in array types. Each such array has an <<elements>> dependency item, also automatically expanded, that points to the element type. For the FileInfo[ ] array this would be the FileInfo type. The <<elements>> dependency shows a multiple association, and an aggregation of composition (depending on the kind of items – objects or structures – the array holds).
Here is the same model, but with the array shapes displayed like the rest. Arrays are considered primitive types in .NET, so their shape title color is green:
Collections
Model Xtractor determines at metadata import time which types act as “collections”. In Metadata browser, when you show member return types, collection types will also appear with a [*] suffix. It is a same when such a return type appears in a shape item’s signature. For .NET, types are identified as collections if they are, implement or inherit from IEnumerable or IEnumerable<T>, or another collection class. IList, ICollection, IEnumerable are all collection interfaces, and CollectionBase is a collection class. If we cannot determine the actual type of inner elements, we use System.Object for the <elements>> dependency.
Just like the arrays, collection shapes are automatically minimized when association items get expanded, and their <<elements>> dependency is auto-expanded as well. In the diagram below, EventLog.GetEventLogs has been expanded like before, through a EventLog[ ] array. But the Entries property returns a type identified by Model Xtractor as collection, so it gets minimized:
All collection shapes get a blue border. Restore both the array and collection shapes:
The sole purpose of EventLogEntryCollection is indeed to hold a collection of EventLogEntry objects. With the shape minimized, we bypassed it and better represented rather the multiple association between EventLog and EventLogEntry. This is: an EventLog returns a collection of EventLogEntry objects. What kind of container holds these objects is usually of less interest.
The difference between arrays and collections is collections are well-defined specific types. Arrays are more generic and dynamically built-in.
Generic Collection Types
Lets take a look at a more complex collection and see what Model Xtractor can do for you. If you expand Peer.PeerEndPoints from the image below into a new diagram, it will nicely appear as a collection of PeerEndPoint elements, passing through a minimized collection shape (blue border). Lets restore and take a closer look at the collection class:
PeerEndPointCollection inherits from the dynamic type Collection<PeerEndPoint>, which is a template substitution of Collection<T>. All are collections, but only for first two we can determine a precise element type: PeerEndPoint. Model Xtractor dependency can expand into relationships in any direction, so we can quickly investigate the whole complexity of this model and offer in the same time simplified different views.
Another interesting case is presented below. The MailAddressCollection collection class inherits from Collection<MailAddress>, which is a compile-time dynamic template substitution of the Collection<T> generic type. Both “elements” and “param” dependencies return a MailAddress type:
Single and Multiple Results
No function, in any programming language, receives multiple values in a parameter or returns multiple values. Yes, type members can return arrays or collections of objects, but we’re still talking here about one single object at a time, and in this case this is either the array instance or the collection type instance (not their inner elements!). To get to the actual elements, we use loops (for, foreach, while, do) and we still access the elements as well one at a time, at any moment. This is why, for maximum accuracy, any multiple association will appear in Model Xtractor as two different connectors, passing through an array or collection shape: first connector actually returns the container, through a typical single-cardinality association, the second is a multiple virtual association to its inner elements.
Those diagram models that simplify the multiplicity problem, by simply adding multiple arrows at one end of the connector, and going directly to the element class, will also bypass the actual container (the actual instance returned by that member). Same models that do not automatically recognize the collection types make things harder, because the user will have to determine by himself which kind of elements the container holds. Model Xtractor is the best of all worlds: (1) we do not simply omit the dynamic arrays (just because they do not translate into specific well-defined classes). And (2) we automatically detect types used as collections and their element types. What’s more, with the minimized shapes, we reach the elements, bypassing the containers, but in a consistent, accurate and clean way.
Avoid confusion regarding the term “array”. In most programming languages, this is a rather compiler-dependent type, virtual and dynamic, not an API-dependent well-defined type. .NET defines also a System.Array type, but this is rather a well-defined type (identified by Model Xtractor as collection type as well), not what we called before an “array”. System.Array holds Object elements, but it is not the same as the Object[ ] array.
To make things more confusing, it’s said any dynamic array is actually using the System.Array type. When C# introduced generics, System.Array has been extended with template members. It’s unfortunate however there is no Array<T> generic in .NET (with most methods translated easily from System.Array), because any T[ ] could have been easily interpreted as alias for that class: System.Array would have become Array<Object>, and for FileInfo[ ] we would have had the equivalent type Array<FileInfo>.
Leave a Comment