Major change
[u/philim/db2osl_thesis.git] / program_interface.tex
CommitLineData
28b54c67 1\section{Interface and usage}
c31df1ed
PM
2\label{interface}
3This section describes the interface to the operating system and the user interface.
b96bb723 4For information on programming interfaces, see Section~\fullref{arch}.
c31df1ed
PM
5
6\subsection{User interaction and configuration}
b96bb723 7\label{usage}
c31df1ed 8\subsubsection{Basic usage}
28b54c67 9\label{basic}
c31df1ed 10Currently, the only user interface of \myprog{} is a command-line interface.
002fa020 11Since the program is supposed to bootstrap the OBDA specification automatically and
c31df1ed 12thus there is little interaction, but a lot of output, this was considered ideal.
28b54c67
PM
13Basically, one invocation of \myprog{} will initiate the automatic, non-interactive
14bootstrapping of exactly one \osl{} specification written to the standard output,
15a behavior which can be modified via command-line arguments.
c31df1ed 16Because of its ability to write to the standard output (which is also the default
28b54c67 17behavior), it is easy to pipe the output of \myprog{} directly into a program that
002fa020 18handles it in a Unix-/POSIX-like fashion \cite{unix}:
c31df1ed
PM
19\codepar{db2osl myserver.org | osl2onto myserver.org}
20
21(supposed \name{osl2onto} is a tool that reads an \osl{} specification from its
22standard input and uses it to bootstrap an ontology from the database
23specified on its command line).\\
002fa020 24This scheme is known as ``Pipes and Filters architectural pattern'' \cite{patterns}.
c31df1ed
PM
25
26By inserting additional ``filters'', the bootstrapping process can be customized
27without changing any of the involved programs:
28b54c67 28\codepar{db2osl mydatabase.org | customize\_spec.sh | osl2onto mydatabase.org}
c31df1ed 29
28b54c67
PM
30(supposed \name{customize{\scriptsize \_}spec.sh} is a shell script that modifies
31a given \osl{} specification in the way the user desires).
c31df1ed 32
28b54c67
PM
33\subsubsection{Configuration via command-line arguments}
34The behavior of \myprog{} itself can be adjusted via command-line arguments (only).
002fa020 35%The syntax for their application follows the POSIX standard \cite{posix} (no!).
c31df1ed
PM
36Most features can be configured via short options (as, for example, \code{-P}).
37To allow for enhanced readability of \myprog{} invocations, each feature can (also)
38be configured via a long option (like \code{\textendash\textendash password}).
28b54c67
PM
39The utilization of configuration files was considered, but for the time being
40seen as unnecessary complicating
41while not addressing any real difficulties.
c31df1ed 42
28b54c67 43The command-line arguments \myprog{} currently supports are
45d598e9
PM
44described in Table~\ref{if_tbl_arguments_desc};
45their default values are listed in Table~\ref{if_tbl_arguments_def}.
28b54c67 46There is currently no switch to set the output format, since the only supported
c31df1ed
PM
47output format, besides \osl{}, is a low-level output format for debugging purposes.
48Because of this and since the change that has to be made in the source code to enable it
49only involves changing one token, it was preferred not to offer a command-line option
28b54c67 50for this, to not unnecessarily complicating the command-line interface for the
c31df1ed
PM
51normal, non-debugging, user.
52
53\begin{table}[]\begin{center}
28b54c67
PM
54 \begin{tabular}{p{4.9cm}|p{11.1cm}}
55 Option(s) & Description, taken from the help page of \myprog{}\\
c31df1ed 56 \hline
28b54c67
PM
57 \code{\textendash\textendash database}, \code{-d} & database name (\name{Java} regular expression) databases have to match to be processed; see also: \code{\textendash\textendash loose-database-match}\\
58 \code{\textendash\textendash echo-password} & echo input when prompting for SQL password -- must be specified before \code{\textendash\textendash password-prompt} to get effective\\
59 \code{\textendash\textendash help}, \code{-h, } & show this help and exit\\
60 \code{\textendash\textendash interactive}, \code{-i} & be interactive when chosing database\\
61 \code{\textendash\textendash login}, \code{-L} & SQL login\\
62 \code{\textendash\textendash loose-database-match} & if no database matching the regex specified with \code{\textendash\textendash database} is found on the given server and \code{\textendash\textendash interactive} is not specified for this job, use some other database\\
63 \code{\textendash\textendash osl-header} & use the specified custom (non-standard) OSL header, implies \code{\textendash\textendash remote-osl-header} (to import no header, specify the empty string)\\
64 \code{\textendash\textendash output-file}, \code{-o} & use the specified output file (for the standard output, specify ``-'')\\
65 \code{\textendash\textendash password}, \code{-P} & SQL password; use \code{\textendash\textendash password-prompt} to get a password prompt (if you do both, the password set via this switch will be ignored)\\
66 \code{\textendash\textendash password-prompt}, \code{-p} & prompt for SQL password; a password set via \code{\textendash\textendash password} is ignored\\
67 \code{\textendash\textendash remote-osl-header}, \code{-R} & don't use hard-coded version of the OSL header for verification\\
68 \code{\textendash\textendash remote-test} & try to retrieve a database schema from a hard-coded list of servers and take the first one successfully retrieved (and accepted, when \code{\textendash\textendash interactive} is given; note: give a dummy server if you want to do a test besides other jobs)\\
69 \code{\textendash\textendash test} & use hard-coded test database schema, ignore given servers (note: give a dummy server if you want to do a test besides other jobs)\\
c31df1ed 70 \end{tabular}\\
28b54c67
PM
71 \caption{Command-line arguments in \myprog{} -- descriptions}
72 \label{if_tbl_arguments_desc}
c31df1ed
PM
73 \end{center}\end{table}
74
28b54c67
PM
75\begin{table}[]\begin{center}
76 \begin{tabular}{l|l}
77 Option(s) & Default value\\
78 \hline
79 \code{\textendash\textendash database, -d} & \code{.*}\\
80 \code{\textendash\textendash echo-password} & \code{false}\\
81 \code{\textendash\textendash help, -h, } & \code{false}\\
82 \code{\textendash\textendash interactive, -i} & \code{false}\\
83 \code{\textendash\textendash login, -L} & \code{anonymous}\\
84 \code{\textendash\textendash loose-database-match} & \code{false}\\
85 \code{\textendash\textendash osl-header} & \code{<empty string>}\\
86 \code{\textendash\textendash output-file, -o} & \code{-}\\
87 \code{\textendash\textendash password, -P} & \code{<empty string>}\\
88 \code{\textendash\textendash password-prompt, -p} & \code{false}\\
89 \code{\textendash\textendash remote-osl-header, -R} & \code{false}\\
90 \code{\textendash\textendash remote-test} & \code{false}\\
91 \code{\textendash\textendash test} & \code{false}\\
92 \end{tabular}\\
93 \caption{Command-line arguments in \myprog{} -- default values}
94 \label{if_tbl_arguments_def}
95 \end{center}\end{table}
96
97The sole invocation of \code{db2osl}, without any arguments, does not initiate any
98processing but displays the usage directions instead, in addition to an error message
99pointing out the missing server argument.
c31df1ed
PM
100
101\subsubsection{Multiple bootstrapping operations or multiple servers}
28b54c67 102To perform multiple bootstrapping operations with only one invocation of \myprog{},
c31df1ed
PM
103it is sufficient to concatenate the command-line arguments for each operation,
104separated by blanks, to get the final command line.
28b54c67
PM
105However, when combining a test job with other operations, some arbitrary string
106has to be inserted as dummy server to allow distinguishing the different jobs
107and assigning each command-line argument to the appropriate job.
c31df1ed 108
28b54c67 109Likewise, to check several servers in order for the database to be used
c31df1ed
PM
110for one bootstrapping operation, these servers have to be concatenated,
111separated by blanks.
112Again, the distinction of the different bootstrapping jobs has to be possible,
113so all but the first operation have to have at least one command-line argument
28b54c67 114that signals the beginning of a new job definition
c31df1ed
PM
115(which is no practical problem, since to enforce this, a default argument simply
116can be stated explicitly without changing the behavior of the invocation).
117
118All settings are configured per operation, so, when using a shell that separates batched
119commands by `;',
120\codepar{db2osl \textendash\textendash database employees \textendash\textendash
121 password itsme sql.myemployer.com\\
122 \textendash\textendash database test myserver.org backup.myserver.org}
123is equivalent to
124\codepar{db2osl \textendash\textendash database employees \textendash\textendash
125 password itsme sql.myemployer.com;\\
126 db2osl \textendash\textendash database test myserver.org backup.myserver.org}
127
28b54c67
PM
128Thus, a parameter defined for one operation (like the password
129in the example) will have no effect on other operations.
130This ensures that typical errors are prevented when merging several invocations
131of \myprog{} into one (or vice versa)
b96bb723 132and allows for a straight-forward and comprehensible implementation.
28b54c67
PM
133
134\subsubsection{Advanced modifications}
b96bb723 135\label{advanced}
28b54c67
PM
136Since \osl{} specifications are plain text files, a user can edit them in any desired
137text editor if he wants to change them in ways that go beyond the functionality
138\myprog{} provides or that can be achieved by scripts or programs modifying their
139input automatically.
62fe6284 140Because of \osl{} being a subset of \name{OWL} (see the specification
b96bb723 141of \osl{} in Section~\ref{osl_spec}), he can thereby take advantage of editors
28b54c67
PM
142supporting syntax highlighting or other features making the handling of
143the respective \name{OWL} serialization more comfortable.
144
145Moreover, every common ontology editor can be used to edit the generated \osl{}
146specification automatically or manually.
147Doing so, care has to be taken to make the ontology remain a conforming \osl{}
148specification. However, since the restrictions imposed by \osl{} are rather
149small and intuitive, this is easily achieved.
b96bb723
PM
150One of the most popular ontology editors \cite{protegepopular}, \name{Protégé},
151is an open, \name{Java} based platform supporting plug-ins \cite{protege};
152for a habitual \name{Protégé} user it should be an easy task to write an
153\osl{} plugin.
154Furthermore, upcoming tools supporting \osl{} (see Section~\fullref{future}) most
62fe6284 155likely will be able to check input files for conformity with the \osl{} definition.
c31df1ed
PM
156
157\subsection{Integration into systems}
b96bb723
PM
158Besides the use cases described in Paragraph~``\nameref{basic}''
159and in Paragraph~``\nameref{advanced}'' in the previous Section~\ref{usage},
28b54c67
PM
160there are many other ways in which \myprog{} can be used.
161For example, a database can be periodically checked for changes that make a
162re-bootstrapping necessary:
163\codepar{db2osl -d mydb myserver.org | sha256sum >oldsum\\
164 cp oldsum newsum\\
62fe6284 165 while diff oldsum newsum; do\ \ \# while checksums are the same\\
45d598e9
PM
166 \ind{} sleep 3600\ \ \# wait 1 hour\\
167 \ind{} db2osl -d mydb myserver.org | sha256sum >newsum\\
28b54c67
PM
168 done\\
169 rm oldsum newsum\\
170 \# notify web admin via e-mail:\\
002fa020 171 date | mutt -s "Re-bootstrapping necessary" web-admin@myserver.org}
28b54c67
PM
172
173Another possible example is the integration of \myprog{} into a shell script
174that bootstraps all databases on a server:
175\codepar{regex=\textquotesingle(?!\$).*\textquotesingle\ \ \# accept all nonempty database names first\\
176 while db2osl -d "\$regex" -o spec myserver.org; do\\
45d598e9
PM
177 \ind{} dbname="\`{} sed -ne \textquotesingle/xmlns:ont/ \{ s|.*/||; s|\#"||p \}\textquotesingle\ spec \`{}"\\
178 \ind{} mv spec "\$dbname".osl\\
179 \ind{} \# don't use this database a second time:\\
180 \ind{} regex="\`{} printf \%s "\$regex" | sed -e "s,\textbackslash\textbackslash\textbackslash\textbackslash\$,\$|\$dbname\$," \`{}"\\
28b54c67
PM
181 done}
182
28b54c67
PM
183Since the programming language used to implement \myprog{} is \name{Java},
184it is possible to deploy it on all platforms offering the
002fa020 185\name{Java} Runtime Environment TODO.
28b54c67
PM
186Additionally, it is possible to deploy it as a Web application TODO.
187
188To simplify integration on the code level, the architecture of \myprog{} was
189designed to be highly modular and to cleanly separate code with different areas of
190responsibility into different packages
b96bb723 191(for details about the structuring of \myprog{}, see Section~\fullref{arch}).
28b54c67
PM
192This modularity, besides facilitating understanding the code,
193allows for a high degree of code reusability.
194
195For example, the packages \code{database}, \code{osl} and \code{specification}
196can be reused in other programs with little or no changes --
197the biggest change involves combining the database schema retrieval with the
198user interface of the new program to provide control over the retrieval process
199when reusing the \code{database} package
200(to do this, three method calls have to be replaced).
201%However, the \code{osl} package heavily depends on the \code{specification} package.
202If the accruing information shall be used in another way than being output or logged,
203this of course has to be implemented.
204If not, it is sufficient to replace the used \code{Logger} object by anohter one
205providing the desired behavior, since the \code{Logger} class is part of the
002fa020 206\name{Java} API and widely used \cite{log}.
28b54c67
PM
207This is a good example of how using well-known and commonly used classes can
208greatly improve modularity and reusability.