Showing Software Architectures in 2+1 Views with UML

  • How can I show & explain an application or service architecture?
  • How can I draw “correct” (and what does that mean?) UML diagrams?

Let me show you how I document smallish software systems with, typically, no more than four UML diagrams. We’ll cover the questions, what is worth diagramming? and what can I do with these diagrams anyway? and we’ll cover enough UML to be useful.

I will use the example of developing a “lead generation” website, which should be simple enough to not get bogged down, but complex enough to answer some of the but how do I …? questions that more complex systems raise.

Why Diagrams?

Use diagrams as starting point to discuss, describe and explain your system. A diagram can give an instant overview of some aspect of the system. It can show important relationships on a single sheet of paper. It can raise important questions and show design decisions.

Why UML?

The UML is a visual modelling language. It has a vocabulary and grammar for diagramming software such that the diagram is a precise statement. So it can be used to show and explain software architecture.

The UML is the only diagramming standard left standing (with, perhaps, one exception that we’ll see later). You may be tempted to compete in this uncrowded field of standards for software diagrams. I comment only that the UML contains several decades of work by several thoughtful people and if you can produce a usable standard that is simpler, quicker to learn, and not unhelpfully imprecise, then I shall be impressed.

You may also be tempted — as many, many of your colleagues have been — to just do without a standard. I hope these few examples will persuade you that learning a standard is less work than you fear and more useful than you expect.

Why 2+1 views?

The UML tells you how to diagram once you’ve decided what to diagram. “2+1” is a minimal decision about what to diagram. It suggests a couple of diagrams for the logical view of your software and one for the physical view (we’ll explain what those words mean, too). That’s the 2. But it starts with the 1, which is the context.

The System Context: Shown with a UML Use Case Diagram

Always start with context. Always start with simple.

The context diagram should make sense to your non-technical customer and can be so simple you wouldn’t even give it a second glance. It shows:

  • Who and what will use the system
  • What the system will do
  • Who and what the system will rely on

In the UML, anyone or anything who uses the system, or is relied on by the system to do its thing, is an Actor. What the system will do is a UseCase. A UseCase is a instance of the system being used to do something. It is shown on a diagram just by its name, which is a single descriptive phrase, in an ellipse.

  • Anything inside the box is what the system does.
  • Anything outside the box is the context of the system.

How to Use a Context / Use Case Diagram?

Use the diagram to discuss scope, expectations and dependencies with the system’s customers and with the development team who will build it. Its simplicity and brevity should also clarify what is not (or not yet) expected of the system. Like user stories, the brevity calls for conversation to clarify. Complex Use Cases call for detailed careful business analysis too, but that is done with words, not pictures.

For your developers, this diagram is the high level overview of what they’re delivering — everything inside the box — and what the system will need for it to work — everything outside the box.

I really like having a “hand drawn” look when first showing diagrams, because it says “work in progress” and invites participation. A precisely drawn diagram risks the impression of being a final decision.

I try to draw diagrams to be read from top left to bottom right. So I put “active” Actors—the users—on the left, and “dependency” actors on the right. That’s not a part of UML, but it’s part of how I will talk through the diagram.

Here’s the same diagram later on on the project. In phase two, we’re giving visitors SMS feedback, and adding a whole new bit of functionality to read events from the customer service team and integrate then with web analytics.

Use Case diagram with several use cases, 2 user actors and 5 machine actors.


What if you have lots of use cases? Don’t put more on one diagram than you can usefully discuss in a single session. Pick out the main use cases & those that show the main external dependencies (which probably means, the ones that pose the highest risk to your project). Optionally, have a second diagram for all use cases, but only if you have an audience for it.

UML Definitions

There are 3 things you need to know for this diagram:

Actor, UseCase, and Subject aka System Boundary

Here are their definitions, which I’ve abbreviated from the UML 2.5 spec, section 18 Use Cases.

UseCases are a means to capture the requirements of systems, i.e., what systems are supposed to do. The key concepts specified in this clause are Actors, UseCases, and subjects. Each UseCase’s subject represents a system under consideration to which the UseCase applies. Users and any other systems that may interact with a subject are represented as Actors.

A UseCase is a specification of behavior. An instance of a UseCase refers to an occurrence of the emergent behavior that conforms to the corresponding UseCase. Such instances are often described by Interactions.

An Actor models a type of role played by an entity that interacts with the subjects of its associated UseCases (e.g., by exchanging signals and data). Actors may represent roles played by human users, external hardware, or other systems.

NOTE. An Actor does not necessarily represent a specific physical entity but instead a particular role of some entity that is relevant to the specification of its associated UseCases. Thus, a single physical instance may play the role of several different Actors and, conversely, a given Actor may be played by multiple different instances.

