
\section{The AutoMed Repositories API}
\label{sec:repAPI}

The repositories API provides methods to create, query, alter and
remove models, constructs, construct schemes, schemas, schema objects,
object schemes, transformations as well as some ancillary etnitities
such as access methods for extensional schemas.  An ER diagram of how
these entities are related to each other is given in
Appendix~\ref{sec:repSchema}.  The repositories API comprises of Java
classes representing each of these entities, all the methods for
manipulating the repositories are in these classes.

The AutoMed GUI tools will access the MDR and STR via the AutoMed
Repository API.
The two major classes that will be created directly by the (AutoMed) tool
are the \texttt{Model} class (from the MDR) and the \texttt{Schema} class
(from the STR).  The classes we have created (partially) so far for the
AutoMed Repositories API are listed in Table~\ref{table:api_classes}.


\begin{stdtable}{Classes for the AutoMed Repositories API}
{table:api_classes}

\begin{tabular}{lll}
\multicolumn{3}{>{\columncolor{header}}c}{AutoMed Repositories API Classes} \\[0.3cm]
\rowcolor{header}
Class & Repository & Created By \\
\textbf{Model}
& MDR
& AutoMed tool \\
\rowcolor{evenrow}
\textbf{Construct}
& MDR
& Model \\
\textbf{SchemePos}
& MDR
& Construct \\
\rowcolor{evenrow}
\textbf{Schema}
& STR
& AutoMed tool \\
\textbf{SchemaObject}
& STR
& Schema \\
\rowcolor{evenrow}
\textbf{ObjectScheme}
& STR
& SchemaObject \\
\textbf{Transformation}
& STR
& AutoMed tool \\
\rowcolor{evenrow}
\textbf{AccessMethod}
& STR
& AutoMed tool \\
\textbf{Protocol}
& STR
& AutoMed tool \\
\end{tabular}

\end{stdtable}


Examples showing the usage of the classes related to the MDR and STR are
included in Section~\ref{sec:mdr_classes} and Section~\ref{sec:str_classes}
respectively.

\subsection{Classes related to the MDR}
\label{sec:mdr_classes}

The \texttt{Model} class represents data models.  The argument required for
creating a \texttt{Model} object is the \texttt{name} of the model.  For
example, the following line creates a \texttt{Model} named \texttt{ER}:

\texttt{Model myER = new Model(``ER'');}

To create \texttt{Constructs} for the \texttt{Model}, a method is provided
in the \texttt{Model} class.  For example, to create an entity for the
\texttt{myER} model, we do the following:

\begin{verbatim}
Construct myEREnt = myER.createConstruct(``Entity'',
                                   Construct.CONSTRUCT_CLASS_NODAL,
                                   true);
\end{verbatim}

The first argument of the \texttt{createConstruct} methods takes a
\texttt{String} value which represents the name of the \texttt{Construct}.
The second argument is a constant integer indicating the class of the
construct, its value must be \texttt{Construct.CONSTRUCT\_CLASS\_\$}, where
\texttt{\$} is one of \texttt{NODAL}, \texttt{LINK}, \texttt{LINK\_NODAL},
and \texttt{CONSTRAINT}.  The third argument accepts a \texttt{boolean}
value.  It is set to \texttt{true} if the construct is indeed a construct
in the model (the \textbf{isRoot} field in the \emph{Construct} table of
the MDR) and set to \texttt{false} otherwise.  A model identifier
(\textbf{mid}) is created upon creation of a \texttt{Model} object and a
unique construct identifier (\textbf{cid}) is created for each
\texttt{Construct} object.  To fill the \emph{construct} table in the MDR, 
the value for the field \textbf{mid} is implied by the calling
\texttt{Model} object that calls the \texttt{createConstruct} method.

We now need to fill the \emph{scheme} table of the MDR for the construct
we have created.  The method \texttt{createSchemePos} in the
\texttt{Construct} class allows us to do so.

