Q.

1 Explain the working of Table module and discuss its characteristics and applicability, citing any business application.

Solution: Data is usually bundled in the form of table (Data Set) A dataset (or data set) is a collection of data, usually presented in tabular form Each column of data set represents a particular variable Each row corresponds to a given member of the dataset in question. The value at the intersection of row & column is the instance value of the variables in data set, such as height of an object and weight of an object. Each value is known as a datum The dataset may comprise data for one or more members, corresponding to the number of rows Table Module is designed to work with a Record Set (508). Revenue Recognition in Table module

Advantages

1. 2.

Table Module (125) easily fits into a bigger architecture / implementing domain logic Table Module is suitable pattern to work in GUI environments, which can work directly on the results of a SQL query organized in a Record Set (508)

3.

Since Table Module (125) can work on a Record Set (508), a query can be easily run to manipulate the results in the Table Module (125) and pass the manipulated data to the GUI for display.

4.

Table Module (125) facilitates validations and calculations over a DataSet. A number of platforms, particularly Microsoft's COM and .NET, use this style of development. Disadvantage Table Module (125) does not work well with fine grained structure of the logic, e.g. inheritance, strategies, and other OO patterns Domain Model and Table Module Compared Though Table Module (125) looks like a Domain Model (116) However, the vital difference is Domain Model (116) One instance of contract for each contract in the database Table Module (125) Will have one instance of data set of all contracts having at least one common attribute Revenue recognition Operation

The revenue recognition method will

operate on each contract instance Domain model does not get data as a bundle of the record set but only gets data in the form of single row instance for manipulation

will be performed on recordset/DataSet Table Module will receive data as bundle of the record set in the form of set of rows

Table Module (125) may be viewed as super solution over Transaction Script (110) and a Domain Model (116). Developing/Organizing domain logic with Table Module instead Transaction Scripts gives a structured approach Table Module (125) facilitates finding and removing duplicates o Table Module (125) is preferable to work around with Record Set (508). In a Visual Studio and .NET environment Table Module pattern works very well as they provide lots of tools for implementation o In case, domain logic requires handling of record set, Table Module (125) supports the Record Set (508) structure Definition: Table Module is a single instance that handles the business logic for all rows in a database table or view

Table Module employs concept of object orientation providing bundled data for a method to manipulate (operate) Domain Model (116) on the other hand provides traditional objectoriented approach to manipulate data. Example For an Employee class, instance corresponds to a particular employee With reference to this employee instance, one can execute all operations that follow relationships with employee to gather data on the employee

One of the problems with Domain Model is the interface with relational databases

Considerable programming efforts are required to pull from and place data in the database. The effort basically aim at transforming the data between two different representations (relational and OO).

In Table Module, logic is organized to form one class per table in the database, and this single instance of the class contains various procedures that will act on the data set. How Table Module Works

Table Module provides behaviour and data packaged together such that the capabilities of a relational database are also placed together for operations

Assuming that table module is working with employee object, every time some manipulation is to be done to a particular employee, some kind of identity reference has to be passed (e.g. identifying the employee with primary key used in the database).

Table Module works well with table oriented database structure

The tabular data will be generated with a SQL call and the data will be returned and held in a Record Set (508) that mimics SQL table.

Table Module gives an explicit method-based interface that acts on set of data. The most obvious example of Table Module is use of one instance for each table in the database Often a complex problem will require behaviour from multiple Table Modules for the useful work. These Multiple Table Modules may be operating on the same Record Set (508) (Fig 9.4 Not in notes)

For different queries and views on the database(s) one may have different Table Modules corresponding to each of them. Table Module may be implemented as an instance or may be a collection (set) of static methods Advantage of Table Module instance Table Module can be initialized with an existing record set. The Table Module instance may also be used to manipulate the rows in the record set.

Q.2 Data Mapper maps the business objects to data source. In this context, explain/discuss/draw the following: (a) The business process complexity and the concept behind Data mapper to resolve this complexity. (b) Explain the working of Data mapper with a sequence diagram for querying or retrieving data from database. (c) Diagram of Data Mapper Architecture.

Solution:

