Major change
[u/philim/db2osl_thesis.git] / program_interface.tex
CommitLineData
c31df1ed
PM
1\section{Interface}
2\label{interface}
3This section describes the interface to the operating system and the user interface.
4For information on programming interfaces, see section \fullref{arch}.
5
6\subsection{User interaction and configuration}
7\subsubsection{Basic usage}
8Currently, the only user interface of \myprog{} is a command-line interface.
9Since the program is supposed to bootstrap the OBDA Specification automatically and
10thus there is little interaction, but a lot of output, this was considered ideal.
11Because of its ability to write to the standard output (which is also the default
12behavior), it is easy to pipe the output of \myprog{} directly to a program that
13handles it in a Unix-/POSIX-like fashion TODO:
14\codepar{db2osl myserver.org | osl2onto myserver.org}
15
16(supposed \name{osl2onto} is a tool that reads an \osl{} specification from its
17standard input and uses it to bootstrap an ontology from the database
18specified on its command line).\\
19This scheme is known as ``filter-pattern'' TODO.
20
21By inserting additional ``filters'', the bootstrapping process can be customized
22without changing any of the involved programs:
23\codepar{db2osl mydatabase.org | customize\_uris.sh | osl2onto mydatabase.org}
24
25(supposed \name{customize\_uris.sh} is a shell script that modifies the URIs
26contained in an \osl{} specification in the manner the user desires).
27
28\subsubsection{Command-line arguments}
29The behavior of \myprog{} itself can be adjusted via command-line arguments.
30The syntax for their application follows the POSIX standard TODO.
31Most features can be configured via short options (as, for example, \code{-P}).
32To allow for enhanced readability of \myprog{} invocations, each feature can (also)
33be configured via a long option (like \code{\textendash\textendash password}).
34
35The command-line arguments \myprog{} currently supports and their effects are
36described in table \ref{if_tbl_arguments}.
37There currently is no switch to set the output format, since the only supported
38output format, besides \osl{}, is a low-level output format for debugging purposes.
39Because of this and since the change that has to be made in the source code to enable it
40only involves changing one token, it was preferred not to offer a command-line option
41for this, thus not unnecessarily complicating the command-line interface for the
42normal, non-debugging, user.
43
44\begin{table}[]\begin{center}
45 \begin{tabular}{l|l|l}
46 Option(s) & Description, taken from the help page of \myprog{} & Default value (if present)\\
47 \hline
48 \code{\textendash\textendash database, -d} & database name (Java regular expression) databases have to match to be processed; see also: \code{\textendash\textendash loose-database-match} & .*\\
49 \code{\textendash\textendash echo-password} & echo input when prompting for SQL password -- must be specified before \code{\textendash\textendash password-prompt} to get effective & false\\
50 \code{\textendash\textendash help, -h, } & show this help and exit & false\\
51 \code{\textendash\textendash interactive, -i} & be interactive when chosing database & false\\
52 \code{\textendash\textendash login, -L} & SQL login & anonymous\\
53 \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 & false\\
54 \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) & Default: <empty string>\\
55 \code{\textendash\textendash output-file, -o} & use the specified output file (for the standard output, specify ``-'') & -\\
56 \code{\textendash\textendash password, -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) & Default: <empty string>\\
57 \code{\textendash\textendash password-prompt, -p} & prompt for SQL password; a password set via \code{\textendash\textendash password} is ignored & false\\
58 \code{\textendash\textendash remote-osl-header, -R} & don't use hard-coded version of the OSL header for verification & false\\
59 \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) & false\\
60 \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) & false\\
61 \end{tabular}\\
62 \caption{Command-line arguments in \myprog{}}
63 \label{if_tbl_arguments}
64 \end{center}\end{table}
65
66The sole invocation of \myprog{}, without any arguments, does not initiate any processing
67but displays the usage directions instead, in addition to an error message.
68
69\subsubsection{Multiple bootstrapping operations or multiple servers}
70To perform multiple bootstrapping operations with one invocation of \myprog{},
71it is sufficient to concatenate the command-line arguments for each operation,
72separated by blanks, to get the final command line.
73However, when combining a test job with other operations, some arbitrary string has to be
74inserted as dummy server to allow distinguishing the different jobs and assigning
75each command-line argument to the appropriate job.
76
77On the other hand, to check several servers in order for the database to be used
78for one bootstrapping operation, these servers have to be concatenated,
79separated by blanks.
80Again, the distinction of the different bootstrapping jobs has to be possible,
81so all but the first operation have to have at least one command-line argument
82(which is no practical problem, since to enforce this, a default argument simply
83can be stated explicitly without changing the behavior of the invocation).
84
85All settings are configured per operation, so, when using a shell that separates batched
86commands by `;',
87\codepar{db2osl \textendash\textendash database employees \textendash\textendash
88 password itsme sql.myemployer.com\\
89 \textendash\textendash database test myserver.org backup.myserver.org}
90is equivalent to
91\codepar{db2osl \textendash\textendash database employees \textendash\textendash
92 password itsme sql.myemployer.com;\\
93 db2osl \textendash\textendash database test myserver.org backup.myserver.org}
94
95Thus, currently
96
97\subsection{Integration into systems}
98TODO: modularity -> reusability
99TODO: logger
100TODO: operating system -> Java