\begin{verbatim}
myEREnt.createSchemePos(SchemePos.SCHEME_TYPE_NAME,
                        null,
                        true,
                        SCHEME_HDM_TYPE_N1,
                        1, 1);
\end{verbatim}

The \texttt{createSchemePos} method does not return a value.  The first
argument takes the value \texttt{SchemePos.SCHEME\_TYPE\_\$}, where
\texttt{\$} is one of \texttt{NAME}, \texttt{CONSTRUCT},
\texttt{ALTERNATION}, and \texttt{SEQUENCE}.  The second argument is
always \texttt{null} if the SCHEME\_TYPE is \texttt{NAME}.  It is of type
\texttt{Construct} if the SCHEME\_TYPE is \texttt{CONSTRUCT}.  We have not
yet arrived at a decision as to what the treatment should be for the other
two SCHEME\_TYPES.  The third argument refers to the \textbf{isKey} field
of the \emph{scheme} table in the MDR.  The fourth argument indicates the
corresponding HDM type in the HDM template.  Its value is
\texttt{SchemePos.SCHEME\_HDM\_TYPE\_\$}, where \texttt{\$} is one of
\texttt{N1}, \texttt{N2}, \texttt{P1}, \texttt{P2}, and \texttt{C}.
The last two arguments refer to the \textbf{lower} and \textbf{upper}
fields in the \emph{scheme} table.  Details about the meaning of these
fields (and tables) can be found in~\cite{boy01a}.

The fragments of code together provide the MDR complete information for
the ER entity construct.  Table~\ref{table:mdr_er} shows the state of the
MDR after the execution of the code fragments.  An ER attribute can be
created in a similar fashion.  Table~\ref{table:mdr_all} shows the state
of the MDR after the attribute construct has also been created.

\begin{verbatim}
/*.......................... code fragment for ER Attribute ...*/
Construct myERAtt = myER.createConstruct(``Attribute'',
                            Construct.CONSTRUCT_CLASS_LINK_NODAL,
                            true);

myERAtt.createSchemePos(SchemePos.SCHEME_TYPE_CONSTRUCT,
                        myEREnt,
                        true,
                        SCHEME_HDM_TYPE_P1,
                        1, 1);

myERAtt.createSchemePos(SchemePos.SCHEME_TYPE_NAME,
                        null,
                        true,
                        SCHEME_HDM_TYPE_N2,
                        1, 1);
/*....................... end of code fragment ER Attribute ...*/

\end{verbatim}

\begin{stdtable}{MDR (ER entity created)}{table:mdr_er}
\subtable[]{
\begin{tabular}{ll}
\multicolumn{2}{>{\columncolor{tablename}}c}{model} \\
\rowcolor{columnname}
\underline{mid} & name \\
1 & ER \\
\end{tabular}}
\hspace{1em}
\subtable[]{
\begin{tabular}{lllll}
\multicolumn{5}{>{\columncolor{tablename}}c}{construct} \\
\rowcolor{columnname}
mid & \underline{cid} & name & class & isRoot \\
1 & 1 & Entity & NODAL & true \\
\end{tabular}}

\subtable[]{
\begin{tabular}{llllllllll}
\multicolumn{10}{>{\columncolor{tablename}}c}{scheme} \\
\rowcolor{columnname}
mid & \underline{cid} & \underline{pos} & type & argMid & argCid & isKey
& HdmType & lower & upper \\
1 & 1 & 1 & NAME & - & - & true & N1 & 1 & 1 \\
\end{tabular}}
\end{stdtable}


\begin{stdtable}{MDR (ER entity \& attribute created)}{table:mdr_all}
\subtable[]{
\begin{tabular}{ll}
\multicolumn{2}{>{\columncolor{tablename}}c}{model} \\
\rowcolor{columnname}
\underline{mid} & name \\
1 & ER \\
\end{tabular}}
\hspace{1em}
\subtable[]{
\begin{tabular}{lllll}
\multicolumn{5}{>{\columncolor{tablename}}c}{construct} \\
\rowcolor{columnname}
mid & \underline{cid} & name & class & isRoot \\
1 & 1 & Entity & NODAL & true \\
1 & 2 & Attribute & LINK-NODAL & true \\
\end{tabular}}