NOTE. The term “role” is used informally here and does not imply any technical definition of that term found elsewhere in this specification.

A UseCase is shown as an ellipse, either containing the name of the UseCase or with the name of the UseCase placed below the ellipse. An optional stereotype keyword may be placed above the name.

A subject for a set of UseCases (sometimes called a system boundary) may be shown as a rectangle with its name in the top-left corner, with the UseCase ellipses visually located inside this rectangle.

An Actor is represented by a “stick man” icon with the name of the Actor in the vicinity (usually above or below) the icon. An Actor may also be shown as a Classifier rectangle with the keyword «actor»

Other icons that convey the kind of Actor may also be used to denote an Actor, such as using a separate icon for non- human Actors.


The spec: https://www.omg.org/spec/UML

I have used 3 more UML features to add explanations:

  • A Comment is “a textual annotation that can be attached to a set of Elements”. A Comment is shown as a rectangle with the upper right corner bent (this is also known as a “note symbol”). The rectangle contains the body of the Comment. The connection to each annotatedElement is shown by a separate dashed line. The dashed line connecting the note symbol to the annotatedElement(s) may be suppressed if it is clear from the context, or not important in this diagram.
  • A Dependency “implies that the semantics of the clients are not complete without the suppliers”. A Dependency is shown as a dashed arrow between two model Elements. The model Element at the tail of the arrow (the client) depends on the model Element at the arrowhead (the supplier) .
  • InformationFlows “describe circulation of information through a system in a general manner. They do not specify the nature of the information, mechanisms by which it is conveyed, sequences of exchange or any control conditions”. An InformationFlow is represented using the same notation as Dependency , with the keyword «flow» adorning its dashed line.

HowTo: Linux, Nginx, Mono, Asp.Net Mvc

These are notes I made for getting an application written for Asp.Net Mvc (It was probably Mvc 3-ish) to run on a Centos server.

Note that some of the issues/solutions may vary across Linux variants. The interface Nginx-Mono is FastCGI, which they both support. The Mono webserver is xsp4.

Of course, running cross platform is all much easier these days if you use .Net Core and Kestrel 🙂 And een for Net Framework running on Mono, the work done since Microsoft bought Xamarin has been really helpful for e.g. Mvc compatibility.

The Reading List

The Checklist

Ensure nginx has read execute permissions on your application directory and all parent directories

nginx conf section for webapp

With the Asp.Net website listening on port 9001

#
server {
listen 8080;
server_name your-public-facing-nginx-server-name.com;

# use /smoketest/ to confirm that nginx is reading this config 
# and has read/execute access to the 
# /usr/share/nginx directories and files:

location /smoketest/ {
root /usr/share/nginx/smoketestredir;
index index.html;
}

# pass XSP to FastCGI server listening on 127.0.0.1:9001
# use a different port for each ASP.NET site you create
# (port 9000 is often taken by PHP on default webserver setups)

location / {

# replace fastcgi with this to confirm nginx read address
# to files in root /usr/share/nginx/mywebapplication;
fastcgi_pass  127.0.0.1:9001;
fastcgi_index index.html;

include /etc/nginx/fastcgi_params;
fastcgi_param  PATH_INFO          "";
fastcgi_param  SCRIPT_FILENAME    $document_root$fastcgi_script_name;

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
}
}

Systemd Startup Script

vim /etc/systemd/system/fastcgi-mono-hdmbreas.service

[Unit]
Description=FastCgi-mono-server4 for Application
After=syslog.target

[Service]
Type=simple
ExecStart=/bin/fastcgi-mono-server4 --applications /:/usr/share/nginx/hdmbreas/hdm-fe-web --socket=tcp:127.0.0.1:9001
Restart=always

systemctl daemon-reload
systemctl start fastcgi-mono-app.service
systemctl status fastcgi-mono-app.service
systemctl status fastcgi-mono-app.service

Error: [error] 7216#0: *119 upstream sent too big header while reading response header

  • Considering setting the buffer size
  • Considering setting the busy buffer size
  • e.g. nginx config: fastcgi_buffers 16 16k; fastcgi_buffer_size 32k;

Watching Errors

Watch errors with tail -F /var/log/nginx/error.log

Should a method name describe what it does or what it intends?

Bob Martin raises a good example in InformIT: Robert C. Martin’s Clean Code Tip of the Week #1: An Accidental Doppelgänger in Ruby > Duplication of two functions that do the same thing but mean different things by it.

I recently stumbled into a slightly different take on the question of should a function say what it does or what it intends?

When a  function implements business process Alpha that today consists of steps A and B (but tomorrow  may change) should you call the function DoBusinessProcessAlpha or call it DoStepsAandB?

