Project 2: Tomcat-Based Markdown Editor

Description

In Project 2, we will develop an online “markdown” editor using Apache Tomcat. Through this
process we will learn:
1. How to develop a Web application using a “traditional” stack, in particular, MySQL and Apache
Tomcat (Java servlet)
2. How to use CSS to format and layout a Web page
In later projects, we will use more “modern” Web development stack, such as MongoDB, Node.js,
and Angular, but we want to make sure that everyone has an experience with developing Web
applications on a more “traditional” stack. This will help students understand and appreciate why
modern frameworks are structured as they are. All development for Project 2 will be done on the
“tomcat” container that you created from “junghoo/cs144-tomcat” image in Project 1. Make sure
that container still starts and works fine by issuing the following command in a terminal window:
$ docker start -i tomcat
Part A: Learn Apache Tomcat
Before starting to code, first learn how we develop a Web application using Apache Tomcat by going
over our tutorial:
Developing a Web Application on Tomcat.
The tutorial teaches how you can develop a Web application using Java Servlet and JSP, and how
you can package the set of files needed for your app into a single Web Application Archive (WAR)
file for easy deployment on Tomcat.
Part B: Learn JDBC
12/13/2018 Project 2: Tomcat-Based Markdown Editor
http://oak.cs.ucla.edu/classes/cs144/project2/index.html 2/13
In order to access MySQL data from a Java program, you will need to use JDBC (Java DataBase
Connectivity) API. Go over the following tutorial to learn how to use JDBC to access MySQL in a
Java program.
A short tutorial on JDBC
Part C: Implement Markdown Editor and Previewer
Now that you have learned how to develop applications on Tomcat and MySQL, it is time to get your
real work done. In Part C, you will need to implement an “online markdown editor” that allows users
to save and edit blog posts written in markdown.
Markdown is a lightweight and intuitive markup language originally proposed by John Gruber in
2004 to help people “write using an easy-to-read, easy-to-write plain text format, and optionally
convert it to structurally valid XHTML (or HTML)”. Due to its simplicity, markdown has become the
de-facto standard for writing readme files on many web sites (e.g., GitHub and BitBucket). In fact,
this page was originally written in markdown and has been converted to HTML using Pandoc! Since
we will use an “off-the-shelf” markdown parsing library in Java for this project, you don’t have to
learn markdown syntax, but in case you are interested, here is a 2-minute introduction to markdown
syntax. For your reference, John Gruber’s description of markdown syntax is available here (highly
recommended if you want to learn more precise syntax) and the result of recent standardization
efforts, referred to as CommonMark, is available here (extremely detailed and precise, yet boring to
read).
“Pages” Within Your Application
Your Web site should allows users to create a new post (written in markdown), preview the post
(rendered in HTML), and manage existing posts. These tasks are supported through three main
pages on your Web site: edit, preview, and list pages
Edit page
The “edit page” allows editing the title and body of a post.
The page should contain two input boxes
1. a title box of text type. This text input element must have the ID attribute with
value “title”.
2. a body . This textarea element must have the ID attribute with value “body”.<br /><br /> The page should contain four buttons: save, close, preview, and delete. Once pressed,<br /><br /> 1. “save” button saves the content of the post to the database and goes to the “list page”.<br /><br /> 12/13/2018 Project 2: Tomcat-Based Markdown Editor<br /><br /> http://oak.cs.ucla.edu/classes/cs144/project2/index.html 3/13<br /><br /> 2. “close” button goes to the “list page” without saving the<br /><br /> current content.<br /><br /> 3. “preview” button goes to the “preview page” (without<br /><br /> saving the current content).<br /><br /> 4. “delete” button deletes the post from the database and<br /><br /> goes to the “list page”.<br /><br /> Preview page<br /><br /> The “preview page” shows the HTML rendering of a post written<br /><br /> in markdown. The page must have a “close” button. Once<br /><br /> pressed, close button goes back to the “edit page” of the post.<br /><br /> List page<br /><br /> The “list page” shows the list of all blog posts saved by the user.<br /><br /> The posts in the list should be sorted by their “postid” (a unique<br /><br /> integer assigned to a post) in the ascending order. Each item in<br /><br /> the list must show:<br /><br /> 1. title, creation, and modification dates of the post, and<br /><br /> 2. two buttons: open and delete. Once pressed,<br /><br /> “open” button goes to the “edit page” for the post.<br /><br /> “delete” button deletes the post from the database and<br /><br /> comes back to the list page.<br /><br /> 12/13/2018 Project 2: Tomcat-Based Markdown Editor<br /><br /> http://oak.cs.ucla.edu/classes/cs144/project2/index.html 4/13<br /><br /> The list page should also contain a “new post” button to allow users to create a new post. Once<br /><br /> pressed, the button should lead to the “edit page” for a new post.<br /><br /> To help you better understand the function of the three pages on your site and their interaction<br /><br /> model, we made an example demo site available at http://oak.cs.ucla.edu/editor/post?<br /><br /> action=list&username=junghoo. To encourage you to create your own CSS styles for your site, we<br /><br /> removed all CSS styling tags in the demo, so it looks ugly. But you can still get an idea of how the<br /><br /> three pages should interact and function. For security concerns, we do not perform any update<br /><br /> operation to our database. Even if you “delete” a post, for instance, it won’t disappear from the list.<br /><br /> Note: The three “pages” that we described above may not necessarily be three separate HTML<br /><br /> pages. Depending on your implementation, they may be implemented as one or more HTML pages,<br /><br /> Java servlets and/or JSP pages. You may consider “three pages” as three classes of page layouts that<br /><br /> your application should use.<br /><br /> Server-Side API<br /><br /> In developing your application, you should follow the following REST API. First, you should make<br /><br /> your application available at the following path:<br /><br /> /editor/post?action=type&username=name&postid=num&title=title&body=body<br /><br /> The path is case sensitive. You must use exactly the same case as above both for the the initial path<br /><br /> prefix and the parameters. The parameter “action” specifies one of five “actions” that your site has to<br /><br /> take: open, save, delete, preview, and list. The other four parameters, username, postid, title, and<br /><br /> body are (optional) parameters that the actions may need. Here is detailed descriptions of the five<br /><br /> actions – their functions and required parameters:<br /><br /> open<br /><br /> required parameters: username and postid<br /><br /> function: return the “edit page” for the post with the given postid by the user<br /><br /> If postid <= 0, if title and body parameters have been passed, use the passed parameter values as the initial title and body values and return with status code 200 (OK) otherwise, set missing title and/or body to empty string and return with status code 200 (OK) If postid > 0,<br /><br /> if title and body parameters have been passed, use the passed parameter values as the<br /><br /> initial title and body values and return with status code 200 (OK)<br /><br /> otherwise<br /><br /> 12/13/2018 Project 2: Tomcat-Based Markdown Editor<br /><br /> http://oak.cs.ucla.edu/classes/cs144/project2/index.html 5/13<br /><br /> if (username, postid) row exists in the database, retrieve the title and body from<br /><br /> the database and return with status code 200 (OK).<br /><br /> otherwise, return with status code 404 (Not found).<br /><br /> save<br /><br /> required parameters: username, postid, title, and body<br /><br /> function: save the post into the database and go to the “list page” for the user<br /><br /> if postid <= 0 assign a new postid, and save the content as a “new post” if postid > 0<br /><br /> if (username, postid) row exists in the database, update the row with new title, body,<br /><br /> and modification date.<br /><br /> if (username, postid) row does not exist, do not make any change to the database<br /><br /> delete<br /><br /> required parameters: username and postid<br /><br /> function: delete the corresponding post and go to the “list page”<br /><br /> preview<br /><br /> required parameters: username, postid, title, and body<br /><br /> function: return the “preview page” with the html rendering of the given title and body<br /><br /> list<br /><br /> required parameters: username<br /><br /> function: return the “list page” for the user<br /><br /> NOTE:<br /><br /> 1. Among the five actions, you should take requests via both GET and POST methods for open,<br /><br /> preview, and list, while you should allow only POST method for save and delete. This is<br /><br /> because save and delete leave significant side effects on the server.<br /><br /> 2. When the server cannot handle a request because the request is “invalid” – for example, the<br /><br /> request does not include a required parameter – the server must return with a 4XX response<br /><br /> status code, such as “400 (Bad request)” or “404 (Not found)”. The server should never<br /><br /> return a 5XX response status code because of an invalid request. Look up this page to<br /><br /> 12/13/2018 Project 2: Tomcat-Based Markdown Editor<br /><br /> http://oak.cs.ucla.edu/classes/cs144/project2/index.html 6/13<br /><br /> see the list of HTTP response status codes and their meaning. Refer to the<br /><br /> HttpServletResponse API to learn how to set the HTTP status code in Servlet.<br /><br /> In case of confusion, you may want to reference our demo site, since it follows the above described<br /><br /> API.<br /><br /> NOTE: During our grading, we won’t be doing extensive check for security related issues, but there<br /><br /> are two things that we may test:<br /><br /> 1. Your implementation should do the basic input validation. For example, we do expect that<br /><br /> students make sure that postid is integer.<br /><br /> 2. Your implementation should use preparedStatement in your SQL queries as a basic<br /><br /> protection against SQL injection attack. As we mentioned in our JDBC tutorial, we expect<br /><br /> students to follow this industry-wise convention, which cannot be overemphasized as a minimal<br /><br /> security measure.<br /><br /> Whatever the user input, it will be important that your implementation won’t flake out (like<br /><br /> throwing Java exception messages as the output). All requests need to be handled gracefully,<br /><br /> however malformed they may be.<br /><br /> Note on Multi­Threading:<br /><br /> Tomcat creates one thread per each request and concurrent data manipulation can be taken care of<br /><br /> by MySQL. This makes server-side programming easy since the programmer doesn’t have to worry<br /><br /> about concurrency. But in order to do things this way, you need to keep two things in mind:<br /><br /> 1. JDBC API is thread-safe only if each thread uses its own connection. If multiple threads share<br /><br /> the same connection, the behavior is unpredictable. Create one DB connection in each servlet<br /><br /> request handler, such as doGet() and close it before you return from the handler.<br /><br /> 2. Any servlet request handler must not use global states. Any global state that needs to be<br /><br /> shared between multiple requests must be stored and managed by MySQL. In particular,<br /><br /> any servlet request handler, such as doGet() must not reference a class instance variable. It<br /><br /> must reference only local variables.<br /><br /> Note on Connection Pooling:<br /><br /> You may think that creating one DB connection per request will lead to too much overhead and<br /><br /> wonder whether there is any way to “share” the same DB connection among multiple requests. The<br /><br /> proper way to do it is to use connection pooling, but this is beyond the scope of this project.<br /><br /> Connection pooling is something that must be used in a production environment, but you MUST<br /><br /> NOT use connection pooling in this project since it won’t work on the grader’s machine.<br /><br /> Database Schema<br /><br /> 12/13/2018 Project 2: Tomcat-Based Markdown Editor<br /><br /> http://oak.cs.ucla.edu/classes/cs144/project2/index.html 7/13<br /><br /> All blog posts that are saved by the users must be stored as a row a MySQL table with the following<br /><br /> schema:<br /><br /> Hopefully, the meaning of each column would be clear from our earlier discussion. MySQL schema<br /><br /> definition is case sensitive, so be careful with the case of your schema definition. Create the table<br /><br /> within “CS144” table as the user “cs144”. The first blog post of every user must start with postid=1<br /><br /> and their subsequent posts must be assigned to a linearly increasing postid. Therefore, blog posts by<br /><br /> different users may share the same postid, but postid is unique within a single user. In<br /><br /> implementing your app, you may need to create tables other than the “Posts” table to store other<br /><br /> information needed for your app persistently.<br /><br /> Skeleton Code<br /><br /> To help you get started, we provide skeleton sample code for this project in project2.zip, which has<br /><br /> the following set of files:<br /><br /> project2.zip<br /><br /> |<br /><br /> +- build.gradle<br /><br /> +- create.sql<br /><br /> +- deploy.sh<br /><br /> +- src<br /><br /> +- main<br /><br /> +- java<br /><br /> | +- Editor.java<br /><br /> |<br /><br /> +- webapp<br /><br /> +- edit.jsp<br /><br /> +- WEB-INF<br /><br /> +- web.xml<br /><br /> 1. create.sql: This file has has a sequence of SQL commands that create “Posts” table in the CS144<br /><br /> database. If you need to create any additional tables for your app, you will need to add the SQL<br /><br /> Posts(<br /><br /> username VARCHAR(40),<br /><br /> postid INTEGER,<br /><br /> title VARCHAR(100),<br /><br /> body TEXT,<br /><br /> modified TIMESTAMP DEFAULT ‘2000-01-01 00:00:00’,<br /><br /> created TIMESTAMP DEFAULT ‘2000-01-01 00:00:00’,<br /><br /> PRIMARY KEY(username, postid)<br /><br /> )<br /><br /> 12/13/2018 Project 2: Tomcat-Based Markdown Editor<br /><br /> http://oak.cs.ucla.edu/classes/cs144/project2/index.html 8/13<br /><br /> commands to create them in this file.<br /><br /> 2. src/main/java/Editor.java: This is a skeleton Java code for servlet implementation. The<br /><br /> provided code simply dispatches the request to edit.jsp page, so you will need to implement<br /><br /> your application logic as part of the Editor class, such as connecting to, retrieving from, and<br /><br /> updating MySQL database server, and dispatching the user’s request to an appropriate JSP<br /><br /> page.<br /><br /> 3. src/main/webapp/edit.jsp: This is a simple JSP page that contains HTML elements for<br /><br /> implementing the “edit page”. You will need to update this page according to our earlier<br /><br /> specification.<br /><br /> 4. src/main/webapp/WEB­INF/web.xml: This is the Tomcat deployment descriptor file prepared<br /><br /> for this project. Currently, it sends any request to /editor to the Java class Editor.<br /><br /> 5. build.gradle and deploy.sh: These are gradle “build script” and the app deployment script that<br /><br /> you can use to build your WAR file and deploy it to Tomcat. We will explain these scripts in<br /><br /> more detail in the next section.<br /><br /> Gradle build script<br /><br /> As you learned from our tutorial on Tomcat, a Web application needs many files that should be<br /><br /> carefully prepared and packaged. To help you focus on coding, not packaging, we included a “gradle<br /><br /> build script” that takes care of compilation and packaging. To see how it works, unzip project2.zip<br /><br /> into a folder, cd to the folder and run the following command:<br /><br /> $ gradle assemble<br /><br /> This will compile all your Java source files in the src/main/java/ directory (currently, just<br /><br /> “Editor.java”), package them together with everything under src/main/webapp directory<br /><br /> according to the spec, and create a war file at build/libs/editor.war. Once created, you can<br /><br /> copy the war file to $CATALINA_BASE/webapps:<br /><br /> $ cp build/libs/editor.war $CATALINA_BASE/webapps<br /><br /> to deploy it to the Tomcat server. Copy the file, wait for a few seconds (so that Tomcat detects the<br /><br /> new war file and sets it up), and access http://localhost:8888/editor/post?<br /><br /> action=list&username=test from a browser on your host. You will get a (non-functional) version of<br /><br /> the “edit page” that has been generated from the edit.jsp page.<br /><br /> As long as you can use our provided gradle build script to compile your code and create the war file,<br /><br /> it is okay for you to know nothing about how the gradle build script works. But if you want to learn<br /><br /> more, read one of many online tutorials on Gradle.<br /><br /> 12/13/2018 Project 2: Tomcat-Based Markdown Editor<br /><br /> http://oak.cs.ucla.edu/classes/cs144/project2/index.html 9/13<br /><br /> Your job now is to write Java code in Editor.java and (optionally) add new JSP, HTML, CSS<br /><br /> pages to src/main/webapp in order to implement Online Markdown Editor. If you are not sure<br /><br /> how the code in Editor.java works or how to write a JSP page, go over our Tomcat Application<br /><br /> Development Tutorial. If you are not sure how to access a MySQL database with a Java code, go over<br /><br /> our JDBC tutorial.<br /><br /> Note: You may find it helpful that what is written to System.out/err in Tomcat servlet is (1)<br /><br /> printed on console and (2) written to the catalina.out log filelocated in<br /><br /> $CATALINA_BASE/logs/. To access the directory, you will need the root permission. You can start<br /><br /> a bash shell under the root user by the “sudo bash” command, for example.<br /><br /> Commonmark Java Library<br /><br /> To implement the “preview page”, you need to “compile” a markdown-formatted input into an<br /><br /> HTML-formatted output. For this, you can use the commonmark Java library. We have already<br /><br /> downloaded the library and made it available in our “tomcat” container. Go over the the<br /><br /> README.me file on the library page to learn how to use the library. Roughly, the following Java<br /><br /> code<br /><br /> will “compile” the markdown text This is *CS144* into HTML text </p><br /> <p>This is<br /><br /> <em>CS144</em></p><br /> <p>.<br /><br /> Deployment Script deploy.sh<br /><br /> In project2.zip, we also included our “deployment bash script”, deployment.sh, that automates the<br /><br /> entire application deployment process. In particular, it (1) creates tables for our application in<br /><br /> MySQL (2) build the “editor.war” file and (3) deploy it to the Tomcat server. Once you finish<br /><br /> developing your code, make sure that simply running<br /><br /> $ ./deploy.sh<br /><br /> import org.commonmark.node.*;<br /><br /> import org.commonmark.parser.Parser;<br /><br /> import org.commonmark.renderer.html.HtmlRenderer;<br /><br /> …<br /><br /> Parser parser = Parser.builder().build();<br /><br /> HtmlRenderer renderer = HtmlRenderer.builder().build();<br /><br /> String markdown = “This is *CS144*”;<br /><br /> String html = renderer.render(parser.parse(markdown));<br /><br /> /* html has the string “</p><br /> <p>This is <em>CS144</em></p><br /> <p>\n” */<br /><br /> 12/13/2018 Project 2: Tomcat-Based Markdown Editor<br /><br /> http://oak.cs.ucla.edu/classes/cs144/project2/index.html 10/13<br /><br /> properly sets up your application. This script will be used to deploy your application during our<br /><br /> grading, so it is extremely important to make sure that this script works without any error.<br /><br /> Part D: Style Your Application Using CSS (Optional)<br /><br /> Once you finish developing the functional part of the online markdown editor, the required part of<br /><br /> Project 2 is over. But we encourage you to add CSS styling rules to your app, so that the interface is<br /><br /> aesthetically more pleasing. This part, however, is completely optional. As long as your code<br /><br /> functionally satisfies our requirements, you will get the full score for this project.<br /><br /> There are a number of ways that you can implement styling your site. You can specify the detailed<br /><br /> CSS rules all by yourself, without relying on a third-party “CSS frameworks”. This will help you learn<br /><br /> the intricate detail of the CSS standard. Another way is to use a popular framework for Web page<br /><br /> design and styling. For example, Bootstrap is one of the most popular Web front-end library, based<br /><br /> on CSS and Javascript and developed by Twitter. Learning a third-party library will take time and<br /><br /> effort, but once learned, they make it significantly simpler to add beautiful and interactive interface<br /><br /> to your Web site. The sample page layouts in our earlier screenshots were implemented using<br /><br /> W3.CSS library developed by W3schools (which happens to be a favorite of the author because it is<br /><br /> lightweight – only 23KB in size –, relatively easy to learn and use, and adequate for designing simple<br /><br /> Web sites. You are welcome to use a third-party CSS framework as long as you make sure that your<br /><br /> submission runs on the grader’s machine. You can either include the third-party framework in the<br /><br /> submission file or link to the public CSS/JS URL(s) in your HTML output.<br /><br /> To recognize the efforts that you may put into this part of the project, we give you as much as 10%<br /><br /> extra credit, if your efforts and dedication to this part is clear from your submission.<br /><br /> Your Final Submission<br /><br /> Your project must be submitted electronically before the deadline through our CCLE Course<br /><br /> Website. Navigate to Sections on left of the page, and click on the Project 2 submission section. If<br /><br /> you submit multiple times, we will grade only the latest submission.<br /><br /> What to Submit<br /><br /> The zip file that you submit must be named project2.zip, created using a zip compression utility<br /><br /> (like using “zip -r project2.zip *” command in the container). You should submit this single<br /><br /> file project2.zip that has the following packaging structure.<br /><br /> 12/13/2018 Project 2: Tomcat-Based Markdown Editor<br /><br /> http://oak.cs.ucla.edu/classes/cs144/project2/index.html 11/13<br /><br /> project2.zip<br /><br /> |<br /><br /> +- README.txt (optional)<br /><br /> +- TEAM.txt<br /><br /> +- deploy.sh<br /><br /> +- build.gradle<br /><br /> +- create.sql<br /><br /> +- edit.png, preview.png, list.png<br /><br /> +- src<br /><br /> +- main<br /><br /> +- java<br /><br /> | +- Editor.java (and other java files that you wrote)<br /><br /> |<br /><br /> +- webapp<br /><br /> +- edit.jsp (and other jsp, css, and html files that you added)<br /><br /> +- WEB-INF<br /><br /> +- web.xml<br /><br /> We have already explained what most of the above files are earlier, but your submission should<br /><br /> include the following additional files:<br /><br /> 1. README.txt: This optional file should include any information that you need to communicate<br /><br /> to the grader.<br /><br /> 2. TEAM.txt: This file must include the 9-digit university ID (UID) of every team member, one<br /><br /> UID per line. No spaces or dashes. Just 9-digit UID per line. If you are working on your<br /><br /> own, include just your UID.<br /><br /> 3. edit.png, preview.png, list.png: You need to take screenshots of your edit, preview, and list<br /><br /> pages and include them in the zip file.<br /><br /> Please ensure that your submission is packaged correctly with all required files. Make sure that each<br /><br /> file is correctly named (including its case) and project2.zip contains all files directly, not within a<br /><br /> subdirectory. Please do not include complied Java class files or WAR file.<br /><br /> Perhaps, the most important requirement of your submission is that the grader should be able<br /><br /> to deploy a fully functional version of your Web site just by running ./deploy.sh<br /><br /> after unzipping your submission. You may get as small as zero points if the grader<br /><br /> encounters an error due to incorrect packaging, missing files, and failure to follow<br /><br /> our exact spec.<br /><br /> Testing of Your Submission<br /><br /> 12/13/2018 Project 2: Tomcat-Based Markdown Editor<br /><br /> http://oak.cs.ucla.edu/classes/cs144/project2/index.html 12/13<br /><br /> Grading is a difficult and time-consuming process, and file naming and packaging convention is very<br /><br /> important to test your submission without any error. In order to help you ensure the correct<br /><br /> packaging of your submission, we have made a “grading script” p2_test available. In essence, the<br /><br /> grading script unzips your submission to a temporary directory and deploy your files to Tomcat to<br /><br /> test whether they are likely to run OK on the grader’s machine. Download the grading script and<br /><br /> execute it inside the tomcat container:<br /><br /> $ ./p2_test project2.zip<br /><br /> (if your project2.zip file is not located in the current directory, you need to add the path to the zip<br /><br /> file before project2.zip. You may need to use chmod +x p2_test if there is a permission error.)<br /><br /> You MUST test your submission using the script before your final submission to minimize the<br /><br /> chance of an unexpected error during grading. Again, significant points may be deducted if the<br /><br /> grader encounters an error during grading. When everything runs properly, you will see an output<br /><br /> similar to the following from the grading script:<br /><br /> 12/13/2018 Project 2: Tomcat-Based Markdown Editor<br /><br /> http://oak.cs.ucla.edu/classes/cs144/project2/index.html 13/13<br /><br /> $ ./p2_test project2.zip<br /><br /> dropping all tables in CS144 database<br /><br /> building and deploying your application…<br /><br /> :clean UP-TO-DATE<br /><br /> BUILD SUCCESSFUL<br /><br /> Total time: 0.86 secs<br /><br /> :compileJava<br /><br /> :processResources NO-SOURCE<br /><br /> :classes<br /><br /> :war<br /><br /> :assemble<br /><br /> BUILD SUCCESSFUL<br /><br /> Total time: 0.894 secs<br /><br /> Finished deploying your app. Sleeping for 30 seconds for Tomcat to pick it<br /><br /> up…<br /><br /> Requesting http://localhost:8080/editor/post?<br /><br /> action=open&username=test&postid=0&title=&body=<br /><br /> This is the response from Tomcat. Make sure that it is what you expect<br /><br /> <!DOCTYPE html><br /><br /> <html><br /><br /> <head><br /><br /> <meta charset=”UTF-8″><br /><br /> <title>Edit Post</title><br /><br /> </head><br /><br /> <body></p><br /> <div><br /> <h1>Edit Post</h1><br /> </div><br /> <form><br /> …<br /><br /> </form><br /> <p></body><br /><br /> </html><br /><br /> SUCCESS!</p><br />