
\section{Introduction}
The purpose of this report is to describe the AutoMed repositories API
which provides a Java interface to the Model Definitions Repository
(MDR) and the Schemas and Transformations Repository (STR) both of
which have been developed as part of the AutoMed project.  These
repositories will be used when developing software for the project
such as a graphical schema transformation and intregation tool, schema
improvement tool and a JDBC driver.  The query processing,
optimisation and translation as well as the data migration and schema
evolution tools may well interact directly with the reps API as well
as indirectly through the JDBC driver.

Because the AutoMed project is concerned with schema integration using
a generic Hypergraph Data Model (HDM) with higher-level modelling
languages being defined in terms of the lower-level HDM, we need to
enable users of the API to describe the higher-level modelling
languages in a formal way so that our tools can automatically
translate between the two levels.  This is the function of the MDR.

The STR stores information about schemas in terms of the modelling
language constructs described in the MDR as well as primitive
transformations between schemas (thus describing transformation
pathways between them).  It also stores information about the data
source a schama describes such as how to access it, whether its data
is extensional or intentional, etc.


\section{Overview}
% arch of MDR, STR, DSR and the repAPI
\begin{stdfigure}{Architecture of the AutoMed Repositories API}{pic:api_arch}

\stdpicmag{-2}

\begin{picture}(42,22)
\put(0,0){\colorbox{lightgrey}{\makebox(22,27){}}}
%\put(1,1){\colorbox{blue}{\makebox(29,6){}}}
\entity(7,17){\tt Rep.\\\tt API}
\entity(2,7){\tt MDR}
\entity(12,7){\tt STR}
\path(6,11)(6,15)(16,15)(16,11)
\path(11,15)(11,17)
\entity(7,0){\tt DSR}
\path(6,7)(9,4)
\path(16,7)(13,4)
\path(11,4)(11,15)
\entity(7,23){\tt AutoMed\\\tt GUI tools}
\path(11,21)(11,23)
%\path(15,14)(22,14)
%\put(33,18){Other}
%\put(31,16){components}
% horrible way of drawing dotted lines...
%\path(30,14)(31,14)
%\path(32,14)(33,14)
%\path(34,14)(35,14)
%\path(36,14)(37,14)
%\path(38,14)(39,14)
%\path(40,14)(41,14)
% vertical
%\path(41,14)(41,15)
%\path(41,16)(41,17)
%\path(41,18)(41,19)
%\path(41,20)(41,21)
% another one...
%\path(28,16)(28,17)
%\path(28,18)(28,19)
%\path(28,20)(28,21)
%\path(28,21)(29,21)
%\path(30,21)(31,21)
%\path(32,21)(33,21)
%\path(34,21)(35,21)
%\path(36,21)(37,21)
%\path(38,21)(39,21)
%\path(40,21)(41,21)
\end{picture}

\end{stdfigure}

Figure~\ref{pic:api_arch} illustrates how the tool and the various
repositories are connected.  The DSR (Data Source Repository) is a
helper class that provides common functionality to the MDR and STR as
well as a test harness for the API.  The DSR will not be documented
further in this report.

After a breif description of the MDR and STR, we will describe the
reps API by giving example code that first uses the API to construct a
basic ER modelling langauge and then uses that language to construct
the schemas in the example.

We will give the schemas of the MDR and STR and the data that would be
produced by the example code for the reps API as well as some other
examples of data for more complex scenarios.

\subsection{MDR Overview}
The MDR (Model Definitions Repository) stores descriptions of
modelling languages.  In essence, it comprises of a list of constructs
for each modelling language along with the arguments needed to create
an instance of each construct and the means by which to translate
instances of constructs into HDM.

Each argument needed to create an instance can be a simple name, a
reference to an existing object of a given construct type, a list of
alternatives or a sequence.  Each argument has a lower and upper
cardinality\footnote{An upper bound of infinitry is denoted by giving
an upper bound which is lower than the lower bound.} which specifies
how many times the name / construct / alternation / sequence can
appear (all occurances make up the one argument for the construct).

Each construct is given an HDM type which can be either nodal,
linkage, link-nodal, or constraint (which simply means there is no
corresponding HDM), see \cite{PM98} for details.  Each HDM type (and
therefore each construct) has a template with varaiables that the
arguments specified for instantiating the construct can be assigned
to.

