#{extends '../main.html'/}#
#{set title:'Webpieces Design'/}#
#{set tab:'management'/}#

<ol>
   <li><a href="#prg">PRG Pattern</a></li>
   <li><a href="#webpiecesDesign">Webpieces Design</a></li>
   <li><a href="#postMVC">MVC POST request</a></li>
   <li><a href="#getMVC">MVC GET request</a></li>
</ol>

<h2 id="prg">PRG</h2>

<p>Many webservers allow developers to make the mistake where the following windows will pop up to users.</p>  

<img src="%[/org/webpieces/plugin/documentation/resubmit_chrome.png]%"/>

<p>This prompt is confusing as hell to users and you should never show this dialogue....ever!  This is the fault of</p>

<ol>
   <li>The developer writing the application and not following the PRG pattern</li>
   <li>The platform itself not preventing the developer from making this mistake</li>
</ol>

<p>Webpieces forces you into the PRG pattern such that you cannot send a response to a post that is not a redirect unless</p>

<ol>
   <li>you are creating an api</li>
   <li>you are creating an ajax request which requires a response</li>
</ol>

<p>For all html pages, POST requests always result in a redirect saving you many many headaches.</p>

<p>More information can be found on the <a href="https://en.wikipedia.org/wiki/Post/Redirect/Get">Wikipedia PRG page</a></p>

<p>Next, on a POST request with all the user data like user name, email, phone number, address, password, since we are sending a 
redirect back, we could possibly lose what the user typed in.  This would be really annoying to the user and is where the 
'Flash Scope' comes into play.  The Flash Scope is a special cookie where the user info is saved on the post and destroyed 
after the GET request.  Post, Redirect, Get happens so fast, this scope only lasts milliseconds over a good network connection.</p>

<p>With this new information, we can now look closer at the MVC pattern with respect to </p>

<ul>
  <li>POST and 303 REDIRECT response</li>
  <li>GET and 200 OK render response.</li>
</ul>


<p>As a side note, http does have PUT and DELETE so essentially, the CRUD operations(Create, Read, Update, Delete) in theory are
POST, GET, PUT, DELETE in http.  However, due to legacy reasons, browsers only use POST for forms not PUT so even on updates/deletes,
a POST will be performed instead of a PUT or DELETE.  This is just the way browsers work.  In theory, some developers may see this
as unclean but in practice, it really doesn't hurt that much in terms of creating a webserver.  If you are developing an JSON api,
you 'could' use all 4, but again in practice, clients and customers really don't give a crap, but we leave the apis up to you. We
have found what is far more important is the documentation behind the api rather than these types of detailed decisions.</p>

<h2 id="webpiecesDesign">Webpieces Design</h2>

<p>Webpieces is designed such that EVERYTHING is a library including the main webserver.  Here is a full picture of the dependencies between
the most important jar files.</p>

<img src="%[/org/webpieces/plugin/documentation/webpiecesDesign.jpg]%"/>

<p>Notice that http-webserver really only depends on 3 things to create the webserver</p>

<ol>
   <li>http-frontend2 - By using this library, you deal with http messages and stop dealing with sockets.  This is the only piece you need if you want to create a micro-webserver</li>
   <li>http-router - The http-webserver listends to http-frontend2 and translates/feeds requests into http-router</li>
   <li>http-templating - The http-templating is responsible for rending html templates when the webserver tells it to</li>
</ol>

<p>Notice that any one of these pieces could be taken to build another webserver.  http-router actually knows nothing about http
and only knows of a RouterRequest keeping it independet of protocol.  http-webserver is the glue between these 3 main pieces of
the webserver.</p>
  
<p>Of course, digging deeper, http2-frontend2 depends on even more pieces and in fact some of those pieces are what are used to
build the http-client that is independent of the http-webserver.</p>

<p>Requests in bytes come into the 'core-channelmanager' at which point 'http-frontend' is listening and receives those bytes and 
has the http1 or http2 parser parse the bytes.  http-frontend does http1/http2 detection when the socket connects for the first
time.  Once http-frontend has parsed the bytes into an http object, it fires it to the a listener.  The listener was added
by the http-webserver.  At this point, the http-webserver translates the http request into a router request for the router and
calls the router.  The router then finds the route and calls the controller which sends back redirect or render response.  In the
case of render response, the webesrver then calls into http-templating to render a response and sends that back to the client.
If the controller sends back a redirect, the http-templating is skipped.</p>

