-\section{Interface}
+\section{Interface and usage}
\label{interface}
This section describes the interface to the operating system and the user interface.
For information on programming interfaces, see section \fullref{arch}.
\subsection{User interaction and configuration}
\subsubsection{Basic usage}
+\label{basic}
Currently, the only user interface of \myprog{} is a command-line interface.
Since the program is supposed to bootstrap the OBDA Specification automatically and
thus there is little interaction, but a lot of output, this was considered ideal.
+Basically, one invocation of \myprog{} will initiate the automatic, non-interactive
+bootstrapping of exactly one \osl{} specification written to the standard output,
+a behavior which can be modified via command-line arguments.
Because of its ability to write to the standard output (which is also the default
-behavior), it is easy to pipe the output of \myprog{} directly to a program that
+behavior), it is easy to pipe the output of \myprog{} directly into a program that
handles it in a Unix-/POSIX-like fashion TODO:
\codepar{db2osl myserver.org | osl2onto myserver.org}
By inserting additional ``filters'', the bootstrapping process can be customized
without changing any of the involved programs:
-\codepar{db2osl mydatabase.org | customize\_uris.sh | osl2onto mydatabase.org}
+\codepar{db2osl mydatabase.org | customize\_spec.sh | osl2onto mydatabase.org}
-(supposed \name{customize\_uris.sh} is a shell script that modifies the URIs
-contained in an \osl{} specification in the manner the user desires).
+(supposed \name{customize{\scriptsize \_}spec.sh} is a shell script that modifies
+a given \osl{} specification in the way the user desires).
-\subsubsection{Command-line arguments}
-The behavior of \myprog{} itself can be adjusted via command-line arguments.
+\subsubsection{Configuration via command-line arguments}
+The behavior of \myprog{} itself can be adjusted via command-line arguments (only).
The syntax for their application follows the POSIX standard TODO.
Most features can be configured via short options (as, for example, \code{-P}).
To allow for enhanced readability of \myprog{} invocations, each feature can (also)
be configured via a long option (like \code{\textendash\textendash password}).
+The utilization of configuration files was considered, but for the time being
+seen as unnecessary complicating
+while not addressing any real difficulties.
-The command-line arguments \myprog{} currently supports and their effects are
-described in table \ref{if_tbl_arguments}.
-There currently is no switch to set the output format, since the only supported
+The command-line arguments \myprog{} currently supports are
+described in table \ref{if_tbl_arguments_desc},
+their default values are listed in table \ref{if_tbl_arguments_def}.
+There is currently no switch to set the output format, since the only supported
output format, besides \osl{}, is a low-level output format for debugging purposes.
Because of this and since the change that has to be made in the source code to enable it
only involves changing one token, it was preferred not to offer a command-line option
-for this, thus not unnecessarily complicating the command-line interface for the
+for this, to not unnecessarily complicating the command-line interface for the
normal, non-debugging, user.
\begin{table}[]\begin{center}
- \begin{tabular}{l|l|l}
- Option(s) & Description, taken from the help page of \myprog{} & Default value (if present)\\
+ \begin{tabular}{p{4.9cm}|p{11.1cm}}
+ Option(s) & Description, taken from the help page of \myprog{}\\
\hline
- \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} & .*\\
- \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\\
- \code{\textendash\textendash help, -h, } & show this help and exit & false\\
- \code{\textendash\textendash interactive, -i} & be interactive when chosing database & false\\
- \code{\textendash\textendash login, -L} & SQL login & anonymous\\
- \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\\
- \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>\\
- \code{\textendash\textendash output-file, -o} & use the specified output file (for the standard output, specify ``-'') & -\\
- \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>\\
- \code{\textendash\textendash password-prompt, -p} & prompt for SQL password; a password set via \code{\textendash\textendash password} is ignored & false\\
- \code{\textendash\textendash remote-osl-header, -R} & don't use hard-coded version of the OSL header for verification & false\\
- \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\\
- \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\\
+ \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}\\
+ \code{\textendash\textendash echo-password} & echo input when prompting for SQL password -- must be specified before \code{\textendash\textendash password-prompt} to get effective\\
+ \code{\textendash\textendash help}, \code{-h, } & show this help and exit\\
+ \code{\textendash\textendash interactive}, \code{-i} & be interactive when chosing database\\
+ \code{\textendash\textendash login}, \code{-L} & SQL login\\
+ \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\\
+ \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)\\
+ \code{\textendash\textendash output-file}, \code{-o} & use the specified output file (for the standard output, specify ``-'')\\
+ \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)\\
+ \code{\textendash\textendash password-prompt}, \code{-p} & prompt for SQL password; a password set via \code{\textendash\textendash password} is ignored\\
+ \code{\textendash\textendash remote-osl-header}, \code{-R} & don't use hard-coded version of the OSL header for verification\\
+ \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)\\
+ \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)\\
\end{tabular}\\
- \caption{Command-line arguments in \myprog{}}
- \label{if_tbl_arguments}
+ \caption{Command-line arguments in \myprog{} -- descriptions}
+ \label{if_tbl_arguments_desc}
\end{center}\end{table}
-The sole invocation of \myprog{}, without any arguments, does not initiate any processing
-but displays the usage directions instead, in addition to an error message.
+\begin{table}[]\begin{center}
+ \begin{tabular}{l|l}
+ Option(s) & Default value\\
+ \hline
+ \code{\textendash\textendash database, -d} & \code{.*}\\
+ \code{\textendash\textendash echo-password} & \code{false}\\
+ \code{\textendash\textendash help, -h, } & \code{false}\\
+ \code{\textendash\textendash interactive, -i} & \code{false}\\
+ \code{\textendash\textendash login, -L} & \code{anonymous}\\
+ \code{\textendash\textendash loose-database-match} & \code{false}\\
+ \code{\textendash\textendash osl-header} & \code{<empty string>}\\
+ \code{\textendash\textendash output-file, -o} & \code{-}\\
+ \code{\textendash\textendash password, -P} & \code{<empty string>}\\
+ \code{\textendash\textendash password-prompt, -p} & \code{false}\\
+ \code{\textendash\textendash remote-osl-header, -R} & \code{false}\\
+ \code{\textendash\textendash remote-test} & \code{false}\\
+ \code{\textendash\textendash test} & \code{false}\\
+ \end{tabular}\\
+ \caption{Command-line arguments in \myprog{} -- default values}
+ \label{if_tbl_arguments_def}
+ \end{center}\end{table}
+
+The sole invocation of \code{db2osl}, without any arguments, does not initiate any
+processing but displays the usage directions instead, in addition to an error message
+pointing out the missing server argument.
\subsubsection{Multiple bootstrapping operations or multiple servers}
-To perform multiple bootstrapping operations with one invocation of \myprog{},
+To perform multiple bootstrapping operations with only one invocation of \myprog{},
it is sufficient to concatenate the command-line arguments for each operation,
separated by blanks, to get the final command line.
-However, when combining a test job with other operations, some arbitrary string has to be
-inserted as dummy server to allow distinguishing the different jobs and assigning
-each command-line argument to the appropriate job.
+However, when combining a test job with other operations, some arbitrary string
+has to be inserted as dummy server to allow distinguishing the different jobs
+and assigning each command-line argument to the appropriate job.
-On the other hand, to check several servers in order for the database to be used
+Likewise, to check several servers in order for the database to be used
for one bootstrapping operation, these servers have to be concatenated,
separated by blanks.
Again, the distinction of the different bootstrapping jobs has to be possible,
so all but the first operation have to have at least one command-line argument
+that signals the beginning of a new job definition
(which is no practical problem, since to enforce this, a default argument simply
can be stated explicitly without changing the behavior of the invocation).
password itsme sql.myemployer.com;\\
db2osl \textendash\textendash database test myserver.org backup.myserver.org}
-Thus, currently
+Thus, a parameter defined for one operation (like the password
+in the example) will have no effect on other operations.
+This ensures that typical errors are prevented when merging several invocations
+of \myprog{} into one (or vice versa)
+and allows for a straight-forward, comprehensive and clean implementation.
+
+\subsubsection{Advanced modifications}
+Since \osl{} specifications are plain text files, a user can edit them in any desired
+text editor if he wants to change them in ways that go beyond the functionality
+\myprog{} provides or that can be achieved by scripts or programs modifying their
+input automatically.
+Because of \osl{} being defined to be a subset of \name{OWL} (see the specification
+of \osl{} in section \ref{oslspec}), he can thereby take advantage of editors
+supporting syntax highlighting or other features making the handling of
+the respective \name{OWL} serialization more comfortable.
+
+Moreover, every common ontology editor can be used to edit the generated \osl{}
+specification automatically or manually.
+Doing so, care has to be taken to make the ontology remain a conforming \osl{}
+specification. However, since the restrictions imposed by \osl{} are rather
+small and intuitive, this is easily achieved.
+Furthermore, upcoming tools supporting \osl{} (see section \fullref{future}) are very
+likely to be able to check their input for conformity with the \osl{} definition.
\subsection{Integration into systems}
-TODO: modularity -> reusability
-TODO: logger
-TODO: operating system -> Java
+Besides the use cases described in section ``\nameref{basic}'',
+there are many other ways in which \myprog{} can be used.
+For example, a database can be periodically checked for changes that make a
+re-bootstrapping necessary:
+\codepar{db2osl -d mydb myserver.org | sha256sum >oldsum\\
+ cp oldsum newsum\\
+ while diff oldsum newsum; do\\
+ \ind sleep 3600\ \ \# wait 1 hour\\
+ \ind db2osl -d mydb myserver.org | sha256sum >newsum\\
+ done\\
+ rm oldsum newsum\\
+ \# notify web admin via e-mail:\\
+ mutt -s "Re-bootstrapping necessary" web-admin@myserver.org}
+
+Another possible example is the integration of \myprog{} into a shell script
+that bootstraps all databases on a server:
+\codepar{regex=\textquotesingle(?!\$).*\textquotesingle\ \ \# accept all nonempty database names first\\
+ while db2osl -d "\$regex" -o spec myserver.org; do\\
+ \ind dbname="\`{} sed -ne \textquotesingle/xmlns:ont/ \{ s|.*/||; s|\#"||p \}\textquotesingle\ spec \`{}"\\
+ \ind mv spec "\$dbname".osl\\
+ \ind \# don't use this database a second time:\\
+ \ind regex="\`{} printf \%s "\$regex" | sed -e "s,\textbackslash\textbackslash\textbackslash\textbackslash\$,\$|\$dbname\$," \`{}"\\
+ done}
+
+Newer versions than version 1.0 described here provide a command-line parameter
+\code{-a} (or, alternatively, \code{\textendash \textendash all)}
+which makes \myprog{} bootstrap \emph{all} databases matching the given
+regular expression.
+However, using this approach, all bootstrapped specifications will be output
+to one single file.
+
+Since the programming language used to implement \myprog{} is \name{Java},
+it is possible to deploy it on all platforms offering the
+\name{Java Runtime Environment} TODO.
+Additionally, it is possible to deploy it as a Web application TODO.
+
+To simplify integration on the code level, the architecture of \myprog{} was
+designed to be highly modular and to cleanly separate code with different areas of
+responsibility into different packages
+(for details about the structuring of \myprog{}, see section \fullref{arch}).
+This modularity, besides facilitating understanding the code,
+allows for a high degree of code reusability.
+
+For example, the packages \code{database}, \code{osl} and \code{specification}
+can be reused in other programs with little or no changes --
+the biggest change involves combining the database schema retrieval with the
+user interface of the new program to provide control over the retrieval process
+when reusing the \code{database} package
+(to do this, three method calls have to be replaced).
+%However, the \code{osl} package heavily depends on the \code{specification} package.
+If the accruing information shall be used in another way than being output or logged,
+this of course has to be implemented.
+If not, it is sufficient to replace the used \code{Logger} object by anohter one
+providing the desired behavior, since the \code{Logger} class is part of the
+\name{Java} API and widely used TODO.
+This is a good example of how using well-known and commonly used classes can
+greatly improve modularity and reusability.
git://git.uio.no / u / philim / db2osl_thesis.git / blobdiff