Revisiting Domain Model Domain Model is a layer of objects that abstracts the real world logic, data, and problems that application deals with Some books classify the Domain Model in two broad categories: Simple Domain Model and

A Rich Domain Model A Simple Domain Model tends to have a one-to-one correspondence between business objects and database tables A Rich Domain Model includes

Complex /tangled web of tightly interwoven objects Uses inheritance Will leverage many of the design patterns

Rich Domain Models tends to be tightly coupled with the business needs Patterns like Active Record, RDG, TDG and Data Mapper are the database-related design patterns that provide organizing databaserelated logic into a Domain Model

As the domain logic gets more complicated the Transaction script

pattern get discarded and the architecture moves towards a rich Domain Model.

With complicated domain logic, simple approach of Active

associated with rich Domain Model also breaks down. to-one match between domain classes to tables fails

Record

Moreover, when domain logic is factored into smaller classes, one Furthermore, as the domain logic gets more complex, developers

like to test it without having to talk to the database all the time. How is the Problem Resolved?

Solution to problem:

1. Total isolation: Eliminate direct interaction between domain model and database 2. Appropriate Mapping: Suitably Map the domain objects and database tables

Data Mapper (Fig 3.4) handles

loading and storing between the database and the domain objects associated with Domain Model

This option (amongst all 4) is the most complicated, but provides

major benefit of complete isolation of the two layers

See

fig 3.4 Not in notes Data mapper isolating domain objects from database Data Mapper Revisited (From Chapter 10) Definition: It is a Layer of Mappers That moves data between domain objects and a database While keeping them independent of each other and The mapper itself

Problems with growing Business Complexity

Attributes in Domain Objects and rows in RDBMS have different mechanisms of data structuring. Domain objects may have many variants of data structuring: E.g. Collections and inheritance are not present in relational databases

Object model is built with lots of business logic that uses these variable mechanisms to organize variables and the behaviour in domain object

Object model also generate varied object schemas that do not match the relational schema. Complexity grows when data is to be transferred from variant schemas to and fro. Changes in any of the schema (Object or Relational) sends ripples the other on account of data transfer from in-memory objects to the relational database structure. Solution to the Problem

Data Mapper introduces a layer of software that separates the in-memory objects from the relational database Data Mappers responsibility is

1. 2.

To isolate the domain object layer and data source layer To transfer data between the two layers

With the introduction of Data Mapper concept the in-memory objects are not even required to know

1. 2.

Whether there is a database present; Requirement of any SQL interface code,

3.

The knowledge of the database schema.

On the other hand, since the mapping is done by Mapper (473), Data Mapper itself may not know the existence of domain layer. How Data Mapper Works

Separation between domain objects and data source is the main

function of a Data Mapper.

Consider a simple case of Person class and Person Mapper class. To load a person object from the database, 1. Client will call find method, with the method argument, on the mapper (Figure 10.3 not in notes) 2. Mapper uses an Identity Map to see if the person is already loaded in memory a. If loaded, maps data to object b. If not, requests DB with the SELECT argument

Example 1: Loading data from database

3. Loads Result Set in to mapper 4. Maps Data to domain object Example 2: Updating data into database

To Update the data in DB

1. Client will request the mapper to save a domain object 2. Mapper pulls the data out of the domain object and shuttles it to the database See Fig 10.4 Not in notes Updating data in database with data mapper

Notice that with ease Data Mapper layer 1. Can be substituted, either for testing purposes or 2. Can allow a single domain layer to work with different databases

Mappers need a variety of strategies to handle

Classes that have multiple fields, Classes that have multiple tables Classes that have to provide inheritance

Placing Data Mapper

Data Mapper will have dependency from the Domain Model object an upward dependency Data Mapper is also required to be coupled to the SQL for interfacing with database (e.g. java.sql package) A conflict on placing the Data Mapper

This is resolved through implementing RDG/TDG

Q.3 Domain layer has to manage with typical behavioral problem of loading and saving the objects to database. What are these behavioral problems? With reference to this statement, discuss the following behavioral patterns. a. Identity pattern b. Unit of work pattern c. Lazy load pattern

