\markboth{Tracz}{Tracz}
\documentstyle[11pt]{article}
%\documentstyle{article}
\oddsidemargin  0.26in % Leave enough for binding margin
\evensidemargin 0.26in %
\topmargin      -1.00in % (adjusted for printer bias)
\headheight      .00in  % (no headers)
\headsep         .75in  % (top margin + headers + skip)
\footheight     12.0pt  % ??? (seems to work ok)
\footskip       25.0pt  % ??? ( "   "  )
\textheight     9.425in % (instructions: 9 1/8" min, 9 7/16" max)
\textwidth      6.5in   %

\markboth{Tracz}{Tracz}
\pagestyle{myheadings}

\parindent=0pt
\parskip=8pt
\def\@maketitle{\vbox to 2.6in{\hsize\textwidth
    \linewidth\hsize \vfil \centering
    {\large \@title \par}
    \vskip 2em
    {\normalsize
    \begin{tabular}t|{c}\@author
    \end{tabular}\par}
    \vfil}
}
 
\begin{document}
%\bibliographystyle{alpha}
\bibliographystyle{ieeetr}
\title{Design Records: A Way to Organize Domain Knowledge}
 
\author{Will Tracz -- Steve Shafer -- Lou Coglianese\\
\\
IBM Federal Systems Company\\
MD 0210, Owego, NY 13827\\
Tel: (607) 751-2169, fax: (607) 751-6025\\
Email: tracz@vnet.ibm.com\\
}
\date{}
 
\maketitle
 
\begin{abstract}
 
\vspace{.25in}
 
This document describes the {\bf Design Records} being
developed as part of the Domain-Specific Software Architecture Avionics Domain
Application Generation Environment (DSSA-ADAGE) Project\footnote{This effort
is sponsored by the US Department of Defense Advanced Research Projects Agency
in cooperation with the US Air Force Wright Laboratory Avionics Directorate
under contract F33615-91-C-1788.}.
A design record aids in the generation of new avionics applications as
well as the maintenance of existing systems built using ADAGE.
The purpose of a design record is to serve as a vehicle for software
understanding by functioning as a collection point for {\it domain-specific}
knowledge about the components that make up a Domain-Specific Software
Architecture (DSSA),
%and {\it application-specific} knowledge about their instantiations.\\
 
\vspace{.125in}
 
There are {\bf three} kinds of design records used by ADAGE to describe
the avionics software architecture and components
 \cite{ADAGEIBM9307,ADAGEUT9303}.
\begin{enumerate}
  \item {\bf Domain Model Design Record} defines a collection of
        realms\footnote{See Batory's \cite{Batory86,Batory} for a detailed
        treatment of creating layered designs using realms and type
        expressions.},
  \item {\bf Realm Design Record} defines the interface for a collection
        of components, and
  \item {\bf Component Design Record} represents an  (alternative)
        implementation or design choice.
\end{enumerate}
 
\vspace{0.2in}
\noindent
{\bf Keywords:}Domain Analysis, Knowledge Representation, Software Reuse.
 
\vspace{0.2in}
\noindent
{\bf Workshop Goals:} Facilitate the technical interchange of ideas
and experience related to the development and use of software components.
 
\vspace{0.2in}
\noindent
{\bf Working Groups:}   Knowledge Representation, Design for Reuse.
\end{abstract}
 
\newpage
 
\section{Background}
 
IBM FSC as part of ARPA Domain-Specific Software Architecture Program
has been actively pursueing the developement of tools and processes
to support the generation and application of software architectures.
One of the major focusses of this effort has been the creation of
a ``design record''.
The purpose of a design record is to serve as a vehicle for software
understanding by functioning as a collection point for {\it domain-specific}
knowledge about the components that make up a Domain-Specific Software
Architecture (DSSA).
ADAGE design records play a
central role in 1) describing the avionics domain-specific software architecture
and 2) integrating the tools that comprise the ADAGE environment.
 
Two points merit distinction in their bearing on the design record:
\begin{enumerate}\itemsep -3pt
\item the contents of the ADAGE {\bf Component Design Record} (i.e., its
``data elements'') are patterned after those initially proposed by Bill
Scherlis in \cite{Scherlis90}.
%
\item While a design record serves as a collection point for:
   \begin{itemize}\itemsep -3pt
      \item {\it domain-specific} knowledge about components or design
            alternatives and
      \item {\it implementation-specific} knowledge about alternate
      implementations,
    \end{itemize}
      it does {\bf not} provide information about their application,
      instantiation, or configuration.
      This type of information, though
      similar in nature, is part of an application's {\bf design history}.
\end{enumerate}
 
\section{Position}
 
The goal of a design record is to adequately describe a domain-specific
software architecture and its software software components such that design
decisions and component selections can be accomplished without looking at
implementations.
 
Asset capture and re-capture is supported in ADAGE by the design record,
hypermedia browsing capability, and the domain engineering process
\cite{ADAGEIBM9202}.
The design record provides a ``common data structure for system
documentation and libraries \cite{Scherlis90}''.
 
