%nicht vergessen: auch sdd.tex ($Revision $) \"andern !

 \chapter{Software Design Document}

 \section{The Worksheet}

 %WN --- vvv -----------------Kopie aus UseCases am 2.9.02-----------------

 The worksheet is the component responsible for interaction with the user while doing a claculation.

 The functionality is split between a worksheet presentation layer (WPL) and the worksheet dialog guide (WDG). This makes it possible to change the logic of user-interaction (WDG) and the presentation or skin (WPL) independently from each other.

 The WPL is responsible for visible presentation of data (like formulas in a calculation) and user-interface objects (like buttons or menus). Moreover, the WPL accepts input from the user.

 The WDG makes decisions on which data and which choices of user-interaction to present in which order, depending on the role (student, teacher, author, ...), the preferences and the history of the user.

 \subsection{Elements of user-interaction}

 Any of the following elements can be activated by the user (e.g. clicked with a mouse) to get a choice of actions offered for the respective item. The actions available are determined by the WDG. The choice can be empty as well. 

 \begin{itemize}

 \item \textbf{Menus} in the usual sense of the word are filled in by the WDG. Several "types" of menus will be offered, including:

 \begin{itemize}

 \item global settings

 \item display options

 \item calculation options

 \item user profile

 \end{itemize}

 \item \textbf{Formulas} are the visual representation of mathematical formulas.

 Actions offered on formulas include:

 \begin{itemize}

 \item Edit

 \item Collapse (minimize) / Show

 \item Propose a tactic

 \item Make current

 \item Highlight

 \end{itemize}

 \item \textbf{Tactics} are rules applied to a formula yielding another formula (the next formula in the course of calculation).

 Actions offered on tactics include:

 \begin{itemize}

 \item Edit

 \item Choose from list of applicable tactics

 \item Get information from knowledge base

 \end{itemize}

 \end{itemize}

 \subsection{Data stored and manipulated by the WDG}

 \subsubsection{Draft for an user-model}

 The user-model stores an abstraction of the knowledge, abilities and learning progress of a user, based upon his history of interaction with \isac{} as well as his personal preferences and restrictions set by teachers and course designers. The user-model is persistent across sessions.

 At the moment, the uses of the user-model and the implications for the data abstractions stored cannot be foreseen in every detail. To avoid prejudicing decisions to be taken by dialog designers, the user model is designed to store data at a rather low level of abstraction suitable for being combined into high-level equivalents at a later time. Moreover, a mechanism transparent to future extensions is preferred.

 Elements of the user model envisioned at present include:

 \begin{itemize}

 \item \textbf{Specific examples already done by the user} will be logged together with information about success or failure. This "history" can be used to deduce flexible strategies for user-guidance.

 \item \textbf{Errors typical to the user} will be included as soon as a comprehensive classification of common errors is implemented in the system. This information can be used to automatically choose specific examples to be practised.

 \item \textbf{Tactics considered no longer interesting to the user} will be used to reduce the complexity of user-interaction by omitting steps in the calculation trivial to the specific user. Tactics having been applied several times withot error could be considered trivial in this sense of the word.

 \item \textbf{Tactics to be practised by the user} will be used to choose specific examples or to leave parts of the calculation blank to be filled in by the user.

 \item \textbf{Specific examples to be done by the user}

 \end{itemize}

 Preferences about the visual representation such as colors, fonts or visual layout of the worksheet depend heavily on the capabilities of the WPL and will be stored separately.

 Depending on the role and permissions of the user, some of these user-model data could be set directly by the user according to his preferences, whereas othe data may be modified only by the system or a privileged teacher.

 \subsubsection{Dialog state}

 The dialog state stores the momentary state of interaction in the current session.

 \subsection{The object world of the worksheet component}

 \subsubsection{The dialog guide object}

 Its local data represent the current state of the dialog. It has methods for interacting with the user at different levels of abstraction and for being queried about its interpretation of the proof tree.

 \subsubsection{The user model object}

 \subsubsection{The presentation layer object}

 The presentation layer object is an abstraction of the visible worksheet.

 It has methods for

 \begin{itemize}

 \item redisplaying itself

 \item showing menus, buttons and other objects of user-interaction

 \item highlighting parts of the displayed calculation

 \item editing the hot spot of the calculation

 \item being notified of changes in the data displayed

 \end{itemize} 

 It does not have methods for directly changing the data displayed, but reacts to update notifications by re-querying the data. 

 It notifies other objects of

 \begin{itemize}

 \item actions (e.g. mouse clicks) on the displayed elements

 \item completed edit operations

 \end{itemize} 

 \subsubsection{The proof tree object}

 The proof tree object represents a proof or course of calculation, consisting of a problem specification and a series of formulas an tactics.

 It has methods for

 \begin{itemize}

 \item being initialized with a problem specification

 \item checking a problem specification for completeness and consistency

 \item being queried about its inner structure (i.e. formulas and tactics)

 \item changing itself by doing steps in a calculation

 \item changing itself by adding detail to a step in the calculation, leaving the rest of the tree consistent and unchanged

 \item finding the origins of conditions, yielding highlights indicating the tactics which introduced a condition

 \item setting the hot spot, i.e. the current formula or tactic

 \item changing the data at the hot spot and verifying the consistency of the resulting proof

 \end{itemize} 

 It can notify other objects of updates, optionally indicating parts of the tree left unchanged.

 \subsubsection{The proof element selector object}

 The proof element selector object is intended for selecting a formula or a tactic in a proof. Its implementation is closely interwoven with the proof tree object.

 It has methods for

 \begin{itemize}

 \item attaching and detaching a proof tree

 \item navigating the attached proof tree, i.e. selecting a formula or tactic. Navigation is done by methods like the following 

 \begin{itemize}

 \item root - select the first formula

 \item down - select the next formula

 \item up - select previous formula

 \item tactic - select the tactic yielding the currently selected formula

 \item formula - select the formula resulting from the currently selected tactic

 \end{itemize} 

 \item extracting the selected formula yielding a new formula object

 \item extracting the selected tactic yielding a new tactic object

 \end{itemize}

 \subsubsection{The formula object}

 The formula object is intended for storing one mathematical formula, i.e. a term consisting of constants, variables, operators and functions.

 While the internal storage is not transparent to the outside and follows requirements of the implementation, the object has methods for storing and retrieving the formula in at least two formats:

 \begin{itemize}

 \item retrieve the formula in MathML content format

 \item store the formula in MathML content format

 \item retrieve the formula in isabelle text format

 \item store the formula in isabelle text format

 \item given a subterm selector, retrieve the formula in MathML content format leaving the selected subterm blank for being filled in by the user

 \end{itemize}

 Other formats can be supported by adding respective store/retrieve methods.

 \subsubsection{The subterm selector object}

 The subterm selector object is intended for selecting a subterm of a formula. Its implementation is closely interwoven with the formula object.

 It has methods for

 \begin{itemize}

 \item attaching and detaching a formula

 \item navigating the attached formula, i.e. selecting different subterms. Navigation is done by methods like the following (please imagine the term being stored in a tree structure with operators as nodes and variables \& constants as leaves).

 \begin{itemize}

 \item root - select the whole term

 \item down - select the leftmost subterm of the currently selected term

 \item up - select the superterm of the currently selected term

 \item left - select the previous term on the same level

 \item right - select the next term on the same level

 \end{itemize} 

 \item extracting the selected formula yielding a new formula object

 \end{itemize}

 \subsubsection{The tactic object}

 The tactic object stores a rule for transforming one formula into another.

 Methods implemented include:

 \begin{enumerate}

 \item retrieve the name of the tactic

 \item retrieve a short description of the tactic

 \item retrieve a formula illustrating the tactic, if available

 \item given a formula \textit{f} the tactic is applied to, retrieve a formula illustrating the application of the tactic on \textit{f}

 \end{enumerate} 

 \subsubsection{The problem specification object}

 \subsubsection{The menu object}

 \subsubsection{The worksheet highlight object}

 The worksheet highlight object is to the proof displayed on the worksheet what the proof element seletor object is to the proof tree. It is not yet clear whether both objects can be merged into one.

 \subsection{Interfacing with the worksheet}

 \subsection{Interface WPL-WDG}

 \subsubsection{Actions executed by the WPL on behalf of the WDG}

 \begin{itemize}

 \item \textbf{Redisplay tree}

 \item \textbf{Set active formula}

 \item \textbf{Highlight parts of the calculation}

 \item \textbf{Expand or collapse parts of the calculation}

 \item \textbf{Edit the current formula}

 \item \textbf{Choose a tactic from a list of applicable tactics}

 \item \textbf{Choose a tactic from the knowledge base}

 \item \textbf{Open Knowledge Browser}

 \item \textbf{Offer a menu of choices}

 \end{itemize}

 \subsubsection{User events passed from WPL to WDG}

 \begin{itemize}

 \item \textbf{Editing of formula completed}

 \item \textbf{Editing of tactic completed}

 \item \textbf{Menu item selected}

 \end{itemize}

 \subsection{Interface WDG-ME}

 \subsubsection{Actions executed by the ME on behalf of the WDG}

 Actions related to a specific calculation (proof-tree):

 \begin{itemize}

 \item \textbf{Set active formula}

 \item \textbf{Modifiy active formula}

 \item \textbf{Set next tactic}

 \item \textbf{Calculate one step}

 Apply the current tactic.

 \item \textbf{Calculate to the end of the current sub-problem}

 \item \textbf{Calculate to the end of the current problem}

 \item \textbf{Find origin of a condition}

 \end{itemize}

 Actions not related to a specific calculation (proof-tree):

 \begin{itemize}

 \item \textbf{Initialize calculation with a problem specification}

 \item \textbf{Mark parts of a formula suitable for being filled in by the student}

 \end{itemize}

 \subsubsection{Calculational events passed from ME to WDG}

 \begin{itemize}

 \item \textbf{Tree updated}

 \item \textbf{Calculation completed}

 Success.

 \item \textbf{Failure/Error condition}

 \end{itemize}

 \subsection{Interface WDG-Knowledge Browser}

 The WDG and the Knowledge Browser communicate at a rather high level of abstraction, contacting an instance of the other component and setting a starting point for further action.

 \subsubsection{WDG used by the Knowledge Browser}

 \begin{itemize}

 \item \textbf{Create a new Worksheet and initialize it to present an example from the Knowledge Base}

 \end{itemize} 

 \subsubsection{Knowledge Browser used by the WDG}

 \begin{itemize}

 \item \textbf{Use a new or existing KB Window to browse the KB, starting at a point specified by the item highlighted in the Worksheet.}

 \end{itemize} 

 \subsection{Resulting software design considerations for a worksheet component}

 \textbf{The contents of this section is OBSOLETE and kept temporarily for reference.}

 In this section, when IDs are mentioned, this is to be taken as a proposal.

 ID in this context means ``a way of passing access to a object''.

 Function prototypes are used as a short way of titling a paragraph, not as a definition of an interface.

 \subsubsection{Services/Methods offered by the worksheet component}

 \begin{itemize}

 \item \textbf{redisplay()} Redraws the display on demand from other components or

 the user. 

 \item \textbf{update(idFormulaFrom)} Notifies the worksheet of a change in the prooftree.

 The ID of the last unchanged formula is passed. The display will be updated

 to reflect the changes. Optionally, there could be a flag passing information

 whether the calculation is still in progress or the last requested calculation

 has completed. 

 \item \textbf{expand(idFormulaFrom, idFormulaTo)} (optional) Expands part of the prooftree,

 if collapsed. It is not decided yet whether other components will need a way

 of collapsing/expandig parts of the prooftree display. 

 \item \textbf{collapse(idFormulaFrom, idFormulaTo)} (optional) Collapses part of the

 prooftree, if expanded. \par\centering \resizebox*{11cm}{!}{\includegraphics{fig/design_alan.eps} 

 } \par{}

 \begin{figure}

 \caption{Environment for the worksheet component}

 \end{figure}

 \end{itemize}

 \subsubsection{Services/Methods needed by the worksheet component}

 Services needed for displaying the prooftree: Given a reference to a prooftree,

 the worksheet will manage its display starting from the ``top'', by asking

 (on demand) the prooftree for further elements of the tree.

 \begin{itemize}

 \item \textbf{idFormula getFirstFormula()} Get the ID of the first formula in the

 prooftree. 

 \item \textbf{idFormula getNextFormula(idFormulaCurrent)} Get the ID of the next formula

 in the prooftree, given the current formula. 

 \item \textbf{idTactic getTactic(idFormulaCurrent)} Get the ID of the next tactic

 in the prooftree, given the current formula. A special case arises if the tactic

 to continue the current calculation is solving a \textbf{subproblem}. The subproblem

 is a claculation on its own, represented by a separate proof(sub-)tree. The

 ID of the prooftree representing the subproblem is passed to the worksheet.

 The worksheet will handle the situation accordingly, e.g. by opening a new worksheet

 or displaying the (indented) new prooftree in the current worksheet. 

 \end{itemize}

 Services needed for controlling the progress of calculation: The worksheet controls

 the calculation by modifying the behaviour at the hot spot in the calculation,

 the selcted active formula.

 \begin{itemize}

 \item \textbf{setActiveFormula(idFormula)} Makes the passed formula the active formula,

 i.e. the formula the next tactic is applied to. 

 \item \textbf{indAccepted setEnteredFormula(idFormula)} Tries to replaces the active

 formula in the prooftree by the passed formula. This could fail if no valid

 derivation from the preceding formula to the (new) active formula can be found. 

 \item \textbf{setNextTactic(idTactic)} Set the tactic to be used in the next step

 of calculation. 

 \item \textbf{idTactic getProposedTactic()} Get the tactic proposed by the mathematics

 engine for the next step in the calculation. 

 \item \textbf{listTactics getApplicableTactics()} Get a list of tactics applicable

 to the active formula. 

 \item \textbf{autoCalculate(nSteps)} Calculate the next n steps starting from the

 active formula. 

 \end{itemize}

 Services to handle the underlying formalization have to be discussed and added

 yet.

 \begin{itemize}

 \item \textbf{idFormula getFirstFormula()} Get the ID of the first formula in the

 prooftree. 

 \item \textbf{idFormula getNextFormula(idFormulaCurrent)} Get the ID of the next formula

 in the prooftree, given the current formula. 

 \item \textbf{idTactic getTactic(idFormulaCurrent)} Get the ID of the next tactic

 in the prooftree, given the current formula. 

 \end{itemize}

 Services needed for controlling the progress of calculation: The worksheet controls

 the calculation by modifying the behaviour at the hot spot in the calculation,

 the selcted active formula.

 \begin{itemize}

 \item \textbf{setActiveFormula(idFormula)} Makes the passed formula the active formula,

 i.e. the formula the next tactic is applied to. 

 \item \textbf{setNextTactic(idTactic)} Set the tactic to be used in the next step

 of calculation. 

 \item \textbf{idTactic getProposedTactic()} Get the tactic proposed by the mathematics

 engine for the next step in the calculation. 

 \item \textbf{listTactics getApplicableTactics()} Get a list of tactics applicable

 to the active formula. 

 \item \textbf{autoCalculate(nSteps)} Calculate the next n steps starting from the

 active formula. 

 \end{itemize}

 Services to handle the underlying formalization have to be discussed and added

 yet.

 %WN --- ^^^ -----------------Kopie aus UseCases am 2.9.02-----------------

 \subsection{Draft for an interaction diagram}

 \begin{itemize}

 \item they are tired and ask the system to finish the calculation (automated calculation)

 \item they know the next step and type in a tactic (input a tactic)

 \item they want to find out the next step and request a list of tactics (list of tactics)

 \item they want to find out the next step and lookup the knowledge base (look-up knowledge)

 \item they input a formula as the next step (input a formula)

 \end{itemize}

 These choices are described in the respective use cases below, where 'student' is abbreviated by S, the worksheet is abbreviated by WS, the maths engine by ME, and the dialog guide by DG.

 \paragraph{Automated calculation} can be requested, if the proofstate is 'safe' (indicated by ???), i.e. if the students didn't do a misleading step before in this calculation, and the system thus 'knows' how to continue.

 \begin{enumerate}

 \item S pushes a button {\it Auto} on the WS 

 \item {\it Auto} sends the request {\it autoCalculate(nSteps)} to the ME %WN ODER:to the proofstate ???

 where {\it nSteps} are provided by the DG %WN(wenn vom DG, sollen wir da gleich genauer sein), oder: by the user ???

 \item the ME notifies the WS by {\it redisplay()} that the proofstate has changed

 \item the WS %WN ODER wer 'considers ...' ?

 considers the actual presentation of the proofstate (e.g. if the previously current formula is still visible), and eventually requests {\it getFromTo(currForm,Endproof)}  %WN... das find ich nicht mehr, sowas \"ahnliches haben wir aber gehabt, oder ???

 from the ME

 \end{enumerate}

 \paragraph{Input a tactic} is possible any time in order to propagate the calculation from the current formula towards the result.

 \begin{enumerate}

 \item S inputs the tactic, where the WS distinguishes the input of a tactic - eventually containing formulas - from input of a formula belonging to the calculation

 \item the WS requests {\it setNextTactic(idTactic)} from the ME

 \item the ME notifies the WS by {\it redisplay()} that the proofstate has changed by appending (or inserting) the formula resulting from the input tactic to the proofstate

 \item the WS eventually requests {\it getFromTo(currForm,oneForm)} in order to display the resulting formula

 \end{enumerate}

 \paragraph{List of tactics} can be requested any time in order to receive suggestions how to proceed with the calculation. Depending on the setting of the DG, only the tactics applicable to the current formula are displayed, or some larger list.

 \begin{enumerate}

 \item S pushes a button {\it Tactics} on the worksheet

 \item the WS requests {\it getTactics(Applicable)} %WN Applicable?!

 from the ME, which returns {\it idsTactics}, a list of tactics

 \item the WS performs {\it displayTactics} %WN ???

  displaying the list in such a position on the screen, that the current formula is not covered

 \item S selects a tactic from the list, and the WS requests {\it setNextTactic(idTactic)} from the ME

 \item \dots continuation as above

 \end{enumerate}

 \paragraph{Look-up knowledge} is possible any time during a calculation. In general the ME may provide for special views onto the knowledge base depending on the actual proofstate.  In this case the S wants to look for rules of differentiation, and we assume that there is no representation of the knowledgebase active.

 \begin{enumerate}

 \item S pushes a button {\it theories} %WN?!

 \item the WS requests {\it getCurrentTheory} %WN?!

 from the ME, which returns an {\it idTheory} %WN oder eine Liste von Theories ??? -- weiss ich selbst noch nicht genau

 \item the WS requests {\it getTheoryHierachy(idTheory)} %WN?!

 from the (???) knowledge browsers

 %WN: die Bezeichnungen 'WEB Browsers' und 'Browsers' in Andreas' Diagramm unterscheiden nicht klar genug zwischen Repr\"asentation und Steuerung; besser w\"are ???

 , which return a theory browser, with {\it idTheory} in the focus.

 \item S hits the focus, and the theory browser (???) requests {\it getTheory(idTheory)} %WN?!

 displaying the theory proposed by the ME

 \item after a while S selects the theorem {\it diff\_sum} in the theory browser, which sends the message {\it Selected(idTheorem)} to the WS

 \item the WS eventually performs {\it displayTactic} associating {\it Rewrite} and {\it diff\_sum} to the tactic {\it Rewrite diff\_sum} below the current formula

 \item {\it setNextTactic(idTactic)} as above \dots

 \end{enumerate}

 \paragraph{Input a formula} is interpreted as a derivation of the current formula w.r.t. the actual proofstate. The ME tries to construct this derivation (usually comprising several steps); in this case we assume that constructing the derivation is successful.

 \begin{enumerate}

 \item S inputs the formula, where the WS distinguishes the input of the formula from the input of a tactic (which may contain formulas, too)

 \item the WS requests {\it setNextFormula(idFormula)} %WN ?!

 from the ME

 \item the ME notifies the WS by {\it redisplay()} that the proofstate has changed by appending (or inserting) the formula resulting from the input tactic to the proofstate

 \item the WS eventually requests {\it getFromTo(currForm,nexEnd %WN??

 )} in order to display the resulting formula

 \end{enumerate}

 % WN-------------------------------------------------------------------------\\

 \subsection{}

 \subsection{}

 \subsection{}

 \section{The knowledge browsers}

 \label{SDD:knowledge_browser}

 %\subsection{knowledge browser}

 The knowledge browser mainly consists of three parts. 

 \begin{description}

   \item [Browser-Frontend = interface to the user] Is responsible to

   answer a user request, forward it to the next layer (processor)

   encode the result in a appropriate way and return it to the

   requestor. A HTML-browser-frontend will take the requests from the

   webbrowser and return HTML-Code to the browser-window. Other

   interfaces (like a shell like one) are conceivable.

   \item [processor] The processor has a set of functions to gather the

   correct informations to fulfill a frontends request. e.g. if a user

   browses the knowledge-base to select a problem, the processor asks

   the dialog for a problem description and a match result and returnes

   both to the encoder.

   The dialog to connect to is determined by the session which is given

   by the frontend. Access permissions are controlled by dinopolis ---

   the information-processor is only allowed to connect to the dialog

   if it was allowed to in first place (on login by the session-dialog)

   \item [dialog] adjust a processors request to a users needs and

   permissions. Each dialog has a usermodel assigned to log his history

   and get informations about his permissions. 

 \end{description}

 \begin{figure} [htb]

 \centerline{\psfig{figure=fig/browser_int.eps,width=11cm}}

 \caption{parts of the browser}

 \label{}

 \end{figure}

 The information processor can be replaced by a mock-object in the

 first development step. The ``mock information processor'' has to

 deliver example navigationtrees and the corresponding

 descriptions. So, the Information-Encoder can be developed and tested

 as disjoined Module.

 There is another advantage of splitting the Browser: We can excange

 the encoder part to present our information through other channels

 than HTML.

 \subsection{Browser Servlet}\label{SSD-browser-servelet}

  The servlet is activated whenever a User requests informations from

  the Browser. It decodes the request (URL), asks the \emph{Information

  Processor} for its infos and returns it using the \emph{Information

  Encoder} to present it.

  The browser-servlet is embedded within a servlet-engine

  (e.g. tomcat). The servlet-engine is working either as stand-alone

  webserver or collaborates with an running conventional web-server

  (e.g. apache). The running-mode of the servlet-engine does not affect

  the servlet - it communicates with the servlet-engine through

  well-defined interfaces. Because the running-mode depends on the

  needs of the \isac{}-host and not \isac{} itselve, the choice of its

  configuration is left to the hosts administrator.

  \subsubsection{request a problem-description} The request is

  recognized by the servlet-engine and forwarded to the servlet through

  its interface. Parameters contain the URL used to access the site as

  well as informations regarding the requestor. If the request occures

  the first time, the parameters have to contain a session-ID to

  determine the browser-dialog to connect to. If no session-ID is

  given, the sevlet can connect to a default browser-dialog which

  represents a ``default-user'' (or \emph{visitor}). Servlet-engines

  also support sessions to store informations about repeatedly

  connections. This feature can be used to store the dialog to

  connect. Note, that the first access has to contain the session-ID

  anyway\footnote{this can be fulfilled because the first authenticated

  access is always startet by an session-controller which first fetches

  the login-informations} and that the servlet-engines can only handle one

  session per instance of an webbrowser --- independently of the number

  of open browser-windows.

  The session-ID, the ID of the item to show and the presentation mode

  are used to gain the page-description from the

  information-processor. Missing informations are completed by the

  underlaying layers and does not bother the frontend. The returned

  informations can be used to generate a web-page in every case. In the

  worst case, the information-map contains a failure message to embed

  into an HTML-page.

  The information-encoder is used to generate a HTML-page out of the

  gained informations. Details to this process are given in section

  \ref{SDD:info_encoder}. The outcome of this method-call is the

  HTML-representation of the item to present and does not contain any

  navigational informations. The navigation tree has to be generated by

  an seperate method and is embedded when needed. The implementation

  depends of the structure of the resulting web-page. Either the

  navigation-tree is located in a seperate frame or it is delivered on

  every request. The decission is a matter of usability and should be

  left open till the usability can be tested. Therefore, content and

  navigation are built up seperatly and combined in the last step

  before deliveration to the web-browser.

  \subsubsection{needed methods}

 \begin{description}

   \item[String BrowserServlet.HTTP\_Request(URL)] This is a

   servlet-engine dependent method which is used by the servlet-engine

   to forward the request to the servlet\footnote{name and parameter

   might vary but the semantic of this method will be the same in all

   servlet-engines}. The URL and other context-informations (cookies

   and session-informations can be gailed from the environment) are

   used to encode the type (static, dynamic) of request and the

   information to present. This infos are used to forward the request

   to the \emph{information-processor}. The result of this request is

   combined with the navigation and returned to the servlet-engine (and

   thus to the browser-window).

   \item[HTMLText BrowserEncoder.encodeInformations(information\_map)]

     \ \\ see section \ref{SDD:info_encoder}

   \item[HTMLText BrowserEncoder.encodeNavigation(navigation\_map)]

     \ \\ see section \ref{SDD:info_encoder}

   \item[info\_map BProcessor.getInformation(session, descriptionID, mode)]

     \ \\ see section \ref{SDD:info_processor}

   \item[navigation\_map BProcessor.getNavigation(session, descriptionID)]

     \ \\ see section \ref{SDD:info_processor}

 \end{description}

 \subsection{Information encoder}

 \label{SDD:info_encoder}

 The information decoder knows about the way to present informations

 but does not have knowledge about the semantic of the

 informations. Informations are delivered inside a map. The keys are

 used to distinguish the different fields, the assigned values are then

 put into proper fields of templates. Because different kinds of

 information have to be displayed, a set of templates is used to

 generate the fitting HTML-page. Furthermore, there are some pages

 which require a strict layout rather than an automatically generated

 one (e.g. examples, example-collections). Therfore a first

 implementation might use predefined HTML-pages within the

 information-map while a more sophisticated version of the encoder

 might use a more general way to describe the layout

 (\emph{layout-hints}). 

 Besides the pure informations regarding the displayed item, further

 information have to be encodes as there are the navigation-tree and

 meta-information which enable search-engines to recognize the

 mathematical content of the page. 

 \subsubsection{needed methods}

 \begin{description}

   \item[HTMLText BrowserEncoder.encodeInformations(information\_map)]

   \ \\ encodes the given information. The generation is done with help

   of a ``template''. Basically, the template is a ready-made HTML-page

   with a few locations to fill in informations. This function has to

   parse the HTML and fill in the proper informations out of the

   information map. Different templates can be used for different

   datatypes. For instance a problem-description will have to present

   other informations than an Example or course-mainpage. Optionally, a

   predefined layout can be given within the information-map. This

   layout overrides the automatically generated one.

   To enhance usability of the system, some requirements regarding the

   layout have to be met:

   \begin{itemize}

      \item Highlite important informations: in some cases, there are

      some informations to be highlighted. e.g. if the user is forced

      to find a fitting problem for a calculation, the system can give

      feedback if the problem matches and if not it can give detailed

      informations wich requirements are not fulfilled. These

      ``matching-results'' have to be presented in a proper way.

      \item uniform presentation: The amount of information given

      depends on the users needs and permissions. It might be, that

      some fields available in one problem are missing in an other

      one. The encoder has to ensure, that these missing fields are

      handled in a way that the page keeps looking sound.

   \end{itemize}

   \item[HTMLText BrowserEncoder.encodeNavigation(navigation\_map)] \

   \\The navigation\_map is a hierarchical map which containes its

   nodes as labels and the next treelevel (a map of the same structure)

   as value. One node consists of the ID of an item to show and an

   ``weight'' for the order within one treelevel. The ID has to be

   translated into a link which in turn is used to load an other

   item. The structure should support expanding/collapsing of the

   branches to enhance clearness. This could be reached e.g. through

   java-script.

   \item[HTMLText BrowserEncoder.encodeMeta(information\_map)] \ \\

   There are several projects which try to give meta informations for

   mathematical content.\kommentar{links zu LOM, DC, MoWGLI einfuegen!} 

   This method should be designed to meet the requirements of these

   projects and be flexible enough to change between them if the

   requirements change. The result of this method is put into the

   header of the result-page.

 \end{description}

 \subsection{Information processor}

 \label{SDD:info_processor}

 The information-processor is responsible for gathering the

 information. Therefore it encapsules the communication to the rest of

 the isac-system (utilizing dinopolis). It also splits the users

 request to some subrequests to the browser-dialog.

 The processor has an internal table to find the assigned

 browser-dialog for a session. If no reference to a dialog is present,

 the session-dialog is called to get an object-proxy of the

 browser-dialog which in turn is used to get the requested

 informations. The session-dialog (which created the browser-dialog)

 created the browser-dialog with the assigned session-ID when it

 received the request to open a new browser. (see section

 \ref{SDD:dialog})\frage{authentifikation ?}

 \begin{description}

   \item [InfoMap processDescription(DescriptionID, Mode)] Processes

   the informations of the wantet Description and puts it into an

   map. The resulting \emph{InfoMap} containes copies of all

   informations - changes to this Map do not affect the stored

   data. The \emph{mode} specifies the way the informations have to be

   gathered. The main types are \emph{BROWSE} and \emph{FEEDBACK} where

   FEEDBACK also has to contain the adress of the ProveState upon which

   the feedback is built.

   \begin{description}

     \item[BROWSE] the \emph{information Processor} just forwards the

     request to the \emph{DescriptionStorage} and repacks the gained

     informations.

     \item[FEEDBACK] the \emph{information Processor} takes the result

     from the \emph{DescriptionStorage} and overloads it with the

     informations from the ProoveState. Therefore, the ProofeState

     needs a method wich returnes how far the active information fitts

     into the State. For Example: if the displayed information is an

     Problem, the ProoveState has to perform a match between its model

     and the Problem. The result is returned to the

     \emph{informationProcessor} which fits it into the

     \emph{informationMap}. Statical informations from the

     \emph{DescriptionStorage} (where, find, \dots) are replaced by the

     state and ``comment'' of the ProveState. (e.g. ``find: x'' becomes

     ``find: item missing'')

   \end{description}

   \item [DescriptionObject getDescription(DescriptionID)] internal

   Method to retrieve the Description for a Problem (or Example,

   \dots). This method has to establish a connection to the

   \emph{description-storage}, encode the ID in correct manner and ask

   for the \emph{description-object}.

 \end{description}

 \subsection{drowser-dialog}

 \section{description-storage}

  When the description-storage accesses the SML-knowledge-base, there

  is an helper-layer which encodes the SML-output (text-stream) into

  JAVA-Objects and vice versa. This mechanism is not mentioned

  explicitely within this explanation.

 \begin{description}

  \item[MEadress getBaseRecord(Datatype)] retrieves the Base record of

  a given Datatype. For instance \emph{getBaseRecord(PROBLEM)} returns

  a adress which is understandable by the mathematic engine and points

  to the outermost Problem (e.g. [equation]). This is necessary to get

  an entry point for the further query.

  \item[Map getDescription(MEAdress)] retrieves the mathematical

  informations about a given entry inside the ME. The Map consists of

  the field identifyer (as used within SML) and the assigned data. The

  datatype suits the SML-datatype but is delivered as JAVA-Object

  (e.g. a SML-List is encoded to a JAVA-List).  Among others, the Map

  containes ``children'' which contain a list like [[equation,

  univariate, linear], [equation, univariate, plain\_square],

  [equation, univariate, polynomial], \dots]

  \item[DescriptionID storeDescription(Map)] takes the information as

  given by the ME and stores it inside a database. Therefore it is

  neccessary to convert it into fitting Datatypes understood by the

  Database. 

  \item[void fetchData(Datatype)] fetches the BaseRecord of the

  Datatype (e.g. PROBLEM) and uses \emph{getDescription} to traverse

  recursively through the whole Datastructure to generate the

  information of the whole information-tree.

  \item[DescriptionObject getDescription(DescriptionID)] returnes the

  \emph{description-object} which handles the given description. If

  this method is called twice targeting the same description, one and

  the same \emph{description-object} is returned.

  \item[DescriptionID createDescription(Datatype)] creates a new

  Description of the given Type and return its ID. The Datatype

  identifies the number, type and names of fields which are mandatory

  and optional for the record\footnote{The datatype might be specified

  in a DLD and has to contain metadata as: is the data stored inside

  the ME, which fields are only to be changed by the ME, which

  identifyer has the Datatype within the ME, \dots}.

  \item[List queryDescriptions(criteria)] queries the database for

  Descriptions matching the given criteria. This criteria can be

  e.g. Datatype, modification Date, parts of the name, \dots. The

  identifyers of the matching Descriptions are returned to the caller.

  \item[navigationTree getNavigation(navId)] builds and returns a

  structure which describes a navigation Tree. navigationTree is a

  ``nested Map''-like structure but with an unique order of its

  keys. \\ A key represents a node inside the tree and contains name

  and reference of the related content - the assigned value is a

  structure of the same type or \emph{null}. So, the full tree is

  recursively built.

  \item[navId newNavigation(navigationTree)] store a new navigationTree

  in the description-store.

  \item[List queryNavigation(Criteria)] query the description-store for

  a list of Navigation Trees. Criteria can contain Informations like

  the content of the tree (e.g. differential equation).

  %\item[set navigation] ??? immuteable navigationtrees ? wenn ein tree

  %geaendert wird, muss er neu gesetzt werden ?

 \end{description}

 \subsection{description-object}

 \begin{description}

  \item[Map getFields()] Returnes a Map of the contained fields and

  their types (Maps fieldnames to a fielddescription: datatype,

  optional)

  \item[Object getField(fieldname)] Returnes the assigned Field. The

  returned values has to be immutable as a datachange is only allowed

  through the respective set-Method.

  \item[boolean setField(fieldname, value)] sets the field

  \emph{fieldname} to \emph{value}. This operation might fail if the

  user does not have the permission to change the field, or

  \emph{value} is of the wrong type.

  \item[boolean getWritelock()] request a writelock

  \item[void releaseWritelock()] release the writelock to let other

  users change the description

  \item[DescriptionID createChild()] create a new Child of the same

  Datatype for this description. This is useful for Examples but not

  possible for all types of descriptions. e.g. The children of a

  Problem are only created out of the ME - it is not possible for a

  user to create a new Problem!

 \end{description}

 \section{The Dialog}

 \label{SDD:dialog}

 The dialog represents the \isac{}-layer which connects the

 frontend-applications with the backend-ressources (math-engine,

 description-storage, \dots). It is responsible to adjust the behaviour

 of the system to the users needs and permissions. (see \ref{ADD:dialog})

 The ``heart'' of the dialog-layer is the \emph{session-dialog}. It

 instantiates new sessions and browser-- or worksheet-- dialoges when

 needed. It also registers them on the security system to grant

 access-permissions as needed. Therefore, the session-dialog has to be

 instantiated on system-startup and registered an the

 \emph{dinopolis}\/-NameService to be found by the frontend-applications.

 \subsection{create a new session}

 A new session is initiated by the session-controller. This is a

 client-side java-programm which queries the dinopolis-nameservice for

 the session-dialog and connects with it. The session-dialog requires a

 username and the assigned passwort. If the user is assigned to more

 then one user-group, it is necessary to enter the active group for the

 session (the group determines the behaviour of \isac).  The

 session-dialog prepares the user-model for the user and returns

 user-preferences to the session-controller if wanted.

 \subsubsection{needed methods}

 \begin{description}

   \item[groupset SessionDialog.login(username, password)] A public

   method to performs an user-login to \isac. If username and password

   fit, the set of possible groups for the user are returned to the

   caller and the caller is registered on the dinopolis-securityManager

   to be autorized to connect to the private methods (openSession)

   \frage{laesst sich der caller mit dino-mitteln

   feststellen?}. Otherwise \emph{null} is returned to inform the

   caller that the login was not successful.

   \item[boolean SessionDialog.openSession(group)] This method is only

   accessible for authenticated DinoObjects which performed a login

   previousely. If the group fits the assigned user, a new session is

   created and assigned to the gid of the caller\footnote{Usually, the

   caller will be of type \emph{SessionController}}

   \item[Map SessionDialog.getUserPreferences()] This method is only

   accessible for authenticated DinoObjects which performed a login

   previousely. A set of readable preferences (such as a

   ``default-group'') is returned. Note that there are preferences

   which might be readable but not writeable and others which are not

   even readable and therefore not included in the returnvalue of this

   method.

   \item[boolean SessionDialog.setUserPreferences()] This method is only

   accessible for authenticated DinoObjects which performed a login

   previously. It is used to alter a users preferences. The

   session-dialog checks if all contained preferences are writeable for

   the user before it trys to write them to the user-model.

 \end{description}

 \subsection{open a new browser (--window)}

 Anthough the WebBrowser runs on the client-side and connects to an

 already running WebServer (see Section \ref{SDD:knowledge_browser}),

 interaction with the session-dialog is necessary to prepare the system

 for the request. The request to open a new browser-window can result

 either from the user himself (through the session-controller) or from

 an other part of the dialog (worksheet-dialog if the user is forced to

 search an item by himselve or browser-dialog if the user jumps into an

 other part if the knowledge).

 For the session-dialog, it does not matter who opens the new

 browser-window - the behaviour is always the same (access-control is

 done through dinopolis)

 \subsubsection{needed methods}

 \begin{description}

   \item[boolean SessionDialog.openBrowser(params)] This method is only

   accessible, if the caller is explicitely allowed to

   connect\footnote{the session-dialog gave the permission before

   e.g. while login or because the caller was created by the

   session-dialog}. The session-dialog looks for the

   \emph{browser-dialog} which handles the knowledge-access for the

   current session. If no browser-dialog was found, a new one is

   created and registered to be allowed to access the current

   sessiondialog.

   \emph{params} contains information as start-point and mode of the

   access (e.g. problem to start the search from, mode:dynamic to tell

   the browser to present the match-results, id of the calculation

   within the worksheet-dialog to match with).

   Depending on the type of browser to use (stored in the preferences),

   this informations are encoded to an program-call and passed to the

   session-controller which executes it. (in case of the http-accessed

   browser this programm call could look like ``mozilla -remote 

   http://knowledge.isac.at//\-sid=12345\&type=passive'')

   \item[SessionController.execute(Object programmCall)] Executes the

   given program. \emph{programCall} can also contain information if

   the program to call is native or a java-program (the later can be

   called within the same java-machine)\footnote{for informations

   regarding the execution of the browser-call see section

   \ref{SDD:knowledge_browser}}

 %  This informations are

 %  passed to the browser-dialog to prepare it for the upcomming

 %  request. The browser-dialog stores the informations and returns an

 %  id

 \end{description}

 \subsection{open a new worksheet}

 Opening a new worksheet is similar than open open a new

 browserwindow. Additional to the single programcall, a new ProoveState

 has to be instantiated and filled with the correct informations. The

 request to open a new worksheet can result either from the user

 himselve or from an other part of the dialog (the browser can start

 the calculation of an example or start an empty

 calculation). Therefore the browser (-dialog) has to instantiate a new

 provestate and fill in the informations used to start the calculation

 (see Section \ref{SDD:knowledge_browser} for details) Afterwards, the

 provestate is given to the worksheet-dialog to enable the worksheet to

 continue the calculation.

 \subsubsection{needed methods}

 \begin{description}

   \item[boolean BrowserDialog.openWorksheet(params)] If the Browser is

   used to initiate a new worksheet, this method is called from the

   processor to initiate the ProofState and forward the request to the

   session-dialog. The \emph{params} contain the id of the example to

   calculate if any. First, the BrowserDialog has to connect the

   Description-Storage to gather the informations of the example. Then,

   the new ProofState is instantiated and filled with the data. This

   ProofState is used to call the SessionDialog which instantiates a

   new WorkSheet and connects it with the ProofState (through the

   worksheet-dialog).

   \item[boolean SessionDialog.openWorksheet(ProofState)] This method

   is only accessible, if the caller is explicitely allowed to

   connect. The \emph{ProofState} already containes all information

   which are needed to for the calculation. The session-dialog connects

   the responsible worksheet-dialog (or instantiates a new one if no is

   running) and passes the proof-state. The return-value containes an

   identifyer of the running calculation. The SessionController is

   called with this id to start a new worksheet. The new worksheet uses

   this number to establish an connection to its dialog. Any further

   communication bypasses the session-dialog.

 \end{description}

 \section{The browser generators}

 create a XML-description out of the knowledge-database.

 \subsection{}

 \subsection{}

 \subsection{}

 \subsection{}

 \subsection{}

 \section{The example browser and generator}

 %\subsection{}

 %\subsection{}

 %\subsection{}