Solution: The Behavioural Problem (From Ch 03) Behavioural problem deals with loading, updating and saving the objects to the database. Example: Customer object can have load and save methods in it that can do this task Active Record (160) can be an obvious route. When bunch of objects are required to be loaded into memory, updated /modified, a need arises to track each object (grouped or ungrouped) for modification and ensuring that all of these are written back to the database Writing smaller number of objects is easy. Loading many objects is a tricky exercise, particularly when some new rows are created and some are only modified

Keys would be required for new rows or even for modification Once the objects are in Memory, isolation of these objects is critical: This is to ensure that no other process changes any of the loaded objects that have been read while you're working on them Before writing the objects back, consistency of database state has to be maintained / retained. Any inconsistency will render the data invalid in the objects. The issue of concurrency is a very tricky problem to solve.

Behaviour Patterns and their role on OO Model

1. 2. 3. 4.

Facilitate Mapping of In-memory objects to disk objects

Manage and work with large structures of inter-connected in memory objects Provide OO database control on moving objects to/from disk

Provide Grouping of Transactions between objects for linked updates and maintaining consistency and hence the necessity of sharing of data store

5.

Provide virtual availability of infinite transactional memory seen by the programmers, that facilitates updates( requires sharing of data store)

6. 7.

Advantage: improved productivity Disadvantage:

a. b. c.

Functional aspects at risk Control of grouped objects becomes complex Large memory requirement etc

O/R Mapping Focuses on the structural aspectsrelating to objects and tables table Hardest part of the exercise is mapping of following to relational Architectural aspects and Behavioural aspects Architectural aspects are managed within 1. Transaction Script 2. Domain Model and 3. Table Module Tools used for architectural mapping is in association with database, would be done through JDO, ADO.Net Using O/R Mapping patterns

Mapping Terminology Mapping (v). Act of determining how objects and their relationships are

persisted in permanent data storage (RDBMS) Mapping (n). Defines how an objects property or a relationship is persisted in permanent storage. Property. A data attribute, either implemented as a physical attribute such as the string firstName or as a virtual attribute implemented via an operation such as getTotal() which returns the total of an order Property mapping. A mapping that describes how to persist an objects property. Relationship mapping. A mapping that describes how to persist a relationship (association, aggregation, or composition) between two or more objects A simple Data Mapper will map a database table to an equivalent in-memory class on a field-to-field basis

As domain logic (for business) becomes complex, Mappers become

complex and will have to implement variety of mapping strategies Mapping implementation strategy should cover: 1. 2. Mapping in-Memory objects having multiple fields, Mapping in-Memory objects to multiple tables,

3. Mapping Classes and their sub-classes with inheritance to single/multiple tables 4. Mapping connected objects

Above mentioned strategies are implemented with O/R Mapping patterns in conjunction with Data Mapper O/R Mapping patterns provide variety of alternatives to implement aforesaid strategies,

Data Mapper (From Chapter 10) and its association with Object Relational Behaviour Pattern 1. Identity Map (195) Pattern Its role is to maintain a record of every row that is loaded in the memory each time. Domain logic will first go through this record maintained by Identity Map (195), and Identify whether that the object / row is already not loaded This eliminates initiating call to data source. Identity map thus,

Facilitates coordination of updates. Further, a call to database to load the object is avoided

Net effect is improving the performance (Since the Identity Map (195) also doubles as a cache for the databaserecording what has been loaded in memory).

The primary purpose of an Identity Map (195) is to maintain correct identities and not to boost performance. Development in Domain Model (116), will usually arrange loading of linked objects together

Example: Read for an order object loads its associated customer object. However, with many objects connected together any read of any object can pull an enormous object graph out of the database 2. Unit of Work pattern assists in Managing Transactions When inserts and updates are to be executed into database, the mapping layer has to understand (keep the track of)

1. 2. 3.

What objects have changed, Which new ones have been created, and Which ones have been destroyed

In order to maintain ACID characteristics, the mapper has to fit the whole workload (insert /update) into a transactional framework Unit of Work pattern facilitates in keeping track of the objects as discussed above, thus organize these objects Essentially resolves these two problems of tracking and consistency and more:

1. 2. 3. 4.

Maintaining track of modifications, new records once loaded / created in the memory Maintaining the consistency