A very simple example would be an ER entity and attribute.  An entity
would have a nodal HDM type and would have one construction argument
-- the entity's name.  An attribute would have an HDM type of
link-nodal (because it creates a node for the attribute but can only
exist in relation to an existing entity) and its two construction
arguments would be the name of the attribute and the existing entity
to which it should be linked\footnote{A more realistic example might
have cardinality arguments as well}.

\subsection{STR Overview}
The STR (Schemas and Transformations Repository) stores information
about schemas and transformation pathways between them.  A schema is a
list of objects and associated object schemes.  Each object is
identified as being an instance of a particular construct in the MDR.
The object references that make up an object's scheme directly relate
to the instantiation arguments in the MDR for the object's construct.

The first instantiation argument of type name (as opposed to a
reference to an existing construct, alternation or sequence) is given
special treatement.  This name is used as the name of the object and
the object reference for the argument in which the name appeared
references the object it instantiates.  If a construct has more than
one name in its arguments then extra objects are created to store
these values.  These extra objects have no construct type.  Other than
that, the result is the same as it would be if there was a construct
representing whatever was named and a reference to an instance of that
construct used instead of just its name in the argument list.

Schemas themselves have no inherent modelling language.  Instead, each
object, through its construct type, is of a particular modelling
language.  This means that transformation pathways that convert a
schema from one language to another can be defined because the
intermediatory schemas with some constructs from both languages can be
described.

Their are two types of schema wich are stored -- schemas of acutal data
sources (extensional data) and intermediatory schemas (intentional
data) that exist in transformation pathways between the schemas of
actual data sources.  These intermediatory schemas are usually
themselves intentional\footnote{Intentional with respect to the schema
as opposed to the data described by the schema}; that is, the schemas
can only be desribed by looking at another schema's extension and a
pathway of transformations between the two.  The intentional schemas
can be temporarily materialised (i.e. made extensional) and indeed
this automatically happens when the schema's description is asked for
so that these differences are, for the most part, transparent to tools
using the repositories.

\subsection{Simple Example}
Throughout this paper the example in figure~\ref{fig:example_er} will
be used.

% diagrams of s1 and s2
\begin{stdfigure}{Example ER schemas}{fig:example_er}

\stdpicmag{-2}
\begin{small}

\def\schema(#1,#2)(#3,#4)#5#6{\setlength{\fboxsep}{0em}
\put(#1,#2){\colorbox{lightgrey}{\makebox(#3,#4){}}}
\put(#1,#2){\begin{picture}(#3,#4)
#6
\end{picture}}
\put(#1,#2){\makebox(2,2){\tt #5}}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% s1
%\setlength{\unitlength}{1cm}
\begin{picture}(58,25)
\schema(3,0)(24,23){s1}{\entity(14,2){\tt person}
\cardattribute(14,6)(8,7){\tt sex}{\tt 1:1}{\tt 1:N}
\cardattribute(14,4)(6,4){\tt name}{\tt 1:1}{\tt 1:N}
\cardattribute(14,2)(8,1){\underline{\tt id}}{\tt 1:1}{\tt 1:1}
\relationship(18,6)(18,18){\tiny \tt worksin}{\tt 1:1}{\tt 1:N}
\entity(14,18){\tt dept}
\cardattribute(14,20)(8,20){\underline{\tt dname}}{\tt 1:1}{\tt 1:1}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% s2
\schema(29,3)(32,18){s2}{\entity(12,13){\tt person}
\entity(7,1){\texttt{male}}
\entity(17,1){\texttt{female}}
\generalisation(13,9){\tt sex}
\path(11,5)(11,7)(21,7)(21,5)
\path(16,7)(16,9)
\isa(16,11)(16,13)
\cardattribute(12,14)(6,13){\underline{\tt id}}{\tt 1:1}{\tt 1:1}
\cardattribute(12,16)(6,17){\tt name}{\tt 1:1}{\tt 1:N}
\cardattribute(20,15)(26,15){\tt dname}{\tt 1:1}{\tt 1:N}}
\end{picture}

\end{small}
\end{stdfigure}


