-
Notifications
You must be signed in to change notification settings - Fork 2
/
WriteUp.tex
42 lines (39 loc) · 9.04 KB
/
WriteUp.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
\documentclass{article}
\usepackage[margin=1.0in]{geometry}
\usepackage{amssymb}
\title{NiagaraST Query Maker GUI\\
CS-410 Winter 2012}
\author{Dustin Schmidt, Weston Wedding, Brian Liu}
\date{21 March 2012}
\begin{document}
\maketitle
\tableofcontents
\section{Overview}
The project goal is to design an application for graphically building NiagaraST query plans using Java and Swing. The program will allow a user to assemble NiagaraST query plans by constructing a directed graph of operators. The user will select from a list of operators to generate an operator node. The graphic representation of the operator node will contain fields for entering the operator parameters. The list of operators available to the user and the parameters each operator needs will be generated from the NiagaraST source code for logical operator representation. In this way the application will be scalable as new operators are added. The data flow through the query plan will be constructed by graphically connecting the inputs and outputs of various operators. When the query plan construction is complete an XML query plan file will be generated that will successfully run in NiagaraST.
\section{Program Usage} The user interface is relatively simple and, by default, opens with two window panes: the Main pane, and the Operators pane. A third type of pane is available, the Operator Properties dialogue box.
\subsection{MainPane} This window has the visual representation of the query plan being built. By default it starts as a blank slate, but you may load existing query plans (.nqp files built using this GUI) into the editor by using the File menu. As operators are added to the query plan, graph nodes are added to the display. Nodes can be dragged around as needed, and each node has a an "input" port and an "output" port (the smaller cells on each side, pointing "in" or "out" of the node). Queryplans can be saved at any time, and the various attributes for operators can be set at any time.
\subsubsection{Nodes And Connections} Using the input and output ports are very simple, and are the way a queryplan operator's "input" attribute gets populated. For instance, to set Node A as the input of Node B, simply drag and drop from Node A's output port to the input port of Node B. This will create a line to visualize this connection. Note: A node needs to at least have an "id" attribute set in order to be considered a valid source for a connection.\\
In order to add or update properties to an operator on the graph, just right click the node and choose "Properties." Also note the other option available in this window, "Set As Top." It is important to set an operator as the "top" operator (usually a construct operator) in order for the query plan to be valid in NiagaraST. The "top" operator is given a different color than the other operators.
\subsubsection {Settings} There are several settings a user can set in order to generate a valid query plan. The software ships with an included "default.dtd" that is a DTD file that contains (at the time of release) standard operators that NiagaraST uses. If you have an install of NiagaraST that has custom operators compiled or just want to be sure your available operators are up to date, you will need to point the software to the more recent queryplan.dtd you wish to use from the File menu. The specific menu option is "Select Internal DTD."\\
Note that there is an "External DTD" setting, as well. The External DTD is the string that will be included at the top of the generated XML file, and it defaults to "/stash/datalab/datastreams-student/bin/queryplan.dtd," which is the current default location for Portland State University's copy of NiagaraST.
\subsubsection{File Saving}The software can save and load files that are in its own special serialized format (.nqp files), available in the File menu as "Save Query Plan" and "Load Query Plan." The actual XML formatted output is generated by selecting the "Generate XML" menu option.
\subsection{Operator Selector Window} This window is pretty straight forward. The list of available operators is populated using the either the default.dtd or a user-supplied dtd, and they can be added to the graph by click the "Add Operator" button.
\subsection{Properties Window} This window is used to provide to operator-specific types of information. The various attributes like "input" and "id," any comments you wish to add to this particular operator (these will also be placed into the XML output), and any subelements. At this time, sub elements (like the <and> and <or> elements) that an operator might need can be typed in here. This is a text entry box, so some knowledge of the underlying XML structure will still be necessary at this point. XML markup put here will be placed, unaltered, into the XML document when XML is generated. The Properties for a particular operator are shown by right clicking the operator and selecting "Properties"
\section{Class Descriptions}
\subsection{DTDInterpreter} This class is used by QueryPlan to interpret a DTD file which provides the logical definition for NiagaraST operators.
\subsection{GraphNode} This class extends Operator to include a draw function to draw the operator on the graph canvas. GraphNode is constructed with an operator template which defines it's corresponding operator name and attributes. The draw method accepts a reference to an mxGraphComponent and it's parent and draws the graphical representation of the operator onto the graph component.\\
The graphical representation of an operator contains three main components. An input port, a main body, and an output port. The main body of the node is mainBox which is an mxCell whose value is set to this GraphNode. Setting a cells value to an object causes the string representation of the that object to be displayed in the cell, hence the mainBox contains a string representation of this Operator GraphNode as defined by the toStringMethod. The input port and output port are both instances of the IOPort subclass.
\subsubsection{GraphNode.IOPort} This is a nested class used to represent the input and output of an operator. IOPort extends mxCell but includes a boolean value input and boolean methods isInput and isOutput. These methods are used to validate edge creation in MainForm's EdgeListener.
\subsection{MainFrame} This class is the main frame of the application. It contains an mxGraph component which is a swing component for editing graphs.
\subsection{Operator} This class represents an instance of an operator. The Operator is constructed with and OperatorTemplate which defines the name and attributes of this operator. Once instaniated the Operator attributes are manipulated through the get and set Attribute methods. These methods modify the private HashMaps which map attribute names to their values. There is also a method for generating the XML representation of this operator. The current implementation of the Operator class treats sub elements (such as predicates for select) as a single string $elements$ and not as meaningful content. There is also a member String $comments$ which specifies a comment string to precede the XML representation of the operator.
\subsection{OperatorTemplate} The operator template class is used by most classes in this project. The OperatorTemplate provides a representation of an unstansiated operator. The operator template contains a listing of attributes and elements and the name of an operator. This template is used to construct an Operator instance with the given attributes, elements and name.
\subsection{OperatorSelectorDialog} This dialog is used by MainFrame to display a list of candidate operators. The user clicks an operator (or ctrl+click many or shift+click many) and then clicks the "Add" button and the operators are drawn on the graph.
\subsection{PropertyDialog} This dialog allows the user to set the attributes of an operator. This dialog is displayed by right clicking an operator in the graph and clicking "Properties" After changes are made the user must click the "Update" button in order to apply the changes. If the operator has an "input" attribute it is displayed as read-only. This is because inputs to an operator are set by connection the input and output ports of operators on the graph.
\subsection{QueryPlan} This class contains a logical representation of the query plan currently being edited by the user. This class maintains a listing of all operator templates ($opTemplates$) drawn from a DTD file, and a listing of all instantiated operators currently in the plan ($opList$). When the user makes changes to an operator either on the graph or through the property dialog the state of the corresponding operator in opList is updated. When the user has completed a Query the method QueryPlan.generateXML is called and given a fileName, the query is then rendered to the given file name.
\section{Third Party Libraries Used}
\begin{itemize}
\item JGraphX - obtained from jgraph.com, provided in the file jgraphx.jar
\item DTDParser - obtained from , provided in the file dtdparser.jar
\item Jdom - obtained from http://www.jdom.org/
\end{itemize}
\end{document}