The {\bf basic} design record data elements, as proposed by Scherlis
%\cite{Scherlis90}
and arranged according to phases in the software life cycle, include:
\begin{enumerate}\itemsep -3pt
\item {\bf name/type},
\item {\bf description},
\item {\bf requirement specification fragments},
\item {\bf design structure},
\item {\bf design rationale},
\item {\bf interface and architecture specifications and dependencies},
\item {\bf PDL texts},
\item {\bf code},
\item {\bf configuration and version data}, and
\item {\bf test cases}.
 
In addition to the ``primary'' lifecycle elements listed above, the following
``secondary'' elements aide in the (re-)use of the components by capturing
additional information:
\item {\bf metric data},
\item {\bf access rights},
\item {\bf search points},
\item {\bf catalog information},
\item {\bf library and DSSA links}, and
\item {\bf hypertext paths}.
 
For the avionics domain, the ADAGE design records
contain the {\bf basic} data items listed above (with some domain-specific
clarifications) in addition to some DSSA-ADAGE specific items including:
 
\item {\bf models}
\item {\bf constrants}, and
\item {\bf data quality}.
\end{enumerate}
 
The reader should note that because the design record is a
dynamic entity in that its contents grow as a component goes through the
various stages in the software development life cycle, all component design
records do not contain the same amounts of information.
In addition, certain design record elements may ``inherit'' values for
other records they may be associated with (e.g., a realm component design record
inherits the constraints of the realm it is a member of).
 
%--------------------
\subsection{Types of Design Records}
%--------------------
 
The goal of design records are to organize information associated with a
domain-specific software architecture.
There are {\bf three} kinds of design records used by ADAGE to describe
the avionics domain software architecture and components
\cite{ADAGEIBM9307,ADAGEUT9303}:
\begin{enumerate}\itemsep -3pt
  \item {\bf Domain Model Design Record} defines a collection of realms,
  \item {\bf Realm Design Record} defines the interface for a collection of
         components, and
  \item {\bf Component Design Record} represents an (alternative)
         implementation or design choice.
\end{enumerate}
 
The ``component interface'' found in a {\bf Realm Design Record} includes not
only the entry points, type definitions and data formats (e.g., Ada package
specification), but a description of its functionality, side effects,
performance expectations, degree and kind of assurance of consistency between
specification and implementation (reliability), and appropriate test cases.
 
%--------------------
\subsubsection{Domain Model Design Record}
%--------------------
 
The {\bf Domain Model Design Record} defines a collection of realms.
These show up as a list in the {\bf library and DSSA links} element of the
design record.
The {\bf Domain Model Design Record}
has, as a minimum: a name, a description, and an interface/architecture
specification, as well as a collection of administrative information (e.g.,
version number, catalog information, access rights, etc.).
 
 
%--------------------
\subsubsection{Realm Design Record}
%--------------------
 
The {\bf Realm Design Record} defines the interface for a collection of
components.
These show up as a list in the {\bf library and DSSA links} element of the
design record.
A {\bf Realm Design Record} defines either {\it design decision} or {\it
options} (e.g., a list of sensors to choose from), or {\bf implementation
alternatives} (e.g., a list of stack implementations).
%In the latter case, a {\bf Realm Design Record} points to another
 
 
%--------------------
\subsubsection{Component Design Record}
%--------------------
 
The {\bf Component Design Record} may be used to describe three kinds
of components:
\begin{enumerate}\itemsep -3pt
  \item {\it Domain Specific} -- map into problem space,
  \item {\it Implementation Specific} -- map into solution space, and
  \item {\it Domain Independent} -- general components that may be used in
         other domains.
\end{enumerate}
 
Component Design Records normally have some sort of execution capability.
This can take the form of an Ada package specification and body, an
executable SEDL specification, or a parameterized LILEANNA make statement
indicating how such a component could be constructed.
 
%--------------------
\subsection{Design Record Creation}
%--------------------
 
As part of the domain engineering process described in \cite{ADAGEIBM9202},
a  {\bf Component Design Record} is created for each component in DSSA.
As the DSSA reference architecture is configured and extended to meet the
requirements of a new application using the Architecture-Based
Development Process \cite{ADAGEIBM9203}, additional information is recorded
as part of a {\bf Design History Record} (i.e.,  configuration data
and design decision rationale).
In addition, new design records are generated to account for extensions to
the architecture, addition of components with unprecedented functionality, or
new implementations of existing components.
 
%--------------------
\subsection{Design Record Evolution}
%--------------------
 
Each generic component in the avionics DSSA has a design record with pointers
to instances of the design record (via the DSSA link data element).
The design history records for instances of components ``inherit'' the elements
of the generic while specializing those that are application specific.
In particular:
\begin{itemize}\itemsep -3pt
\item {\bf configuration and version data} indicate parametric values used
to instantiate the component and
\item {\bf design rationale} describe the reasons for their selection.
\end{itemize}
 