Handles how updates are made to the database and saves application programmer invoking explicit save methods Facilitates programmer to COMMIT ( save )

5.

Facilitating sequencing of all behaviours to the database, during COMMIT, the putting the entire complex commit processing in one place Unit of Work (184) can be thought as an object that acts as the controller of the database mapping. In the absence of Unit of Work (184), domain layer will have to act as the controller; deciding when to read and write to the database. A care is required on loading an object more than once. Having an object in memory twice or more, for a single database row for an UPDATE will render the data invalid, besides creating confusion 3. Managing lots of Data with Lazy load Pattern A find method will rarely result into a single SQL query sending a single request to get the results Example: Finding orders for a product would typically load multiple order lines A request from client would obviously require loading of multiple objects in memory Mapper designer has to decide exactly how much to pull back in one go Pulling in (loading) enormous linked objects in memory can create inefficiencies. Designer would like to load objects in parts as required, retaining the reference intact. Lazy Load (200) provides a placeholder for a reference to an object. There are several variations in implementation of Lazy load Theme, but all of them have the object reference modified so that, instead of pointing to the real object, it marks a placeholder

Using Lazy Load (200) at suitable points, one can control just enough loading from the database with each call. Necessity of controlling the dataflow into memory: Clients query pattern on the objects must be well understood as the data to be pulled will be impacted by the nature of query. This can be done by: 1. 2. 3. 4. Analyzing queries Grouping common queries Minimizing database queries, Design of better finders

Making best choices of queries and finders can minimize the pulling of data. Most difficult and complicated task in query design is: Designing a single SQL query that joins the order with multiple order lines and pulls exact data (order lines) from database and upload it in multiple domain objects with appropriate mapping Care in pulling connected Objects: Often objects are interconnected in domain layer and therefore, a care has to be taken while pulling the data in memory, from connected objects Lazy Load Pattern (200) will generally be useful for the mapping layers by using the techniques for dealing with pulling data Revisiting Data Mapper Managing Multiple Data Mappers

Many Data mappers: An application may have one Data Mapper or several data mappers In case Data Mapper is being hand-coded (no off the shelf tools), the best approach is to use

1. 2.

One mapper for each domain class OR Map with Root of a domain hierarchy.

Using Metadata Mapping Pattern: In case multiple Data mappers are required to be used, the better approach would be to use Metadata Mapping (306) for defining each class

Managing Finder Classes with Multiple Data Mappers is a critical design issue When to Use Data Mapper

Data Mapper's primary benefit is working with domain model Data Mapper will be deployed when Database schema and the object model have evolved
independently.

Domain model is to be tested without involving database

Domain objects are required to interact amongst themselves for implementing business logic without understanding the database structure In case Domain Model or Database has to undergo frequent modification independently without having to alter either. This is aspect is valuable, while handling complicated mappings, particularly those involving existing databases.

Higher business complexity leads to complicated logic Which leads to implementation in Complex Domain Model and Therefore need of Data Mapper.

Note that there is an extra price to be paid for developing additional data mapper layer When not to have Data Mapper: With fairly simple business logic, one may not even have Domain Model (116) or a Data Mapper as Active Record would do the job

No point having data mapper,

1. 2. 3. 4.

If the domain model is pretty simple, and The database is under control of domain model

Domain objects can access the database directly with Active Record Mapper has to interact with transaction script, or table module In most of the development, buying a database-mapping layer rather than building would be the best approach Example: A Simple Database Mapper (Java) See Fig 10.5 not in notes implementing Data Mapper Using Data Source access Patterns Revisiting Ch 03)

Data Source access Patterns aren't entirely mutually exclusive.

Choosing of the access pattern, the basic aim is implementing a

persistence mechanism to save data from in-memory model to the database,

Using

a combination can cause problems, messing up everything.

Even if Data Mapper is used as primary persistence mechanism, use of Gateway is recommended to wrap tables or services that are being treated as external interfaces.

 These patterns not only work with "table

with views

but can equally work

Updating

is complicated with views and queries, as one cannot update a view directly but instead has to manipulate the underlying tables.

One may encapsulate the view/query with an appropriate pattern and implementing the update logic will not only simplify the use of views but will keep it reliable.

Using these patterns with

