View source for Assignment:Exposing data over http lab2 GUI Client

=Prerequisites - introductory workshop etc=
Before starting with this assignment, you should attend the workshop for Lab2, the manuscript for which can be found [[:Media:TIG058-Lab2-Client-side GUI.pdf| here]]. Read it (video is work in progress), and try to understand the GUI and how the Request/Param classes work, as well as how the ApiAccess class works. Se the UML at the last page of the presentation.
==Lectures to see and chapters to read before starting with this sub-assignment==
* [[Java-Swing:Introduction to Swing]]
* [[Java-Swing:Introduction to Swing - Introduction to JFrame]]
* [[Java-Swing:Introduction to Swing - Introduction to JButton]]
* [[Java-Swing:Introduction to Swing - Introduction to JTextField]]
* [[Java-Swing:Introduction to Swing - Introduction to JLabel]]
* [[Java-Swing:Introduction to Swing - Introduction to Layout Managers]]
* [[Java-Swing:Introduction to Swing - A GUI for the Address book assignment]]

= Videos =
[https://vimeo.com/channels/1332975 Exposing data over http, Lab 2]
*[https://vimeo.com/249802753 Exposing data over http, lab2 GUI - 1]
*[https://vimeo.com/249802817 Exposing data over http, lab2 GUI - 2]
*[https://vimeo.com/249802808 Exposing data over http, lab2 GUI - 3]
*[https://vimeo.com/249802799 Exposing data over http, lab2 GUI - 4]
*[https://vimeo.com/249802789 Exposing data over http, lab2 GUI - 5]
*[https://vimeo.com/249802773 Exposing data over http, lab2 GUI - 6]
*[https://vimeo.com/249802765 Exposing data over http, lab2 GUI - 7]
*[https://vimeo.com/249802741 Exposing data over http, lab2 GUI - 8]

=Lab 2 - Writing the GUI Client=
In this second sub-assignment, we'll write a small GUI client in Java/Swing. This sub-assignment has two goals:
You should have a graphical Java application which can
* display a table of product from the Systembolaget product line.
* allow the user to enter values for filtering the products, and produce the correct API call for such filters

Technologies which are the focus of this sub assignment include:
* Swing
* HTTP URLs (with GET query parameters)
* Using factories and interfaces to hide implementations
* Using fake data to be able to postpone some technical parts of the application, yet be able to test it
* Printing URLs to verify that the filters are correctly produced from the user interface

== Software introduction ==
Before starting with this task you need to download (and unpack) the software. Use the following link: [https://github.com/progund/exposing-data-lab-gui/archive/master.zip github.com/progund/exposing-data-lab-gui/archive/master.zip]. When unpacking this zip file you will get all the files we refer to below in a directory called <code>exposing-data-lab-gui-master</code>. Enter this directory and start working.
 
Your client software consists of a few software modules:
* The graphical user interface
** Written in Swing
** Mainly focused around a JTable and a custom JTableModel
* The domain class Product (represents a Java object for a Product - note that while the Product class is the same as on the server-side, it need not be, since this one represents Products as they are represented by the JSON file)
** This is the data type for the JTableModel
* Classes to represent a Query which should be used by some class accessing the web API
** The Query class represents a set of Param objects, created from the users filter input text fields
** You'll use a factory to get an <code>ApiAccess</code> object, which let's you access an API
*** An ApiAccess object has a method which accepts a Query object as parameter, and fetches a list of Product objects
** You'll finish the code for a FakeApiAccess class which always returns the same set of products, regardless of what Query you send it
* The REST Query class represents a Query (which is what you send to the ApiAccess object)
* A Query object
** has a list of parameters (of class Param)
*** A Param (represents a parameter) has a key and a value
** let's the programmer add parameters to its internal list
** can return the value from a given key
** can represent itself as a query string

You'll need to attend (or, in worst case, see the video of) the workshop in order to fully understand the architecture and design of the client. And you need to study some basic stuff, in order to get something out of the workshop.

There's an online API [https://progund.github.io/systemet-gui-client-docs/docs/ at progund's github] for this Lab2 classes.
=== Swing User interface ===
The Swing user interface presents the user with a graphical application which lists a set of products in a tabular form. The GUI also presents the user with four input fields:
* Min price
* Max price
* Min alcohol
* Max alcohol

The GUI will react immediately to input changes in the text fields. In this Lab2, you will print a corresponding URL for the servlet to standard out, so that you can test that the GUI produces a correct query to the servlet from Lab1 according to what the user types in to the GUI.

The table has a table model, which is capable of displaying rows with Product objects, and also sorting the rows (when the user clicks a column header).

In this sub-assignment, you will get the data (products) from an ApiAccess object, sending it a Query. As in lab1, however, you will totally fake the fetching of products. You will create a fake ApiAccess class, which will always return the same objects, regardless of what Query it gets as an argument. The idea behind faking data is to reduce the complexity of the system. In the coming lab (Lab3) we will use proper data from the web API instead.

The first goal of this sub-assignment is for you to see how you can display a table of products in a Swing GUI. We provide a GUI for you. Your job is to understand and extend the gui. You shall also understand how a Query is built and the purpose of the <code>APIAccess</code> interface. 

A JTable is used to display the Product data. A JTable uses a "table model" (which we have written for you). You can read about JTable and JTableModel at Oracle: [https://docs.oracle.com/javase/tutorial/uiswing/components/table.html Swing tutorial - how to use tables].

The second goal of this sub-assignment, is for you to verify that the GUI can create the correct Queries for fetching products from the Web API.

'''''Note''', that you will not actually contact the Web API from the Java code in this sub-assignment, only verify that your GUI creates the correct URLs for doing so, by printing the URL you ''would'' use, and test it manually.''

If the user enters 10 in the Min price text field, and 100 in the Max price text field, this should generate a Query for the Web API which reads:

<code>http://localhost:8080/search/products/all?min_price=10&max_price=100</code>

It is enough if your GUI client prints the queries to standard out, for you to be able to test that they are correct and work.

Note, again, that the products displayed in the GUI will not be filtered according to the user input. That's for the third sub-assignment! This is because we don't contact the web API from the GUI code, so we won't get new Products to update the table model with.

This software module is responsible for:
* Creating a GUI
* Displaying products in the GUI
* Allowing for user input in text fields for filtering products

===Domain objects===
This module (package) only contains the Product class which represents a product from the Systembolaget API. The Product class uses a builder as an alternative to a constructor. You can read about the Builder design pattern [[Design patterns - Builder|here]] (in particular, the section ''Making a class have its own builder'').

===The REST Query API===
This module lets you create Query objects (consisting of key-value pairs) which you can send to an ApiAccess object.

An ApiAccess object, should, given a Query, return a list of Product objects. Again, in this sub-assignment, how the ApiAccess object actually fetches the products, is totally fake. Always returning '''some''' objects, allows you to test that the GUI is capable of displaying objects in a tabular fashion.

Your GUI will, given input from the user via the text fields, build up a Query which you can print to the standard out to see that it actually creates a URL which would work for accessing the Web API (Servlet).

===Directory overview===
The directory layout is as follows:
<pre>
.
|-- build.sh
|-- clean.sh
|-- download_json_jar.sh   <-- not needed in this lab, Lab2
|-- examples
|   |-- QueryBuilder.java  <-- An example GUI without products, showing how you can create a URL from textfields
|   `-- TextFieldDemo.java <-- The GUI class for the example
|-- gendoc.sh
|-- run_product_search_gui.sh
|-- run_query_builder_example.sh
`-- se
    `-- itu
        `-- systemet
            |-- domain
            |   `-- Product.java
            |-- gui
            |   |-- ProductTableModel.java
            |   `-- SearchGUI.java         <-- The central class of the GUI
            |-- main
            |   `-- ProductSearch.java     <-- The main class of the GUI
            `-- rest
                |-- ApiAccessFactory.java  <-- Use this to get an ApiAccess object
                |-- ApiAccess.java
                |-- FakeApiAccess.java     <-- Finish this class to create Product objects for the GUI
                |-- Param.java             <-- A parameter for a query
                |-- QueryFactory.java      <-- Use this to get a Query object
                |-- Query.java
                `-- RestQuery.java         <-- Represents a Query for accessing the servlet web API
</pre>

==Part 1 - Building and running the GUI application==
Here we simply learn how to compile everything and run the gui application.

We recommend that you use the <code>build.sh</code> bash script to compile the client. Read the script and make sure you understand what it does and why it does it.

To run, we recommend the <code>run_product_search_gui.sh</code> script. Again, read and understand this script.

As usual, you need to make the scripts executable before running them in your terminal running bash. <code>$ chmod u+x *.sh</code>

To compile the example GUI, please do
<source lang="Java">
$ javac examples/*.java
</source>
And to run it,
<source lang="Java">
$ java examples.QueryBuilder
</source>

==Part 2 - Finish the FakeApiAccess class==
You will add code to the class <code>FakeApiAccess</code>. This class implements the ApiAccess interface, and which returns a list of fake products when its <code>fetch(Query)</code> method is called. Currently the list is empty, which can be seen if you run the GUI.

A big part of this part is to understand the design and architecture of the gui client provided to you by the teachers.

Faking products you already know how to do, from Lab1.

==Part 3 - Printing the generated queries and testing them on the Web API==
In this part, you will print the queries generated from the GUI to standard out and use that output to test that the generated query strings actually would work and return the correct JSON from the Servlet Web API.

==Part 4 - Add a clear button==
Add a button to the search gui. The button:
* shalll have the text "Clear"
* be placed in a row underneath the text fields
* clear the text fields when pressed

==Challenge - Part 5==
If you want something challenging, you can add a checkbox to the form, indicating that the user is over 20 years. If the checkbox isn't checked (default), the only products allowed are products with alcohol of 0% (max_alcohol=0). Note that this will not affect the products shown, since they are from a fake API access, and the GUI in this lab number 2 doesn't update the product list.

Here are some hints to get you started:
* Add a <code>private JCheckBox</code> called <code>ageCheckBox</code> as a component
* Add a <code>private boolean</code> instance variable called <code>is20</code>

'''In lab 3, if you want to keep this, you need to change the constructor of the SearchGUI class so that it loads only zero alcohol products when the GUI is created.'''

Some more hints for the init() method:
* change the form JPanel to be of size 3,4 (three rows and 4 cols)
* initialize the <code>ageCheckBox</code> to <code>new JCheckBox("I am over 20")</code>
* add the checkbox to the form
* add a new JPanel to the form (an empty panel next to the checkbox)
* disable the alcohol text fields using the setEnabled() method

Some hints for the addListeners() method
* add an ItemListener to the checkbox
* in the itemStateChanged(ItemEvent e) method,
** set the <code>is20</code> variable to whether <code>e.getStateChange()</code> is <code>ItemEvent.SELECTED</code>
** if not <code>is20</code>, then set the alco text fields to the empty string
** set the alco text fields enabled state to whatever <code>is20</code> is
** call <code>newFilter()</code>
=Getting started=
==Getting started with part 1==

=== Setting up your environment ===

No extra software needed so nothing to do for you.

=== Build and start your client ===

In this section we list the steps needed to build the source code. These steps need to be done every time you:
* want to build (compile) to check that your source code edits were ok
* run the GUI with the latest changes  

To build:
<source lang="bash">
$ ./build.sh
</source>

To run the GUI:
<source lang="bash">
$ ./run_product_search_gui.sh
</source>

Doing both (the second only of the first is successful):
<source lang="bash">
$ ./build.sh && ./run_product_search_gui.sh 
</source>

<div class="mw-collapsible mw-collapsed">
''Note: Expand using link to the right if you can't execute the script.''
<div class="mw-collapsible-content">
<source lang="bash">
$ chmod u+x *.sh # make all scripts executable
</source>
</div>
</div>

==Getting started with Part 2 ==
Open the file <code>se/itu/systemet/rest/FakeApiAccess.java</code> in an editor and add code to make the method <code>query</code> return a list of (at least) one product. You did this in lab1 so reuse that solution.

==Getting started with Part 3 ==
Start by analysing look at the class with the main method, <code>se/itu/systemet/main/ProductSearch.java</code>. In this main method we can see that the <code>SearchGUI</code> constructor is called. In this Constructor we can see that two methods are invoked, <code>init()</code> and <code>show()</code>. Look at these methods to see where the actionListeners to the text fields are added. This should get you started.                                                                                                                                            

==Getting started with Part 4 ==
In the previous part you added a printout statement to see the queries. While reading the source code you probably saw that the method <code>init()</code> was responsible for creating and laying out components. We suggest you add code to add the JButton in the same method.

''Hint: increase the number of rows in the GridLayout and add a JButton and three empty JPanels to the extra row. The three empty JPanels are added to keep the GridLayout happy.''

''Optional: add the JButton to a panel and add that to the <code>form</code> instead of adding just a JButton.''


==Knowing when you are done==
'''TODO: finish'''
You are done with this task when the following is true:
* You understand how to
** build
** <s>deploy</s>
** run
*: the GUI
* Can manually query your Web API via HTTP using your generated query strings, and see that the requests works

You shall write in your diary (see workshop for details) what you have written and how that code works. You shall also explain how the overall system works and is intended to work.

== About your report ==