The resulting chain or information web is what has been called the
``{\bf Design History}'' in ADAGE \cite{ADAGEIBM9201}.
 
%==================================
\section{Design Record Comparisons}
%==================================
 
This section compares the ADAGE design record data elements to
the reusable software component information proposed by STARS (Software
Technology for Adaptable, Reliable Systems), ASSET (Asset Source for Software
Engineering Technology), RIG (Reuse Interoperability Group), and IBM's
internal reuse repository.
 
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++
\subsection{STARS Comparison}
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
According to the {\bf STARS Reuse Concept of Operations, Volume I}
\cite{STARSCONOPS}, the following asset information ``may be
required for asset acceptance:''
\begin{itemize}\itemsep -3pt
\item abstract,
\item author/ownership information,
\item author certificate of originality,
\item copyrights/patents,
\item distribution rights,
\item distribution restrictions,
\item liability statements for use/misuse,
\item maintenance agreements,
\item environmental dependencies, and
\item dependencies on other assets.
\end{itemize}
The ADAGE design record completely supports the inclusion of this information.
 
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++
\subsection{ASSET Comparison}
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
According to the {\bf ASSET Submittal Guidelines}
\cite{ASSETRR}, the following documentation  is recommended
for asset acceptance into the ASSET Repository:
\begin{itemize}\itemsep -3pt
\item ``an abstract,
\item a user's guide or instructions on how to use,
\item a list of files making up the asset (preferably in compilation order),
\item installation/implementation instructions,
\item sample input/output,
\item design and/or requirements documents,
\item test programs, procedures an/or results,
\item description of the environment under which the asset was developed/tested,
\item known limitations of the software,
\item a list of tools needed to interpret or used the asset,
\item warranties or disclaimers,
\item statement of distribution rights/licenses, and
\item list of special formats of files (e.g., Postscript, InterLeaf, SGML).''
\end{itemize}
 
The ADAGE design record completely supports the inclusion of this information.
 
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++
\subsection{RIG Comparison}
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
The Reuse Interoperability Group (RIG), a defacto standards organization,
whose goal is to facilitate cross reuse repository information exchange,
in {\bf A Basic Interoperability Data Model for Reuse Libraries}
\cite{RIGREF} identified the following subset of the ``Uniform Data Model'',
which defines the minimal set of information that reuse libraries should be
able to exchange about assets in order to interoperate:
 
\begin{itemize}\itemsep -3pt
\item  abstract,
\item  address of contributor/owner,
\item  cost/fee to use$^*$,
\item  date of information,
\item distribution statement,
\item domain,
\item element type (e.g., code, test suite, make file),
\item email address where asset resides$^*$,
\item fax \# where asset resides$^*$,
\item identification number$^*$,
\item keywords,
\item language,
\item Media asset is obtainable in$^*$,
\item name,
\item restrictions (e.g., legal),
\item security/classification,
\item target environment,
\item telephone \# where asset resides$^*$,
\item unique identifier$^*$,
\item version, and
\item version date.
\end{itemize}
 
This Basis Interoperability Data Model (BIDM) is derived from the Common Data
Model defined in the {\it Asset Library Open Architecture Framework} (ALOAF)
\cite{ALOAF} and the {\it STARS Repository Guidelines and Standards}
\cite{STARSRGUIDE}.
 
With the exception of those items indicated with an ``$^*$'', the ADAGE design
record supports the inclusion of the RIG local ``attributes'' for component
classes.
 
 
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++
\subsection{IBM Corporate Reuse Environment (CRE) Comparison}
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
IBM's internal use only software reuse tool, CRE (Corporate Reuse Environment)
is a sophisticated repository of tools for managing libraries of reusable
software components.  The ``Software Element Types'' required for entry
into the repository include:
\begin{itemize}\itemsep -3pt
\item abstract,
\item change history,
\item dependencies,
\item design,
\item interfaces,
\item legal,
\item load module,
\item metrics,
\item miscellaneous project information,
\item object module,
\item performance analysis,
\item product documentation,
\item references to other documents or components,
\item requirements for use and adaptation,
\item restrictions and side-effects,
\item reuse,
\item sample use,
\item source code,
\item specification (formal),
\item test materials,
\item usage information, and
\item variations:
\end{itemize}
 
 
\bibliography{tracz}
 
\section{Biography}
 
{\bf Will Tracz} is a senior programmer at the Owego Laboratory of the IBM
Federal Systems Company where he is currently a DARPA PI (Principal
Investigator) on the DSSA-ADAGE Project.  He is a member of IBM Corporate Reuse
Council and IBM FSC Reuse Steering Committee as well as editor of the
IBM Corporate Programming Reuse Newsletter and column editor for IEEE Computer.
His book, {\em Software Reuse: Emerging Technology},
published (1988) by IEEE Computer Society Press, paints a broad picture of
the technical, economic, pedagogical and social issues facing the transfer
of software reuse technology into the workplace.
 
\end{document}