views and queries can lead to problem of inconsistencies as updates are to be performed on two or more different structures

While using data source patterns always look for

1. 2. 3.

Use of OODB Use of O/R mapping tools, Use of Data Mapper Tools

Q.4 Write notes on following: a. Input controller pattern b. Working of Page Controller with help of class diagram c. Working of Front Controller with help of class diagram

Solution: Input Controller pattern Input controller has two responsibilities

1. 2.

Handling HTTP request and Deciding on how to resolve this request

Two variants of Input Controller: Page Controller Front controller

Recall Figure of Application Controller on page 379 and see how it interacts with input controller- Figure not in notes Page Controller (From Ch 04) Simplest of the two and in its simplest form, it may be just a server page itself which combines the role of view and input control Called Page Controller because An Input Controller Object is created for each page accessed by the client on the web site / used to dispatch http request Precisely speaking there will be one Input Controller object created and associated for each action (button clicks and links) in the page. Button clicks are actions on the page while Links take the client on different page

Page Controller (From Ch 14) Figure of Page Controller class diagram on Page 333 Not in notes

Definition: An object that handles a request for a specific page or action on a Web site Sequence of Action 1. Client initiates request / action / clicks a link 2. Page controller object will receive the request string and also identify the specific page or action on a Web site 3. Initiate response from the web server, in the form of pages in either of the following way: a) A send static HTML page(s) or set of linked pages, which are the notionally maintained as separate document(s) on the Web site / Web server.

b)

Generate dynamic page(s), which will be more complex, as

it has to link up the file that responds, upload data from separate file and manage the response Note: To meet the response for each request, link request or button action, Page Controller will have one input controller for each logical page of the Web site How Page Controller Works Basic principle is to have one module (page controller object) per page to act as controller on the Web server for pages being sent to the client. Practically, one module per page may not be implementable as client may click a link, requesting different pages, depending upon dynamic information/some condition. Therefore, page controller object may not just be for each page a client visits but will be clubbed with set of action(s) or link(s) on the page. Page Controller may be structured either as A script CGI script, servlet, etc. Or As a server page (ASP, PHP, JSP, etc.).

In server page approach Page Controller is placed with Template view in the same file. However, if there is a logic placed in the template view, some design problems will have to be resolved.

Responsibility of page Controller is

1. 2. 3.

Decode the URL and extract any form data or button action to figure out the action(s) required. Create and invoke model objects if any, to process the

data.

Pass all relevant data from the HTML request to the Model so that the model objects don't need any connection to the HTML request.

4.

Determine which view has to be displayed and then send the model information to it When to Use Page Controller Important decision: Use Page Controller or Front Controller. Page Controller provides natural structuring mechanism, where particular actions are handled by particular server pages or script classes. Page Controller works well in a site where most of the controller logic is simple In this case the URLs would be handled by server page and complicated logic would be handled by call to helper objects Front Controller is complex to develop but provides advantages in handling navigation through pages Cost overheads of Front Controller are high, as opposed to page controller ( logic is simple to implement) Two patterns mix without too much trouble. Some web site implementations may have some requests dealt by Page Controllers and

others are dealt with by Front Controllers (when re-factoring is being done from one to another).

Example 1: Simple Display with a Servlet Controller and a JSP View (Java)

 The concept is to establish coupling between the Template View and the Page Controller and passing of parameter names to JSP in the request. Controller logic in the example is very simple, but with more complexity one can use the servlet as a controller.

Example 2: Using JSP as a Handler (Java)

Example 1 uses servlet as a controller. In example 2, server page itself has been made as controller

Front Controller (From Ch 04)

Unlike Page Controller which has one corresponding page controller object, Front Controller provides only one object - Front Controller object for handling varied /all requests This single Front Controller object also called Single Handler Single Handler Interprets the URL for twin purpose a) To figure out what kind of request its dealing with and then creates a separate object to process it b) Understand the nature of request and activate the views that would be required for rendering, post request processing

Front Controller (From Ch 14)

In a complex Web site there are many common similar things done in handling a request. These things mostly include 1. Security, 2. Internationalization, and 3. Providing particular views for certain users If the input controller behaviour is scattered across multiple objects, much of this behaviour will have duplicate code

