program_interface.tex

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