\subtable[]{
\begin{tabular}{llllllllll}
\multicolumn{10}{>{\columncolor{tablename}}c}{scheme} \\
\rowcolor{columnname}
mid & \underline{cid} & \underline{pos} & type & argMid & argCid & isKey
& HdmType & lower & upper \\
1 & 1 & 1 & NAME & - & - & true & N1 & 1 & 1 \\
1 & 2 & 1 & CONSTRUCT & 1 & 1 & true & P1 & 1 & 1 \\
1 & 2 & 2 & NAME & - & - & true & N2 & 1 & 1 \\
\end{tabular}}
\end{stdtable}


\subsection{Classes related to the STR}
\label{sec:str_classes}

The \texttt{Schema} class represents schemas.  A \texttt{Schema} object
is created by calling the \texttt{Schema} class constructor with the
value for the name of the schema (of type \texttt{String}) and three
\texttt{boolean} values indicating whether or not the schame is an
extentional schema, an extentional database, and a data source.  The
following is an example creating a schema named \texttt{mySchema}.

\texttt{Schema mySchema = new Schema(``s1'', true, true, true);}

Schema objects are added to the schema by calling the
\texttt{createSchemaObject} method of the \texttt{Schema} class.
The following code fragment creates an entity and an attribute for
\texttt{mySchema}.

\begin{verbatim}
SchemaObject myEntity1 = mySchema.createSchemaObject(myEREnt,
                                          new Object[] {``E1''});
SchemaObject myAttribute = mySchema.createSchemaObject(myERAtt,
                               new Object[] {``A1'', myEntity1});
\end{verbatim}

The first argument of the \texttt{createSchemaObject} method takes
an object reference of type \texttt{Construct}, which indicates the type of
construct to which the schema object being created belongs.  The
second argument is an \texttt{Object} array that accepts values of
either of type \texttt{String} or \texttt{SchemaObject}.  Only one
\texttt{String} value is allowed in the \texttt{Object} array.  This
\texttt{String} corresponds to the \textbf{value} field in the
\emph{schema\_objects} table in the STR.  An \texttt{ObjectScheme}
object is automatically created for each \texttt{SchemaObject}
object by taking the \texttt{Object} array argument.  In the creation
of each \texttt{ObjectScheme} object, the type of the elements in the
\texttt{Object} array are verified against the data in the
\textbf{scheme} table in the MDR.  Data entries are made in the
\emph{object\_schemes} table in the STR according to the order in which
the elements in the \texttt{Object} array are declared.  The result
produced by the fragments of code is shown in Table~\ref{table:str}.


\begin{stdtable}{STR (Schema with ER entity \& attribute created)}
{table:str}
\subtable[]{
\begin{tabular}{llllll}
\multicolumn{6}{>{\columncolor{tablename}}c}{schemas} \\
\rowcolor{columnname}
\underline{sid} & name & es & edb & data\_source & is\_cached \\
1 & s1 & 1 & 1 & 1 & 0 \\
\end{tabular}}

\subtable[]{
\begin{tabular}{llllll}
\multicolumn{6}{>{\columncolor{tablename}}c}{schema\_objects} \\
\rowcolor{columnname}
sid & mid & cid & \underline{obid} & value & is\_temp \\
1 & 1 & 1 & 1 & E1 & 0 \\
1 & 1 & 2 & 2 & A1 & 0 \\
\end{tabular}}
\hspace{1em}
\subtable[]{
\begin{tabular}{lll}
\multicolumn{3}{>{\columncolor{tablename}}c}{object\_schemes} \\
\rowcolor{columnname}
\underline{obid} & \underline{scheme\_pos} & sobid \\
1 & 1 & 1 \\
2 & 1 & 1 \\
2 & 2 & 2 \\
\end{tabular}}
\end{stdtable}

Further investigation is still required for the other STR-related
classes and hence they are not included in this report.