Front Controller sequences the client request as under: 1. Consolidate all requests from the client, 2. Channelize these requests through a Single handler object 3. Handler object carries out common behaviour, which can be modified at runtime with decorators (Pattern) 4. Handler then dispatches the request to command objects for associating particular behavior to a specific request.

Class diagram on p344 not in notes

How Front Controller Works Handling the clients call on the Web site is usually structured in two parts: 1. Web handler and 2. Command hierarchy Working of Web handler Object

1. Web handler object receives

Web server.

post or get requests from the

2. 3.

Web handler extracts just enough information from the URL and the request Decide what kind of action is to be initiated and then delegates the action to be taken to a command to carry out the action associated with the clients request (Sequence diagram of web handler Fig 14.2 not in notes) Web handler is almost always implemented as a class and not as server page. Web Handler basically is a simple program that does nothing other than extracting request and deciding which command to run either statically or dynamically Web handler in ASP.NET is called page handler (*.aspx) and it is the default HTTP handler for all ASP.NET pages

Two ways to run the Command by Web Handler

1.

Static Web handling: Parse the URL

Use conditional logic to ... Advantage it uses explicit logic Facilitates compile time error checking, and dispatch, Provides lots of flexibility in looking into received URLs Dynamic Web handling: Takes the standard piece of URL Uses dynamic instantiation to create a command class

2.

Allows adding new commands without changing the Web handler Allows placing the name of the command class into the URL Alternatively allows use of properties file that can be bind URL to command class names Benefits of Dynamic web handling: 1. Front Controller can be associated with Decorator Pattern which wraps the handler with pipe line of filters that can check for logging, authentication, authorization etc before control is passed to Command 2. Dynamic setting up of filters at run time Web handler may also be implemented in two stages 1. First stage is to pull the basic data out of the http parameters and hands it over to Second stage 2. Second stage does the dispatch of extracted information to appropriate model. It is also called the dispatcher stage

Dispatcher Stage shown as delegation to Application Controller in JEE

When to Use Front Controller Front Controller is complicated design as compared to Page Controller. Effort is worth only if advantages are accrued Only Front Controller is required to be configured with web server, rest of the job is done by the web handler Advantages of Front Controller

1. 2. 3.

Provides a central access point for applications i.e. only one Front Controller has to be configured into the Web server and Web handler does the rest of the dispatching. Dynamic commands can be added to new commands without changing anything Creates an ideal location to initiate authentication and authorization

4. 5. 6. 7. 8.

Ensures code reuse and reduces the incidence of redundant code being used in several applications Provides common services required to process requests Does not restrict the number of controllers used for a solution With just one controller, one can easily enhance its behaviour at runtime with decorators

Can have decorators for authentication, character encoding, internationalization, and so forth, and add them using a configuration file or even while the server is running. Disadvantage:

1. 2.

The Front Controller is a complicated design as compared to Page Controller

Requires development time and resources Example: Simple Display (Java) Using Front Controller for displaying information about a recording artist with his original and innovative task The example uses a dynamic command with a URL of the form http://localhost:8080/isa/music?name=barelyWorks&command= Artist The command parameter indicates the Web handler which command to use. (See class diagram implementing Front Controller Fig 14.3 Figure not in notes) Comparison Criteria Page Controller Front Controller Complexity / Ease of 1. Low complexity.

Implementation

2. Suits simpler web applications. 3. Most commercial web application frameworks provide built-in support. Duplication will grow as application grows. Has to implement a BaseController from which all page controllers extend. Low. May require two part controller where one is HTTP dependant and the other is independent and testable. Since pages of the web application vary from each other, the code duplication may be higher. No extra bottleneck if plain page controller is used. However if a deep inheritance hierarchy is used performance can be a bit lower than normal.

1. Highly complex, compared to page controller. 2. The single controller itself can be complex. 3. Many CMS frameworks have this built in. Low code duplication. All common tasks can be put inside the front controller Front controller has only to handle transfer of the request to independent commands which could be testable Since the front controller is centralized it's highly configurable. The single front controller can end up being a bottleneck since it answers to all requests. Should avoid doing I/O or database calls in the front controller as much as possible. Front controller can instantiate new command objects for each request and ensure thread safety at

