Improved Documentation

Author: thomasWeise

README.md

@@ -47,7 +47,7 @@ As said, we start at the very bottom: Communication in distributed systems today
 
 The [world wide web](https://en.wikipedia.org/wiki/World_Wide_Web) is based on three pillars: [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol), [HTML](https://en.wikipedia.org/wiki/HTML)/[CSS](https://en.wikipedia.org/wiki/Cascading_Style_Sheets)/[Javascript](https://en.wikipedia.org/wiki/JavaScript), and [URLs](https://en.wikipedia.org/wiki/Uniform_Resource_Locator). HTTP, the Hyper Text Transfer Protocol, is a text-based protocol to query resources which is usually transmitted over TCP connections. Actually, we already provide  example implementations of both the [server](http://github.com/thomasWeise/distributedComputingExamples/tree/master/sockets/java/src/MinHTTPServer.java) ([web server](https://en.wikipedia.org/wiki/Web_server)) and [client](http://github.com/thomasWeise/distributedComputingExamples/tree/master/sockets/java/src/MinHTTPClient.java) ([web browser](https://en.wikipedia.org/wiki/Web_browser)) client side of the HTTP communication using [sockets](http://github.com/thomasWeise/distributedComputingExamples/tree/master/sockets/java) (and even a small [parallel web server](http://github.com/thomasWeise/distributedComputingExamples/tree/master/sockets/java/src/MinHTTPServerThreadPool.java). We then provide some rudimentary [examples](http://github.com/thomasWeise/distributedComputingExamples/tree/master/html/) for [HTML](http://github.com/thomasWeise/distributedComputingExamples/tree/master/html/example_pain/index.html), [CSS](http://github.com/thomasWeise/distributedComputingExamples/tree/master/html/example_css/index.html), and [JavaScript](http://github.com/thomasWeise/distributedComputingExamples/tree/master/html/example_javascript_calculator/index.html).
 
-Implementing HTTP based on sockets is quite complex. Sockets allow us access TCP. What we would like to have is a similarly elegant API to access HTTP (the next higher level of abstraction). One such technology are [Java Servlets](https://en.wikipedia.org/wiki/Java_Servlet). Servlets are used to implement the server-side of a HTTP conversation. A servlet is a sub-class of a special Java class which implements handler methods for different HTTP interactions ("HTTP methods"). These methods are called by a [servlet container](https://en.wikipedia.org/wiki/Web_container), the actual implementation of the server. We can therefore fully concentrate on the application logic and don't need to worry about the protocol interaction itself. We provide a wide range of examples for [Java Servlets](http://github.com/thomasWeise/distributedComputingExamples/tree/master/javaServlets/), both [deployable examples](http://github.com/thomasWeise/distributedComputingExamples/tree/master/javaServlets/examples) as well as a stand-alone [HTTP Proxy Servlet](http://github.com/thomasWeise/distributedComputingExamples/tree/master/javaServlets/proxy). So with Java Servlets, we can build server components that can dynamically interact with a HTTP client (such as a web browser). This means that we can dynamically generate contents of a web page when a browser requests them. However, building complete dynamic web sites as Java Servlets is again quite cumbersome, as servlets are Java classes while web pages are HTML, which we would then write in form of string constants to be written to the output of a Servlet.
+Implementing HTTP based on sockets is quite complex. Sockets allow us access TCP. What we would like to have is a similarly elegant API to access HTTP (the next higher level of abstraction). One such technology are [Java Servlets](https://en.wikipedia.org/wiki/Java_Servlet). Servlets are used to implement the server-side of a HTTP conversation. A servlet is a sub-class of a special Java class which implements handler methods for different HTTP interactions ("[HTTP methods](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods)"). These methods are called by a [servlet container](https://en.wikipedia.org/wiki/Web_container), the actual implementation of the server. We can therefore fully concentrate on the application logic and don't need to worry about the protocol interaction itself. We provide a wide range of examples for [Java Servlets](http://github.com/thomasWeise/distributedComputingExamples/tree/master/javaServlets/), both [deployable examples](http://github.com/thomasWeise/distributedComputingExamples/tree/master/javaServlets/examples) as well as a stand-alone [HTTP Proxy Servlet](http://github.com/thomasWeise/distributedComputingExamples/tree/master/javaServlets/proxy). So with Java Servlets, we can build server components that can dynamically interact with a HTTP client (such as a web browser). This means that we can dynamically generate contents of a web page when a browser requests them. However, building complete dynamic web sites as Java Servlets is again quite cumbersome, as servlets are Java classes while web pages are HTML, which we would then write in form of string constants to be written to the output of a Servlet.
 
 The next higher level of abstraction are [JavaServer Pages](https://en.wikipedia.org/wiki/JavaServer_Pages) (JSPs), which allow us to write HTML pages (or other text formats) and include Java source code in it. The pages are then served again by a servlet container. Whenever a page is sent to a client, the included Java code is first executed on the server side (and may generate additional output). Upon closer inspection, we can find that JSPs are actually "special" servlets: When a JSP is accessed for the first time, the servlet container dynamically creates the source code of a corresponding Java Servlet. This servlet is compiled, loaded, and then executed to create the dynamic content of the page to be sent to the client. Everything which was "text" in JSP becomes a String inside the servlet which is written to the servlet's HTTP response. Everything which was "code" in the JSP is copied directly into the handler methods of the servlet. JSPs are a more natural way to dynamically generate text (HTML) output and serve it to a client. By now, we have a solid understanding how dynamic contents in the web can be generated, how a user can interact with a web application via web forms by using her browser, and how we can realize sessions.
 

html/README.md

@@ -2,6 +2,16 @@
 
 Here you can find some _very simple_ examples for [HTML](https://en.wikipedia.org/wiki/HTML), [CSS](https://en.wikipedia.org/wiki/Cascading_Style_Sheets), and [JavaScript](https://en.wikipedia.org/wiki/JavaScript).
 
+The [world wide web](https://en.wikipedia.org/wiki/World_Wide_Web) (WWW) is based on three pillars: [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol), [HTML](https://en.wikipedia.org/wiki/HTML)/[CSS](https://en.wikipedia.org/wiki/Cascading_Style_Sheets)/[Javascript](https://en.wikipedia.org/wiki/JavaScript), and [URLs](https://en.wikipedia.org/wiki/Uniform_Resource_Locator). Here we want to focus on the second pillar: The most common standards used to build web pages.
+
+HTML , the hyper text markup language, allows us to write documents which can contain structured text (headlines, paragraphs, tables), but also graphics, or videos, and - most importantly - can be linked to other HTML documents. Such links are the very basis for the WWW, they form the "web".
+
+HTML alone is limited in several ways: First, there are not so many ways to create a visual appealing style for a web page. Yes, we can set table borders, images, fonts, bold/italic, etc., but that's pretty much it. Also, we would ideally like to separate the content of a page from the style and/or have multiple styles for a given page, maybe one for displaying on a screen and one for printing. Second, a HTML page is dead, it does perform no activity. But maybe we want some activity? Maybe we want to dynamically load some additional contents, maybe we want to have menus that fade in and out when the moves hovers over them.
+
+We can solve the first shortcoming by using CSS. Stylesheets allow us to specify, for basically each HTML element, how it should be displayed. We can choose from a much richer pool of stylistic elements. And we can separate the style away from the page into a separate file. This way, all of the web pages of our web site can use the same style. If we change the style, it will automatically apply to the whole page. And we can have different styles for printing and displaying on a screen.
+
+The second shortcoming, the "deadness" of the pages, is solved by using JavaScript. JavaScript is a programming language, while HTML is not. Hence, we can specify activities in JavaScript. We can dynamically modify the current page (which also means that we can dynamically add content and load it from different sources) and react to user input. We can execute certain actions and code if the user clicks a specific button or link. Long story short: With JavaScript, we can create the feeling of using a real local application on the client side, in the web browser of our user.
+
 ## 1. `example_plain`
 
 Just a plain HTML document with an image inside.

javaServerPages/README.md

@@ -1,6 +1,12 @@
 # Examples for JavaServer Pages
 
-Here you can find examples for using [JavaServer Pages](https://en.wikipedia.org/wiki/JavaServer_Pages) (JSPs):
+After we have [learned](http://github.com/thomasWeise/distributedComputingExamples/tree/master/javaServlets/) about [Java Servlets](https://en.wikipedia.org/wiki/Java_Servlet), we know basically how we can build dynamic web applications based on [HTML](http://github.com/thomasWeise/distributedComputingExamples/tree/master/html/), [web forms](https://en.wikipedia.org/wiki/Form_%28HTML%29), [Javascript](https://en.wikipedia.org/wiki/JavaScript), and servlets. In a servlet class, the HTML is contained as String constants. The strings are then written to the output sent to the browser.
+
+Now, this method gets relatively quickly awkward when the size of the website increases. Again, all the HTML contents are string constants in a Java class. Changes become harder and just understanding the page takes a lot of time. If we think about it, often we may have much more HTML code than Java code in a reactive page. Thus, the "inverse" idea would be nice to have: A HTML file containing some Java code, able to reference other Java classes. [JavaServer Pages](https://en.wikipedia.org/wiki/JavaServer_Pages) (JSPs) are just that. HTML (or other text files) which contain Java code.
+
+A JSP is also served by a [servlet container](https://en.wikipedia.org/wiki/Web_container). The first time a JSP is accessed, it is translated to a Java Servlet. The HTML code becomes Strings, the Java (original embedded in the HTML) becomes pure Java code, and some Java code (class declaration and stuff) is wrapped around that. This servlet is then compiled a Java class. This class is then executed exactly like a default servlet.
+
+We can now build applications in a fashion similar to what we would do with [PHP](https://en.wikipedia.org/wiki/PHP) but use the whole stack of technologies we already discussed: servlets, sockets, threads, and Java. Here are our examples for this:
 
 1. [deployable examples](http://github.com/thomasWeise/distributedComputingExamples/tree/master/javaServerPages/examples)
 2. [stand-alone JSPs](http://github.com/thomasWeise/distributedComputingExamples/tree/master/javaServerPages/standAloneJSPsWithJetty)

javaServlets/README.md

@@ -1,6 +1,14 @@
 # Examples for Java Servlets
 
-Here you can find examples for using [Java Servlets](https://en.wikipedia.org/wiki/Java_Servlet):
+After we have learned about [sockets](http://github.com/thomasWeise/distributedComputingExamples/tree/master/sockets/) and [HTML](http://github.com/thomasWeise/distributedComputingExamples/tree/master/html/), we are able to develop nice web pages and we can also send data over the internet using [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol). It may occur to us that a [web server](https://en.wikipedia.org/wiki/Web_server) is actually just sending HTML and stuff over the net, using sockets. The [web browser](https://en.wikipedia.org/wiki/Web_browser) then receives the data and displays it. Of course, they cannot just use TCP for communication, as the web browser must somehow tell the web server which page or which image (hosted on that server) it wants and the web server needs to say whether the request was successful or not and so on. For this, the [hypertext transfer protocol](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) exist. This protocol is sent via TCP and it is text-based. With the stuff we have learned, we can fully implement it. Actually, we already have done some partial, rudimentary implementations of it in the sockets examples set.
+
+Still, doing this by hand is not just cumbersome, we will probably make many mistakes. What we would like to have is an API for HTTP as comfortable as sockets are for TCP and UDP. [Java Servlets](https://en.wikipedia.org/wiki/Java_Servlet) are this kind of thing. A servlet is a sub-class of a special Java class which implements handler methods for different HTTP interactions ("[HTTP methods](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods)"). These methods are called by a [servlet container](https://en.wikipedia.org/wiki/Web_container), the actual implementation of the server, which then uses sockets, thread pools, and also takes care of the character encoding for us. We can therefore fully concentrate on the application logic and don't need to worry about the protocol interaction itself.
+
+We can create [forms](https://en.wikipedia.org/wiki/Form_%28HTML%29) with HTML whose contents are sent to the web server (or servlet, in our case). This means that we can send information from a browser to our servlets. This information is provided by the servlet container to our servlet. Our servlet may process, store, and use this information for its purposes. It may dynamically create contents as response. This means that we can now build dynamic web applications. We can build applications that run in a web browser and communicate with our server components and which use [Javascript](https://en.wikipedia.org/wiki/JavaScript) in the browser to create the feeling of "local applications" for the user.
+
+There are many different implementations for java servlet containers. Here we use [GlassFish](https://glassfish.java.net/) and [Jetty](http://www.eclipse.org/jetty/). Other notable containers are [Tomcat](http://tomcat.apache.org/) and [JBoss](http://www.jboss.org/).
+
+Long story short, here you can find my [Java Servlets](https://en.wikipedia.org/wiki/Java_Servlet) examples.
 
 1. [deployable examples](http://github.com/thomasWeise/distributedComputingExamples/tree/master/javaServlets/examples)
 2. [HTTP Proxy Servlet](http://github.com/thomasWeise/distributedComputingExamples/tree/master/javaServlets/proxy)