<h2 id="postMVC">MVC with POST Request</h2>

<p>A Webpieces application follows the MVC(Model-View-Controller) architectural pattern applied to the web architecture.</p>

<p>This pattern splits the application into separate layers: </p>

<dl>
    <dt>Controller</dt>
    <dd>The Controller responds to events (typically user actions) and processes them, and may also invoke changes 
    on the model. In a Web application, events are typically HTTP requests: a Controller listens for HTTP 
    requests, extracts relevant data from the ‘event’, such as query string parameters, request 
    headers… and applies changes to the underlying model objects.</dd> 
    <dt>Model</dt>
    <dd>The Model is the domain-specific representation of the information on which the application operates. 
    Domain logic adds ‘meaning’ to raw data (e.g., calculating if today is the user’s birthday, or the
     totals, taxes, and shipping charges for a shopping cart). Most applications use a persistent 
     storage mechanism such as a database to store data. MVC does not specifically mention the 
     data access layer because it is understood to be underneath, or encapsulated by, the Model.</dd>
    <dt>View</dt>
    <dd>The View renders the model into a form suitable for interactions, typically a user interface. 
    Multiple views can exist for a single model, for different purposes. In a Web application 
    the view is usually rendered in a ‘web format’ like HTML, XML or JSON. However there are 
    some cases where the view can be expressed in a binary form, e.g. dynamically rendered chart diagrams.</dd>
</dl>

<p>I want to be clear about this next picture.  http-frontend does NOT depend on webserver but rather the webserver adds a listener
to http-frontend so it can receive all new http requests, but this diagram is 'not' a dependency diagram but an object flow 
diagram so you can see how requests flow through the pieces of webpieces and to your controller</p>

<img src="%[/org/webpieces/plugin/documentation/postMVC.jpg]%"/>

<p>Again, the 3 situations a POST will occur are create/update/delete.  From the user perspective, for create or update, he is just
filling in a form and clicking save or submit.</p>

<ol>
    <li>A POST request comes in from a form the user is posting</li>
    <li>http-frontend receives bytes, creates an http object and sends to webserver</li>
    <li>http-websever translates to RouterRequest and sends to router</li>
    <li>http-router finds 'your' controller and method to invoke and invokes that</li>
    <li>Your controller does validation and if correct saves it to the database</li>
    <li>Your controller responds with a redirect to either the same page(invalid data) or to a new page</li>
    <li>http-router fires response to http-webserver</li>
    <li>http-webserver translates RouterResponse to http response and sends to http-frontend</li>
    <li>http-frontend sends back the ultimate redirect response to the browser</li>
</ol>

<p>In this diagram, the V in MVC is never used.  All that happens is the controller validates the values in the form and 
saves the model to the database and then redirects the browser to a new page perhaps to display the newly created record.
We show the GET request in the next section for reading that newly created record.</p>

<h2 id="getMVC">GET MVC</h2>

<p>The flow for a GET http request looks like so</p>

<img src="%[/org/webpieces/plugin/documentation/getMVC.jpg]%"/>

<ol>
    <li>A GET request comes in as the user requests a url</li>
    <li>http-frontend receives bytes, creates an http object and sends to webserver</li>
    <li>http-websever translates to RouterRequest and sends to router</li>
    <li>http-router finds 'your' controller and method to invoke and invokes that</li>
    <li>Your controller loads the model from the database</li>
    <li>Your controller responds with a RenderResponse(or a RedirectResponse)</li>
    <li>http-router fires response to http-webserver</li>
    <li>http-webserver calls http-templating to render a template</li>
    <li>http-templating returns the rendered page</li>
    <li>http-webserver returns the http response to frontend</li>
    <li>http-frontend returns the 200 OK and page content to the browser</li>
</ol>

One big note that is the templating engine will be skipped if your controller decides to return a RedirectResponse.
This is useful for security like the user is not logged in or perhaps the model is not found in the database and you can
redirect to a similar page that loads a different thing.  While processing a POST can only return a http 303 REDIRECT, 
processing a GET request can return much more than that like 404 NotFound, 200 OK, or 303 REDIRECT