Code Duplication / Code quality

Testability

Adaptability/ Flexibility

Performance

Thread Safety

The same page controller instance might handle requests for the same page and threadsafety has to be considered.

(Depends on framework e.g.: Java / ASP.Net)

controller level. However model code still has to be thread-safe.

http://www.uchithar.net/2010/03/page-vs-front-controller.html

Q.5 Why Software documentation is important? Give your arguments in favor of its importance. Discuss the seven rules to be followed to maintain excellent set of Software documents in your organization.

Solution: P.1 Short Overview of Software Architecture Introduction Boxes, partitioned rectangles, arrows and line diagrams, lollipops and sockets are ubiquitously used to describes and decorate the system implementations. These must be used unambiguously Multiple software architectural views are essential for diverse stakeholders (users, acquirers, developers, testers, maintainers, interoperators etc) need to understand and use the architecture from their respective viewpoint. Therefore the views must be readable and discernable. Since all the stakeholders would be from the same organization, there is need to maintain consistency in the views created for these stakeholders.

 Software Architecture is Transformation of abstract model to an operational system and would contain many design decisions taken during implementation. Essential that all facts are recorded and documented. Architecture Documentation is similar to documentation of other facets of software development projects. As such, document development must follow some fundamental rules, standard notations etc. SA documentation would invariably be developed by groups of people. SA documentation should therefore be logically partitioned, sectionised prudently as a whole OR into parts, with specific relations among the parts The partitioning allows working amongst groups with cooperation and sync, thereby improving the productivity P.2 Overview of Architecture Documentation

A. Why Architecture documentation: Three Uses

1. Serves as a means of education: Introducing system to the people for education (Old or New) Education for external analysts, or even a new architect. Education to customer, prospective customer 2. Serves as a primary vehicle for communication among stakeholders. An architectures precise use as a communication vehicle depends on which type of stakeholders are communicating.

Stake Holders List Analyst, architect, business manager, conformance checker, customer, database administrator, deployer, designer evaluator, implementer, network administrator, integrator, project manager, system engineer, Tester, user

3. Serves as document / bench mark for system analysis and construction. Architecture tells implementers what to implement Provides design attributes and quality attributes Used as input for evaluation, as it contains the information necessary to evaluate a variety of attributes, such as security, performance, usability, availability, and modifiability For system builders who use automatic code-generation tools, the documentation may incorporate models used for code generation. B. Economics of Architecture Documentation

C. Managing the speed Architectural Changes faster than document development

Document development speed faster than Architecture Synchronizing is important P.3 Architecture Views

Software architecture is complex entity that cannot be described in a simple one-dimensional fashion

Documenting architecture is a matter of documenting the relevant views and then adding documentation that applies to more than one view.

RM ODP, 4+1 P.4 Architecture Styles

P.5 Seven Rules of Architecture documentation

Architecture documentation is much like writing Software Development Project. For sound documentation seven rules must be followed.

These rules can also be used as checklist for judging a documents quality and facilitate a structure for critical review.

Rule 1: Document must have Readers Point of View

The rule states to keep the end goal in mind as to who is the user of the document. Make sure that the document serves its stakeholders and meets the intended uses. Writing a document that a reader finds easy to use will help him/her understand even a complex system.

Document Author should identify the reader/ group of readers and understand their requirements. When reader(s) is new to the document or reader from a different company which does not use the same notation, a glossary may have to be added. Overuse of acronyms must be desisted. Rule 2: Avoid Unnecessary Repetition

Each kind of information should be recorded in exactly one place. This makes documentation easier to use and much easier to change as it evolves.

Placing information at multiple locations can create confusion: information that is repeated is likely to be in a slightly different form, and now the reader must wonder Was the difference intentional? If so, what is the meaning of the difference?

Change to information in one place in the document would require identical change at all the places and can create complications and hence the goal that information never be repeated.

Repeating information in SOME places for convenience, though at the cost of reader and more so because readers dont like to flip pages or click hyperlinks unnecessarily. The information may be repeated in two or more different places for clarity or to make different points.