One answer would be, if the function is in a public package which exposes business functionality then the name should probably show that it does BusinessProcessAlpha. But if it is a private, not exposed, function then the reader is probably looking for the detail, that it does StepsAandB.

The question is more awkward if Steps A and B are themselves business process functions. That is, if you asked your customer, they would understand what steps A and B mean.

I suppose in that case you could always call it DoAlphaAsStepsAandB().

Default timeouts in .Net code. What are they if you don’t specify?

What are the default timeouts in .Net code if you don’t specify one? I realised I didn’t know, when I got timeouts for an HttpClient calling a WCF service calling a SQL query. The choices are all reasonable. But they’re all different. So here’s a list.

System.Net.Http.HttpClient

.Timeout Default 100 seconds
The entire time to wait for the request to complete.
https://docs.microsoft.com/en-us/dotnet/api/system.net.http.httpclient.timeout?view=netframework-4.5 (if your url requires a DNS call and you set timeout < 15 seconds, your timeout may be ineffective; it may still take up to 15 seconds to timeout.)

System.Data.SqlClient SqlConnection & SqlCommand

SqlConnection.ConnectionTimeout Default 15 seconds

The timeout to wait for a connection to open.
https://docs.microsoft.com/en-us/dotnet/api/system.data.sqlclient.sqlconnection.connectiontimeout?view=netframework-1.1

SqlCommand.CommandTimeout Default 30 seconds

The wait time before terminating the attempt to execute a command and generating an error.

https://docs.microsoft.com/en-us/dotnet/api/system.data.sqlclient.sqlcommand.commandtimeout?view=netframework-1.1

Remarks & Notes

  • A value of 0 indicates no limit (an attempt to execute a command will wait indefinitely).
  • The CommandTimeout property will be ignored during asynchronous method calls such as BeginExecuteReader.
  • CommandTimeout has no effect when the command is executed against a context connection (a SqlConnection opened with “context connection=true” in the connection string).
  • This is the cumulative time-out (for all network packets that are read during the invocation of a method) for all network reads during command execution or processing of the results. A time-out can still occur after the first row is returned, and does not include user processing time, only network read time. For example, with a 30 second time out, if Read requires two network packets, then it has 30 seconds to read both network packets. If you call Read again, it will have another 30 seconds to read any data that it requires.

WCF

IDefaultCommunicationTimeouts

This interface does not, of course, set any default values, but it does define the meaning of the four main timeouts applicable to WCF.

System.ServiceModel.Channels.Binding Default values

Remember, timeouts in WCF apply at the level of the Binding used by the client or service. (Think about it. It makes sense).

So the Binding class defaults affect all your WCF operations unless a specific binding subclass changes it. Subclasses include: BasicHttpBinding, WebHttpBinding, WSDualHttpBinding, all other HttpBindings, all MsmqBindings, NetNamedPipeBinding, NetPeerTcpBinding, NetTcpBinding, UdpBinding, and CustomBindings.
https://docs.microsoft.com/en-us/dotnet/api/system.servicemodel.channels.binding?view=netframework-3.0

The defaults are:
OpenTimeout 1 minute
CloseTimeout 1 minute
SendTimeout 1 minute
ReceiveTimeout 10 minutes

However whilst some bindings – basicHtp, netTcp– specify the same—1 min, 1min, 1min, 10 minutes—as Binding base class …

WCF Service Timeouts for webHttpBinding, wsDualHttpBinding and other bindings

The documentation for these bindings contradict (or should I say, override) the documentation for the framework classes and say that all four timeouts, including ReceiveTimeout, default to 1 minute. It could be a typo, I haven’t tested. See all the various bindings at https://docs.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/wcf/bindings.

webHttpBinding vs basicHttpBinding Reminder:
webHttpBinding is for simple (so-called rest-style) HTTP requests as opposed to Soap. basicHttpBinding is for SOAP, i.e.conforming to the WS-I Basic Profile 1.1.

WCF Client Timeouts

A WCF client uses three of these Timeout settings. Since the default value is set by the Binding, what remains is to clarify the definitions.

  • SendTimeout : used to initialize the OperationTimeout, which governs the whole process of sending a message, including receiving a reply message for a request/reply service operation. This timeout also applies when sending reply messages from a callback contract method.
  • OpenTimeout – used when opening channels
  • CloseTimeout – used when closing channels
    ReceiveTimeout is meaningless for a client and is not used.

https://docs.microsoft.com/en-us/dotnet/framework/wcf/feature-details/configuring-timeout-values-on-a-binding

WCF Serverside Timeouts

A WCF service uses all four Timeout settings. Three have the same definition as a WCF Client. The fourth is:

WCF using a Binding with reliableSession

Some System.ServiceModel.Bindings allow the use of ReliableSession behaviour, which adds another timeout:

InactivityTimeout defaults to 10 minutes.

https://docs.microsoft.com/en-us/dotnet/api/system.servicemodel.channels.reliablesessionbindingelement.inactivitytimeout?view=netframework-3.0.

Remarks

  • Activity on a channel is defined as receiving an application or infrastructure message. The inactivity timeout parameter controls the maximum amount of time to keep an inactive session alive. If more than InactivityTimeout time interval passes with no activity, the session is aborted by the infrastructure and the channel faults. The reliable session is torn down unilaterally.
  • If the sending application has no messages to send then the reliable session is normally not faulted because of inactivity; instead a keep-alive mechanism keeps the session active indefinitely. Note that the dispatcher can independently abort the reliable session if no application messages are sent or received. Thus, the inactivity timeout typically expires if network conditions are such that no messages are received or if there is a failure on the sender.

but:

WCF Server using HttpBinding with reliableSession implemented as Connection: Keep-Alive HTTP header

https://social.msdn.microsoft.com/Forums/vstudio/en-US/d8a883dc-c47d-4912-b23b-2dfd0c2557cb/wcf-server-side-timeout?forum=wcf

BasicHttpBinding does not use any kind of session so receiveTimeout should be irrelevant.
BasicHttpBinding can use HTTP persistent connection. Persistance is provided by Connection: Keep-Alive HTTP header which allows sharing single TCP connection for many HTTP requests/responses. There appears to be no way to change the timeout associated with this header, and IIS appears to always timeout at 100 seconds of inactivity. IIS’s keep-alive default timeout value is 120s, but changing this seems to have no effect on the WCF service.

The interesting thing is that closing proxy/channel on the client side does not close the TCP connection. The connection is still opened and prepared to be used by another proxy to the same service. The connection closes when 100s inactivity timeout expires or when application is terminated. Btw. there is RFC which defines that max. two such TCP connections can exists between client and single server (this is default behavior in windows but can be changed).

You can turn off HTTP persistent connection if you implement cutomBinding and set keepAliveEnabled=”false” in httpTransport element. This will force client to create new TCP connection for each HTTP request.

IIS Timeouts

https://docs.microsoft.com/en-us/iis/configuration/system.applicationhost/weblimits

connectionTimeout: Default 2 minutes.

Specifies the time (in seconds) that IIS waits before it disconnects a connection that is considered inactive. Connections can be considered inactive for the following reasons:

  • The HTTP.sys Timer_ConnectionIdle timer expired. The connection expired and remains idle.
  • The HTTP.sys Timer_EntityBody timer expired. The connection expired before the request entity body arrived. When it is clear that a request has an entity body, the HTTP API turns on the Timer_EntityBody timer. Initially, the limit of this timer is set to the connectionTimeout value. Each time another data indication is received on this request, the HTTP API resets the timer to give the connection more minutes as specified in the connectionTimeout attribute.
  • The HTTP.sys Timer_AppPool timer expired. The connection expired because a request waited too long in an application pool queue for a server application to dequeue and process it. This time-out duration is connectionTimeout.

headerWaitTimeout : Default 0 seconds
ToDo: Does this mean none, or does it mean no timeout until the connectionTimeout is hit?

IIS Asp.Net HttpRuntime

executionTimeout: 110 seconds in .Net framework 2.0 & 4.x. In the .NET Framework 1.0 and 1.1, the default is 90 seconds

IIS WebSockets

pingInterval: default is 0 seconds.

IIS Classic Asp

queueTimeout : default value is 0.
The maximum period of time (hh:mm:ss) that an ASP request can wait in the request queue.

scriptTimeout : default value is 1 minute 30 seconds
The maximum period of time that ASP pages allow a script to run run before terminating the script and writing an event to the Windows Event Log.

IIS FastCGI

https://docs.microsoft.com/en-us/iis/configuration/system.webserver/fastcgi/application/index

activityTimeout: The default value in IIS 7.0 is 30seconds ; the default for IIS 7.5 is 70 seconds.
The maximum time, in seconds, that a FastCGI process can take to process.

idleTimeout: default 300 seconds.
The maximum amount of time, in seconds, that a FastCGI process can be idle before the process is shut down

requestTimeout: default 90 seconds
The maximum time, in seconds, that a FastCGI process request can take.

Http Server 408 Request Timeout

https://tools.ietf.org/html/rfc7231#section-6.5.7

The 408 (Request Timeout) status code indicates that the server did not receive a complete request message within the time that it was prepared to wait. A server SHOULD send the “close” connection option (Section 6.1 of [RFC7230]) in the response, since 408 implies that the server has decided to close the connection rather than continue waiting. If the client has an outstanding request in transit, the client MAY repeat that request on a new connection.

See Also