Cross-cutting Concepts

Content and Motivation

You should explain cross-cutting and ubiquitous rules of your system. arc42 calls them concepts: They often affect multiple building blocks and are relevant in several parts of the system and its implementation. Examples include:

• Rules for the usage of technologies and/or frameworks
• Implementation rules, design or architecture patterns used

8.1 Domain Model

Properties of the implementation classes are private, as we manipulate these via getter/setter methods.

8.2 Structure of HTML Links

Remark: For many web developers or HTML experts the following information on URI syntax might be completely evident. As we wrote this book also for different kind of people, we included this information anyhow.

HtmlSC performs various checks on HTML links (hyperlinks), which usually follow the URI syntax specified by RFC-2396. URIs are generally used to link to arbitrary resources (documents, files or parts within documents).

Their general structure is depicted in the following figure - you also find a unit test below.

Test showing generic URI syntax

@Test
public void testGenericURISyntax() {
    // based upon an example from the Oracle(tm) Java tutorial:
    // https://docs.oracle.com/javase/tutorial/networking/urls/urlInfo.html
    def aURL = new URL(
        "https://example.com:42/docs/tutorial/index.html?name=aim42#INTRO");
    aURL.with {
        assert getProtocol() == "http"
        assert getAuthority() == "example.com:42"
        assert getHost() == "example.com"
        assert getPort() == 42
        assert getPath() == "/docs/tutorial/index.html"
        assert getQuery() == "name=aim42"
        assert getRef() == "INTRO"
    }
}

8.3 Multiple Checking algorithms

HtmlSC uses the template-method-pattern to enable flexible checking algorithms:

“The Template Method defines a skeleton of an algorithm in an operation, and defers some steps to subclasses”.

We achieve that by defining the skeleton of the checking algorithm in one operation (performCheck), deferring the specific checking algorithm steps to subclasses. The invariant steps are implemented in the abstract base class, while the variant checking algorithms have to be provided by the subclasses.

Template method for performing a single type of checks

/**
  * Prerequisite: pageToCheck has been successfully parsed,
  * prior to constructing this Checker instance.
**/
public CheckingResultsCollector performCheck() {
    // assert prerequisite
    assert pageToCheck != null
    initResults()
    return check() // subclass executes the actual checking algorithm
}

8.4 Reporting

HtmlSC supports the following output (== reporting) formats and destinations:

• formats (HTML and text) and
• destinations (file and console)

The reporting subsystem uses the template method pattern to allow different output formats (e.g. Console and HTML). The overall structure of reports is always the same.

The (generic and abstract) reporting is implemented in the abstract Reporter class as follows:

Report findings using TemplateMethod pattern

/**
 * main entry point for reporting - to be called when a report is requested
 * Uses template-method to delegate concrete implementations to subclasses
*/
    public void reportFindings() {
        initReport()            // (1)
        reportOverallSummary()  // (2)
        reportAllPages()        // (3)
        closeReport()           // (4)
    }

    private void reportAllPages() {
        pageResults.each { pageResult ->
            reportPageSummary( pageResult )                    // (5)
            pageResult.singleCheckResults.each { resultForOneCheck ->
               reportSingleCheckSummary( resultForOneCheck )  // (6)
               reportSingleCheckDetails( resultForOneCheck )  // (7)  
               reportPageFooter()                             
        }
    }

1. initialize the report, e.g. create and open the file, copy css-, javascript and image files.

2. create the overall summary, with the overall success percentage and a list of all checked pages with their success rate.

3. iterate over all pages

4. write report footer - in HTML report also create back-to-top-link

5. for a single page, report the number of checks and problems plus the success rate

6. for every singleCheck on that page, report a summary and

7. all detailed findings for a singleCheck.

8. for every checked page, create a footer, page break or similar to graphically distinguish pages between each other.

The sample report below illustrates this.