Expressing the same idea in different forms is often useful for achieving a thorough understanding. If keeping the information separately comes at too high a cost to the reader, but can be disastrous if not repeated, repeat the information.

Documents maintained and viewed online, use of hyperlinks simplifies /eliminates duplication effort. For example, each term can be hyperlinked to its definition; a concept can be hyperlinked to an explanation or elaboration. Rule 3: Avoid Ambiguity

Ambiguity occurs when documentation can be interpreted in more than one way and at least one of those ways is incorrect. Undetected ambiguity is most dangerous. In case, the ambiguity persists, each reader will think he or she understands the document, but each reader is likely to come to a different conclusions.

Following two considerations will help in eliminating ambiguity:

By avoiding needless repetition (rule 2). Reviewing the document with intended audience

Use of standardized, defined notation with precise semantics can eliminate most of the linguistic ambiguity. Use of standard languages and notations facilitates elimination of ambiguity. However, use of formal language is not always necessary. Rule 3a: Explain Your Notation

The ubiquitous box-and-line diagrams drawn on whiteboards/ papers to explain systems and architecture are one of the greatest sources of ambiguity in architecture documentation.

These diagrams if not annotated correctly are certainly not good architecture documentation. Such diagrams suffer from ambiguity problems.

Boxes can be o modules, o classes, o clients, o databases, o functions, o procedures, o or something else. objects, services, servers, processes, tiers, processors,

Arrows can mean o calls, o data flow, o inheritance, uses, I/O, communication,

o Processor migration, or something else.

Reader should be able to determine the meaning of the notations/ symbols with ease. The best way to do this is always to include a key in the diagrams. Rule 4: Use Standard Organization for the document

Document should follow a standard, planned organization scheme. Give a preview of the same to the readers Benefits of standard organization of the document:

 Facilitates the document writer /author to plan and organize the contents. The template provides an outline of the important topics to cover. It allows the writer to record information as soon as its known, e.g. pieces of section 4 may be written ahead of sections 3 3. Template reveals the work done and To Be Done (TBD) and labeled as TBD (to be determined) or To Do. Embodies completeness of the information, in the document and its sections and subsections. Facilitates validation check at different stages e.g. Document at review time Testing Verification of development process Corollaries to this rule of Standard Organization:

1. Organize documentation for ease of reference.\ Software document is likely to be referenced hundreds or thousands of times, till a new software stabilizes or at the time of update, upgrade, modifications or error detection. Provide reference to find information quickly. Adding table of contents, index, glossary, acronym lists are good ways to help readers to look up specific information 2. Dont leave any section blank; mark it as TBD or NA,what you know is not applicable.

Rule 5: Record Rationale

Architecture is the result of making a set of important design decisions, and architecture documentation records the outcomes of those decisions. Reasoning for the most important decisions should be recorded.

In case the decision has been made out of several options, record the important or most likely alternatives that have been rejected and state why. Later, when those decisions come under scrutiny or pressure to change, you will find yourself revisiting the same arguments and wondering why you didnt take another path.

Recording your rationale will save you enormous time in the long run, although it requires discipline to record your rationale in the heat of the moment. A design decision is key to achieve a quality requirement of the system; its rationale is worth capturing. A decision arrived after long meeting with stakeholders, is worth capturing. Decisions / conclusions taken after conducting technical experiments and studies or after creation of prototypes to evaluate design alternatives, should be captured as rationale for the chosen alternative. Rule 6: Document must be Current but Not Too Current

Documents always provide authority, reference for any impending tasks or actions. Documentation that is incomplete or inconsistent or out of date will not find a place with readers and is not used as an authority or reference. Current document that is kept updated and accurate is used.

Document that does not answer the basic questions needs to be fixed for correctness within minimum possible time. Updated document will deliver a strong message that it is the final and authoritative source for information. E.g. at the end of each iteration, or each incremental release, providing revised document is absolutely essential.

Every design decision need not be recorded and distributed the instant it is made; rather, the document should be subject to version control and have a release strategy. Rule 7: Reviewing Document for Fitness of Purpose

Only the intended users of a document can authoritatively convey whether it contains the right information presented in the right way. It is always better to have the document reviewed by representatives of the community or communities for which it was written, before a document is released.