Binary Parka Interface Documentation

Starting the Parka Interface

There are two ways to open the interface, in either applet or standalone application mode. In either case, a window labeled Parka Interface v. 1.0 should appear.

Applet:
In order to use the interface from a Web page you simply have to press the appropriate button.
Standalone application:
After executing the program, a small window with two buttons in it appears. One button says "New Window", and operates just as above. The other says "Quit", and should be pressed when you are done with the application. This is called the "Application window". For information on how to execute the program see the section on Running as a Standalone Application.

Query Window

This window provides the query interface to the parka database server. At the top is the menu bar. Under that are three little icons-- an arrow, a hand, and a line. These control the creation of a query graph in the white canvas below it. Beside it is a text area for messages from the system. Below the area for the graphical query is the space for query output. This space is not there until the first query is issued. On the left side is a bar which slides up and down to control the sizes of the two halves of the window -- the query graph and the query results. This will operate after query results first exist.

Menus

File menu
Close
Destroy this query window.
New Object
Creates a new node in the query graph area in a default location.
Clear Graph
Erases all the objects in the query graph.
Clear Query Results
Erases all the results in the responses section of the window.
Browser Window
Bring browser window to the fore (top of the window stack). If the browser window has never been openned (see next menu, it does nothing if the browser has not been opened)
Application Window
Brings the application window to the top of the window stack. This is the window with the two buttons in it. Not an allowed menu choice if run from an applet (since it won't exist).
Parka menu
The Parka menu controls the operations with the parka server. If the application is being run from a web page, most likely the server connection will have already been established and a knowledge base will have been opened for you.

Connect to Parka
Initiate a connection to the parka server.
Open Database
Open a Knowledge Base.
Submit Query
Request the answers for the query represented by the current query graph.
Open Browser
Starts up a browser window for parka. Only one is allowed per Query window. See the section on The Browser Window for information on how to use this window.
Disconnect from Parka
Disconnect from the parka server. Closes any currently open KBs, if there are any.
Close Database
Close the current KB.
Object menu
This can be used when one of the nodes in the query graph is active. The active node is filled with yellow. This is the node to which the menu operations chosen will apply. The operations possible are:

Rename Object
Change the name of the variable or constant that is currently active. Before choosing this option, type the desired new name for the currently active node into the text area. Then choosing this menu item will change the name.
Delete Object
Delete the node that is currently active.
Variable
This is a toggle. When the associated small icon to the left of the word "Variable" is indented, and the node is represented by a rectangle with rounded corners, then the node represents a variable. Clicking on this choice changes the node to represent a constant, and it will change to rectangle with square corners. The small icon on the left in the menu will also become raised to show that the choice "Variable" has been set to false. Notice that at the far right of the window, under the menu bar is a button labeled "Variable". This is activated when the Object menu is activated, and has the same function as this menu choice.
Link menu
This can be used when one of the links in the query graph is active. The active link has the background behind its text colored yellow.

Reverse Link
Reverse which node is the source (domain) for the link, and which is the destination (range).
Rename Link
Pops up the menu of predicate names for choosing another one.
Delete Link
Removes link from the query graph.
Font menu
This menu allows immediate change of font size and font family. It affects the query graph only, not the query responses, which have a fixed size and font.

Query Graph

The query graph has nodes which represent either the query variables or constants from the currently open KB. These are represented by rectangles. The rectangle has square corners the node is a constant; otherwise it is a variable and has rounded corners.

The links are lines going from the source or domain node to the destination or range node. The name of the link appears in the middle.

Once a query is formed, with the help of the icons in the upper left corner, the query can be submitted to the KB that is currently open.

Icons

The three icons that appear just below the menubar on the left side are used to control drawing the query. Click with any mouse button on the one you want to have active. The active icon plus the following mouse buttons describe the effect you will get when creating a query.

Arrow Icon:
When this one is chosen, nodes can be clicked on to activate and move them to a different location. Any mouse button works for this. It is also the position where you can prevent yourself from accidently doing anything else that can happen in the drawing area (eg., accidently creating nodes you don't want).
Hand Icon:
This icon is chosen when you want to do operations with nodes. When this is chosen, mouse buttons have the effects that follow: 1st : create a new node in the position clicked on. 1st plus control key, or 1st plus shift key: rename the node that already exists which you just clicked on. Type the new name (it will go into the text area), then type 'return' when done. NOTE: Some window managers may use one of these key sequences and not let the application running in the window get it. In that case, use the other one, or the menu choice in the 'Object' menu. 2nd: deletes the node clicked on with the 2nd mouse button. 3rd: no effect.
Line Icon:
This icon is chosen when you want to do operations with links. When this is chosen, mouse buttons have the effects that follow: 1st: click first on the node that is to be the source (domain) for the link. The mouse down click must be within the node that is to be the source for this to work. Then you drag, with the mouse button still down, until your cursor is within the node that is to be the destination node. At that point, you let the mouse button up again. While you are dragging, a line will show the link-to-be. Once the mouse button is let up on the destination node, a menu of predicates to choose from will pop up. Choose from the list, and press "OK". The name and a permanent line representing the link will appear in the graph. This will now become the active graph object. 1st plus control key, or 1st plus shift key: rename the link that already exists which you just clicked on. Again, the predicate list will pop up; choose the new name you desire. (The NOTE under "Hand Icon" applies here too). 2nd: delete the link clicked on with the 2nd mouse button. 3rd: reverse the source and destination of the link clicked on.

Query Results

After the first query is submitted, the bottom half of the window is created. This will consist of a multiple column list of answers to the query (if there are any), and a section above that provides information about the answers. The label "First Item" indicates which record is the first one appearing in the list. This is required, because if there are a great many answers, they are not all brought over from the server at once. Initially, only the first batch is brought over. The label "Last Item" shows the number of the last record appearing in the list. At the top of the window, in the text area above the graphical query, the total number of answers to the query is shown, so the user can immediately see how many answers compared to the total that they have. If the total number of answers could be brought over from the server to the client in one batch, then the labelled buttons below "First Item" and "Last Item" will both be inactivated. However, if more answers exist in the server that the user may get, then "Get Next Group" will be activated. Click on this to get the next set of answers. Now "Get Last Group" will be activated, and "Get Next Group" will still be activated unless we have gotten now to the end of the answer set. Thus the user may go backwards and forwards as much as he/she wishes.

The user may also click on a row in the list. This will cause the variable values from that row to show up in the query graph, associated with the appropriate variables. Clicking on a different row changes the values to those of the new row. To go back to no values being displayed in the query graph, double click on some row.

If the user is using the Parka Interface from a Web browser an additional feature is available. Double-clicking on a value which is a valid URL will cause that web page to be opened in another window.

While the user has a particular KB open, the last query given remains in the list in the bottom part of the window, until a new query is submitted. When a KB is closed, the answers are erased, and so is the query graph.

Browser Window

This window allows the user to get some ideas about the content of a KB that is unknown to him/her. When the browser first comes up, there are four lists. Only one item (or no items) can be selected in a given list at one time. A text area is at the bottom of the window for messages to the user. In general, the way the browser works is the following.

When an item in a list is clicked on, it is selected. If the selected item is clicked on, the list returns to a "no items selected" state. Clicking on a different item changes the selection to the new item.

If you were to manually try to find out what was in a KB, you would see that the KB directory has a number of files named for predicates. We start by listing these, plus built in predicates, in the first window of the browser. When one of the predicates is clicked on, a copy of that predicate is moved to the "Current Link" list. As many predicates as you want can be clicked on, and each in turn will be moved to that list. If at this point, the "Execute" button is pressed, the domain and range lists would both be filled with items that can be the domains and ranges of that predicate, respectively. If you want to see which domain associated with that predicate gives which range(s), then click on one of the domain items also. (Now both the original predicate and a domain item are both selected). Now the "Execute" button will give the ranges associated with each item chosen from the second and third lists (ie, domain and predicate lists). If instead you had wanted to see which domains are associated with the original predicate and some choice of range, the predicate in the "Current Link" list and a frame in the "Ranges for Link" list would both be selected; when the "Execute" button is pressed, the domain list would fill with only the domains asssociated with both items.

There is a maximum on the number of items that will be put in a list. If this does not include all the possible data in the KB for the given selections, the user is notified in the message field.

If you know or suspect that a particular value is a domain that you want to look at, that value can be typed into the text field beside the "Domain name:" label. When the return key is pressed, that value will be entered into the domain list, and then can be selected in the same way as any other list value. The "Range name:" text field behaves analogously with the ranges list.

In general then, the second, third, and fourth lists can each have a selection in them (or not). The reaction of the system when the "Execute" button is pushed depends on how many lists have selections in them. Here is a listing of the responses the system will give:

Only a "Current Link" item chosen:
Both all domains for that link, and all ranges for that link (up to the max that will display) are entered into the respective lists.
A "Domain" and a "Current Link" item are both chosen:
The list "Ranges for Link" is filled with items that are the range for the specified domain and predicate.
A "Range" and a "Current Link" item are both chosen:
The list "Domains for Link" is filled with items that are the domain for the specified range and predicate.
A "Domain", a "Current Link", and a "Range" item are all chosen:
Verifies that the resulting assertion exists in the KB. Probably more useful when one or more of the frames has been entered by means of the text fields.
Only a "Domain" item chosen or Only a "Range" item chosen:
Both of these will cause the same effect. The list of items that the chosen item is in will be moved to the center list (ie, third list). Then, all the predicates that have this item for the range will be listed in the "In to Frame" list. All the predicates that have this item for the domain will be listed in the "Out from Frame" list. This behavior is analogous to that for the 'Only a "Current Link" item chosen', above.

If at this point, an incoming link is also selected, and the frame in the center (third) list is left selected, the lists with the selections will each shift to the right, so that the domain(s) can be displayed in the second list (now labelled "Domains for Link"). If an outgoing link is selected, the lists with the selections move the other direction to allow the range(s) to display.

In general, when the only item chosen is in the second or fourth lists, this causes the list with the selected item to shift to the third list position, and answers will appear in both the second and fourth lists. The list labels change appropriately.

When two items are chosen, if the third list is "Current Link", no shifting needs to occur to show results. If the third list is "Current Frame" shifting will need to occur to show results. A user could progress through the KB graph by always making choices that require shifts in one direction.

If at any time, the result is not as you expect, make sure you only have highlighted the items you want to select -- no more and no less. Incidentally, a selection in only the second and fourth lists is not valid.

Remember, you can make and unmake as many selections as you desire. But nothing will happen until the "Execute" button is chosen.

Besides the "Execute" button are three others, one for clearing the second list called "Clear In List", one for clearing the third list, "Clear Center List", and one for clearing the last list, called "Clear Out List". These can be used on their respective lists regardless of whether it contains frames or links at the time.

Menus in the Browser's menu bar

File menu
Close
Destroy this browser window.
Query Window
Bring query window to the fore (top of the window stack).
Application Window
Brings the application window to the top of the window stack. This is the window with the two buttons in it. Not an allowed menu choice if run from an applet (since it won't exist).
Browser menu
Get KB Predicates
Put all the predicates for this KB into the first list.
Shift Lists Right
Move the second list to the third position and the third list to the last list. The second list becomes blank.
Shift Lists Left
Move the fourth list to the third position and the third list to the second list. The fourth list becomes blank.

Besides clearing away a lot of stuff you may not want to look at anymore, these two commands allow setting up for a different command type in an easy way that otherwise you might otherwise not easily get. For example, if the third column is labelled "Current Frame", then the text input fields do not function to enter things into the lists. You may want to use these; the "Shift List" commands then would allow the text input to function again.

Running the Java client as a stand-alone application

The Java client can be run within Netscape, or some other Web browser, or it can be run as a standalone program. In Netscape, the file parka.html is openned in order to run it. For executing the client in standalone mode, from within the source directory, give the command
java parka.ParkaApp &

The command assumes setting the CLASSPATH environment variable correctly. It needs to be able to find the .class files; for example, CLASSPATH would be set:
setenv CLASSPATH directory-path-of-source-code/Parka:.
This sets two places for the interpreter to look. The first is directory-path-of-source-code/Parka, which is the directory where the package directory will be found, when following these directions, and . ,which is the current directory. (Java books will explain CLASSPATH, or the equivalent for other operating systems).

Source Code Structure

The executable files are in a different directory from the source. The compilation command is:
javac -d Parka *java
which creates the directory for the package level in the position: location-of-source/Parka

The name of the package is parka. Therefore all the .class files are in:
location-of-source/Parka/parka/all-the-class-files.class

The gif file used for the various "tool" modes when creating query graphs is located in the directory:
location-of-source/Parka, and is named palette.gif
If this is moved, the Tools class and/or the codebase value in the html file will need changed for the applet, and the contents of the IconDirLoc will need changed for the standalone application. The IconDirLoc file is expected to be in the current directory, if running the application version.