]>
Commit | Line | Data |
---|---|---|
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 | \subsubsection{Basic usage} | |
8 | \label{basic} | |
9 | Currently, the only user interface of \myprog{} is a command-line interface. | |
10 | Since the program is supposed to bootstrap the OBDA Specification automatically and | |
11 | thus there is little interaction, but a lot of output, this was considered ideal. | |
12 | Basically, one invocation of \myprog{} will initiate the automatic, non-interactive | |
13 | bootstrapping of exactly one \osl{} specification written to the standard output, | |
14 | a behavior which can be modified via command-line arguments. | |
15 | Because of its ability to write to the standard output (which is also the default | |
16 | behavior), it is easy to pipe the output of \myprog{} directly into a program that | |
17 | handles it in a Unix-/POSIX-like fashion TODO: | |
18 | \codepar{db2osl myserver.org | osl2onto myserver.org} | |
19 | ||
20 | (supposed \name{osl2onto} is a tool that reads an \osl{} specification from its | |
21 | standard input and uses it to bootstrap an ontology from the database | |
22 | specified on its command line).\\ | |
23 | This scheme is known as ``filter-pattern'' TODO. | |
24 | ||
25 | By inserting additional ``filters'', the bootstrapping process can be customized | |
26 | without changing any of the involved programs: | |
27 | \codepar{db2osl mydatabase.org | customize\_spec.sh | osl2onto mydatabase.org} | |
28 | ||
29 | (supposed \name{customize{\scriptsize \_}spec.sh} is a shell script that modifies | |
30 | a given \osl{} specification in the way the user desires). | |
31 | ||
32 | \subsubsection{Configuration via command-line arguments} | |
33 | The behavior of \myprog{} itself can be adjusted via command-line arguments (only). | |
34 | The syntax for their application follows the POSIX standard TODO. | |
35 | Most features can be configured via short options (as, for example, \code{-P}). | |
36 | To allow for enhanced readability of \myprog{} invocations, each feature can (also) | |
37 | be configured via a long option (like \code{\textendash\textendash password}). | |
38 | The utilization of configuration files was considered, but for the time being | |
39 | seen as unnecessary complicating | |
40 | while not addressing any real difficulties. | |
41 | ||
42 | The command-line arguments \myprog{} currently supports are | |
43 | described in table \ref{if_tbl_arguments_desc}, | |
44 | their default values are listed in table \ref{if_tbl_arguments_def}. | |
45 | There is currently no switch to set the output format, since the only supported | |
46 | output format, besides \osl{}, is a low-level output format for debugging purposes. | |
47 | Because of this and since the change that has to be made in the source code to enable it | |
48 | only involves changing one token, it was preferred not to offer a command-line option | |
49 | for this, to not unnecessarily complicating the command-line interface for the | |
50 | normal, non-debugging, user. | |
51 | ||
52 | \begin{table}[]\begin{center} | |
53 | \begin{tabular}{p{4.9cm}|p{11.1cm}} | |
54 | Option(s) & Description, taken from the help page of \myprog{}\\ | |
55 | \hline | |
56 | \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}\\ | |
57 | \code{\textendash\textendash echo-password} & echo input when prompting for SQL password -- must be specified before \code{\textendash\textendash password-prompt} to get effective\\ | |
58 | \code{\textendash\textendash help}, \code{-h, } & show this help and exit\\ | |
59 | \code{\textendash\textendash interactive}, \code{-i} & be interactive when chosing database\\ | |
60 | \code{\textendash\textendash login}, \code{-L} & SQL login\\ | |
61 | \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\\ | |
62 | \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)\\ | |
63 | \code{\textendash\textendash output-file}, \code{-o} & use the specified output file (for the standard output, specify ``-'')\\ | |
64 | \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)\\ | |
65 | \code{\textendash\textendash password-prompt}, \code{-p} & prompt for SQL password; a password set via \code{\textendash\textendash password} is ignored\\ | |
66 | \code{\textendash\textendash remote-osl-header}, \code{-R} & don't use hard-coded version of the OSL header for verification\\ | |
67 | \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)\\ | |
68 | \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)\\ | |
69 | \end{tabular}\\ | |
70 | \caption{Command-line arguments in \myprog{} -- descriptions} | |
71 | \label{if_tbl_arguments_desc} | |
72 | \end{center}\end{table} | |
73 | ||
74 | \begin{table}[]\begin{center} | |
75 | \begin{tabular}{l|l} | |
76 | Option(s) & Default value\\ | |
77 | \hline | |
78 | \code{\textendash\textendash database, -d} & \code{.*}\\ | |
79 | \code{\textendash\textendash echo-password} & \code{false}\\ | |
80 | \code{\textendash\textendash help, -h, } & \code{false}\\ | |
81 | \code{\textendash\textendash interactive, -i} & \code{false}\\ | |
82 | \code{\textendash\textendash login, -L} & \code{anonymous}\\ | |
83 | \code{\textendash\textendash loose-database-match} & \code{false}\\ | |
84 | \code{\textendash\textendash osl-header} & \code{<empty string>}\\ | |
85 | \code{\textendash\textendash output-file, -o} & \code{-}\\ | |
86 | \code{\textendash\textendash password, -P} & \code{<empty string>}\\ | |
87 | \code{\textendash\textendash password-prompt, -p} & \code{false}\\ | |
88 | \code{\textendash\textendash remote-osl-header, -R} & \code{false}\\ | |
89 | \code{\textendash\textendash remote-test} & \code{false}\\ | |
90 | \code{\textendash\textendash test} & \code{false}\\ | |
91 | \end{tabular}\\ | |
92 | \caption{Command-line arguments in \myprog{} -- default values} | |
93 | \label{if_tbl_arguments_def} | |
94 | \end{center}\end{table} | |
95 | ||
96 | The sole invocation of \code{db2osl}, without any arguments, does not initiate any | |
97 | processing but displays the usage directions instead, in addition to an error message | |
98 | pointing out the missing server argument. | |
99 | ||
100 | \subsubsection{Multiple bootstrapping operations or multiple servers} | |
101 | To perform multiple bootstrapping operations with only one invocation of \myprog{}, | |
102 | it is sufficient to concatenate the command-line arguments for each operation, | |
103 | separated by blanks, to get the final command line. | |
104 | However, when combining a test job with other operations, some arbitrary string | |
105 | has to be inserted as dummy server to allow distinguishing the different jobs | |
106 | and assigning each command-line argument to the appropriate job. | |
107 | ||
108 | Likewise, to check several servers in order for the database to be used | |
109 | for one bootstrapping operation, these servers have to be concatenated, | |
110 | separated by blanks. | |
111 | Again, the distinction of the different bootstrapping jobs has to be possible, | |
112 | so all but the first operation have to have at least one command-line argument | |
113 | that signals the beginning of a new job definition | |
114 | (which is no practical problem, since to enforce this, a default argument simply | |
115 | can be stated explicitly without changing the behavior of the invocation). | |
116 | ||
117 | All settings are configured per operation, so, when using a shell that separates batched | |
118 | commands by `;', | |
119 | \codepar{db2osl \textendash\textendash database employees \textendash\textendash | |
120 | password itsme sql.myemployer.com\\ | |
121 | \textendash\textendash database test myserver.org backup.myserver.org} | |
122 | is equivalent to | |
123 | \codepar{db2osl \textendash\textendash database employees \textendash\textendash | |
124 | password itsme sql.myemployer.com;\\ | |
125 | db2osl \textendash\textendash database test myserver.org backup.myserver.org} | |
126 | ||
127 | Thus, a parameter defined for one operation (like the password | |
128 | in the example) will have no effect on other operations. | |
129 | This ensures that typical errors are prevented when merging several invocations | |
130 | of \myprog{} into one (or vice versa) | |
131 | and allows for a straight-forward, comprehensive and clean implementation. | |
132 | ||
133 | \subsubsection{Advanced modifications} | |
134 | Since \osl{} specifications are plain text files, a user can edit them in any desired | |
135 | text editor if he wants to change them in ways that go beyond the functionality | |
136 | \myprog{} provides or that can be achieved by scripts or programs modifying their | |
137 | input automatically. | |
138 | Because of \osl{} being defined to be a subset of \name{OWL} (see the specification | |
139 | of \osl{} in section \ref{oslspec}), he can thereby take advantage of editors | |
140 | supporting syntax highlighting or other features making the handling of | |
141 | the respective \name{OWL} serialization more comfortable. | |
142 | ||
143 | Moreover, every common ontology editor can be used to edit the generated \osl{} | |
144 | specification automatically or manually. | |
145 | Doing so, care has to be taken to make the ontology remain a conforming \osl{} | |
146 | specification. However, since the restrictions imposed by \osl{} are rather | |
147 | small and intuitive, this is easily achieved. | |
148 | Furthermore, upcoming tools supporting \osl{} (see section \fullref{future}) are very | |
149 | likely to be able to check their input for conformity with the \osl{} definition. | |
150 | ||
151 | \subsection{Integration into systems} | |
152 | Besides the use cases described in section ``\nameref{basic}'', | |
153 | there are many other ways in which \myprog{} can be used. | |
154 | For example, a database can be periodically checked for changes that make a | |
155 | re-bootstrapping necessary: | |
156 | \codepar{db2osl -d mydb myserver.org | sha256sum >oldsum\\ | |
157 | cp oldsum newsum\\ | |
158 | while diff oldsum newsum; do\\ | |
159 | \ind sleep 3600\ \ \# wait 1 hour\\ | |
160 | \ind db2osl -d mydb myserver.org | sha256sum >newsum\\ | |
161 | done\\ | |
162 | rm oldsum newsum\\ | |
163 | \# notify web admin via e-mail:\\ | |
164 | mutt -s "Re-bootstrapping necessary" web-admin@myserver.org} | |
165 | ||
166 | Another possible example is the integration of \myprog{} into a shell script | |
167 | that bootstraps all databases on a server: | |
168 | \codepar{regex=\textquotesingle(?!\$).*\textquotesingle\ \ \# accept all nonempty database names first\\ | |
169 | while db2osl -d "\$regex" -o spec myserver.org; do\\ | |
170 | \ind dbname="\`{} sed -ne \textquotesingle/xmlns:ont/ \{ s|.*/||; s|\#"||p \}\textquotesingle\ spec \`{}"\\ | |
171 | \ind mv spec "\$dbname".osl\\ | |
172 | \ind \# don't use this database a second time:\\ | |
173 | \ind regex="\`{} printf \%s "\$regex" | sed -e "s,\textbackslash\textbackslash\textbackslash\textbackslash\$,\$|\$dbname\$," \`{}"\\ | |
174 | done} | |
175 | ||
176 | Newer versions than version 1.0 described here provide a command-line parameter | |
177 | \code{-a} (or, alternatively, \code{\textendash \textendash all)} | |
178 | which makes \myprog{} bootstrap \emph{all} databases matching the given | |
179 | regular expression. | |
180 | However, using this approach, all bootstrapped specifications will be output | |
181 | to one single file. | |
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 TODO. | |
207 | This is a good example of how using well-known and commonly used classes can | |
208 | greatly improve modularity and reusability. |