Insert assertion labels and a new appendix that lists all the assertions.

Author: spericas

spec/.gitignore

@@ -18,3 +18,10 @@ spec.synctex.gz
 styles/jsrfrontstyle.aux
 styles/jsrmainstyle.aux
 styles/macros.aux
+chapters/assertions.aux
+chapters/assertions.log
+spec.bbl
+spec.blg
+spec.ent
+spec.thm
+spec.toc

spec/chapters/applications.tex

@@ -11,7 +11,8 @@ \section{\mvc\ Applications}
 \Controller\ and, just like \jaxrs\ applications, zero or more providers. If no
 resources are annotated with \Controller, then the resulting application is a \jaxrs\
 application instead. In general, everything that applies to a \jaxrs\ application
-also applies to an \mvc\ application. 
+also applies to an \mvc\ application. Some \mvc\ applications may be {\em hybrid}
+and include a mix of \mvc\ controllers and \jaxrs\ resource methods.
 
 The controllers and providers that make up an application are configured via an 
 application-supplied subclass of \code{Application} from \jaxrs. An implementation 
@@ -27,7 +28,7 @@ \section{\mvc\ Applications}
 be specified either using the \ApplicationPath\ annotation on the application
 subclass or in the web.xml as part of the \code{url-pattern} element. \mvc\
 applications MUST use a non-empty path or pattern: i.e., {\em "/"} or {\em "/*"} are 
-invalid in \mvc\ applications. 
+invalid in \mvc\ applications \assertref{application-path}. 
 
 The reason for this is that \mvc\ implementations
 often forward requests to the Servlet container, and the use of these

spec/chapters/assertions.tex

@@ -0,0 +1,27 @@
+\chapter{Summary of Assertions}
+\label{assertions}
+
+\begin{description}
+\assert{controller} Controller methods are JAX-RS resource methods annotated with \code{@Controller}.
+\assert{all-controllers} All resource methods in a class annotated with \code{@Controller} must
+be controllers.
+\assert{controller-types} A controller's return type is limited as described in Section 
+\ref{controllers}.
+\assert{void-controllers} Controller methods that return void must be annotated with \code{@View}.
+\assert{cdi-beans} MVC beans are managed by CDI.
+\assert{per-request} Default scope for MVC beans is request scope.
+\assert{validation-result} If validation fails, controller methods must still be called if a 
+\code{ValidationResult} field or property is defined. 
+\assert{event-firing} All events in \code{javax.mvc.event} must be fired. See Javadoc for more
+information on each event in that package.
+\assert{application-path} The application's path must be non-empty.
+\assert{builtin-engines} Implementations must provide support for JSPs and Facelets.
+\assert{extension-engines} CDI beans that implement \code{javax.mvc.engine.ViewEngine} provide
+an extension mechanism for view engines.
+\assert{selection-algorithm} Implementations must use algorithm in Section \ref{selection_algorithm} 
+to select view engines.
+\assert{request-forward} Forward request for which no view engine is found.
+\assert{exception-wrap} Exceptions thrown during view processing must be wrapped.
+\assert{view-resolution} Relative paths to views must be resolved as explained in 
+Section \ref{selection_algorithm}.
+\end{description}

spec/chapters/controllers.tex

@@ -8,8 +8,9 @@ \section{Controllers}
 \label{controllers}
 
 An {\em MVC controller} is a \jaxrs\ \cite{jaxrs} resource method decorated by 
-an \Controller\ annotation. If 
-this annotation is applied to a class, then all methods in it are regarded as controllers. 
+an \Controller\ annotation \assertref{controller}. 
+If this annotation is applied to a class, then all methods in it are regarded as controllers
+\assertref{all-controllers}. 
 Using the \Controller\ annotation on a subset of methods defines a hybrid class in which 
 certain methods are controllers and others are traditional \jaxrs\ resource methods.
 
@@ -33,9 +34,11 @@ \section{Controllers}
 the default media type for a response is assumed to be \code{text/html}, but otherwise can
 be declared using \Produces\ just like in \jaxrs.
 
-The return type of a controller method is restricted to be one of four possible types:
+The return type of a controller method is restricted to be one of four possible types
+\assertref{controller-types}:
 \begin{description}
-\item[void] A controller method that returns void is REQUIRED to be decorated by \View. 
+\item[void] A controller method that returns void is REQUIRED to be decorated by \View
+\assertref{void-controllers}. 
 \item[String] The string returned is interpreted as a path to a view. 
 \item[Viewable] A \Viewable\ is a class that encapsulates information about a view and
 how it is processed.
@@ -84,10 +87,11 @@ \subsection{Controller Instances}
 
 Unlike in \jaxrs\ where resource classes can be native (created and managed by \jaxrs), 
 CDI beans, managed beans or EJBs, \mvc\ classes are REQUIRED to be CDI-managed beans 
-only. It follows that a hybrid class that contains a mix of \jaxrs\ resource methods 
-and \mvc\ controllers must also be CDI managed. 
+only \assertref{cdi-beans}. It follows that a hybrid class that contains a mix 
+of \jaxrs\ resource methods and \mvc\ controllers must also be CDI managed. 
 
-Like in \jaxrs, the default resource class instance lifecycle is {\em per-request}.
+Like in \jaxrs, the default resource class instance lifecycle is {\em per-request}
+\assertref{per-request}.
 That is, an instance of a controller class MUST be instantiated and initialized 
 on every request. Implementations MAY support other lifecycles via CDI; the same caveats 
 that apply to \jaxrs\ classes in other lifecycles applied to \mvc\ classes. In particular, 
@@ -234,5 +238,3 @@ \section{Views}
 depending on which controller from Section \ref{models} triggered this view's 
 processing.
 
-%% CONTROLLERS
-%% Computation of Content-Type - Sectin 3.8 in JAX-RS

spec/chapters/engines.tex

@@ -13,11 +13,12 @@ \section{Introduction}
 (i) locating and loading a view (ii) preparing any required models and (iii) rendering the 
 view and writing the result back to the client. 
 
-Implementations MUST provide built-in support for JSPs and Facelets view engines. Additional
+Implementations MUST provide built-in support for JSPs and Facelets view engines
+\assertref{builtin-engines}. Additional
 engines may be supported via an extension mechanism based on CDI. Namely, any CDI bean
 that implements the \code{javax.mvc.engine.ViewEngine} interface MUST be considered as
 a possible target for processing by calling its \code{support} method, discarding the
-engine if this method returns \code{false}.
+engine if this method returns \code{false} \assertref{extension-engines}.
 
 This is the interface that must be implemented by all \mvc\ view engines:
 
@@ -39,32 +40,34 @@ \section{Selection Algorithm}
 the following algorithm assumes only \Viewable\ as input.
 
 Implementations should perform the following steps while trying to find
-a suitable view engine for a \Viewable.
+a suitable view engine for a \Viewable \assertref{selection-algorithm}.
 
 \begin{enumerate}
 \item If calling \code{getViewEngine} on the \Viewable\ returns a non-null value, return
 that view engine.
-\item Otherwise, lookup all instances of \code{javax.mvc.engine.ViewEngine} available via CDI.~\footnote{The \code{@Any} annotation in CDI can be used for this purpose.}
+\item Otherwise, lookup all instances of \code{javax.mvc.engine.ViewEngine} available via 
+CDI.~\footnote{The \code{@Any} annotation in CDI can be used for this purpose.}
 \item Call \code{supports} on every view engine found in the previous step, discarding
 those that return \code{false}.
 \item If the resulting set is empty, return \code{null}.
 \item Otherwise, sort the resulting set in descending order of priority using the integer value 
-from the \Priority\ annotation decorating the view engine class or the default value \code{Priorities.DEFAULT} if the annotation is not present.
+from the \Priority\ annotation decorating the view engine class or the default value
+ \code{Priorities.DEFAULT} if the annotation is not present.
 \item Return the first element in the resulting sorted set, that is, the view engine with
 the highest priority that supports the given \Viewable.
 \end{enumerate}
 
 If a view engine that can process a \Viewable\ is not found, as a fall-back attempt to 
 process the view by other means, implementations are 
 REQUIRED to forward the request-response pair back to the Servlet container using a 
-\code{RequestDispatcher}.
+\code{RequestDispatcher} \assertref{request-forward}.
 
 The \code{processView} method has all the information necessary for processing
 in the \code{ViewEngineContext},
 including the view, a reference to \Models, as well as the HTTP request and response
  from the underlying the Servlet container. Implementations MUST catch
 exceptions thrown during the execution of \code{processView} and re-throw them as 
-\code{ViewEngineException}'s. 
+\code{ViewEngineException}'s \assertref{exception-wrap}.
 
 Prior to the view render phase, all entries available in \Models\ MUST be bound in
 such a way that they become available to the view being processed. The exact mechanism
@@ -73,9 +76,11 @@ \section{Selection Algorithm}
 \code{HttpServletRequest.setAttribute(String, Object)}; calling this method ensures
 access to the named models from EL expressions.
 
-A view returned by a controller method represents a relative path within an
-application archive. Implementations MUST resolve view paths relative to 
-\code{ViewEngine.DEFAULT\_VIEW\_FOLDER}, which is set to \code{/WEB-INF/views/}.
-Locating views under \code{WEB-INF} ensures that they are not  
-directly accessible to clients as static resources.
+A view returned by a controller method represents a path within an
+application archive. If the path is relative, does not start with \code{/}, implementations 
+MUST resolve view paths relative to \code{ViewEngine.DEFAULT\_VIEW\_FOLDER}, 
+which is set to \code{/WEB-INF/views/}. If the path is absolute, no further processing
+is required \assertref{view-resolution}. It is recommended to use relative paths and a 
+location under \code{WEB-INF} to prevent direct access to views as static resources.
+
 

spec/chapters/events.tex

@@ -10,7 +10,8 @@ \section{Observers}
 \label{observers}
 
 The package \code{javax.mvc.event} defines a number of event types that MUST be 
-fired by implementations during the processing of a request. Implementations MAY
+fired by implementations during the processing of a request \assertref{event-firing}. 
+Implementations MAY
 extend this set and also provide additional information on any of the events defined
 by this specification. The reader is referred to the implementation's documentation
 for more information on event support.

spec/chapters/intro.tex

@@ -87,7 +87,11 @@ \section{Terminology}
 \section{Conventions}
 
 The keywords `MUST', `MUST NOT', `REQUIRED', `SHALL', `SHALL NOT', `SHOULD', `SHOULD NOT', 
-`RECOMMENDED', `MAY', and `OPTIONAL' in this document are to be interpreted as described in RFC 2119\cite{rfc2119}. 
+`RECOMMENDED', `MAY', and `OPTIONAL' in this document are to be interpreted as described in 
+RFC 2119\cite{rfc2119}. 
+
+Assertions defined by this specification are formatted as {\textbf{\lllb{an-assertion}\rrrb}} 
+using a descriptive name as the label and are all listed in Appendix \ref{assertions}.
 
 Java code and sample data fragments are formatted as shown in figure \ref{ex1}:
 

spec/chapters/validation.tex

@@ -90,7 +90,7 @@ \section{Validation Exceptions}
 Implementations MUST introspect the controller bean for a field or a property of
 this type to determine the correct semantics; fields and property setters
 of this type MUST be annotated with \code{@Inject} to guarantee proper bean
-initialization.
+initialization \assertref{validation-result}.
 
 Let us revisit the example from Section~\ref{exception_mappers},
 this time using the controller method as an exception handler:

spec/spec.pdf

@@ -92,6 +92,7 @@
   \markboth{\appendixname
   \ \thechapter.\ #1}{}}
 
+\include{chapters/assertions}
 \include{chapters/annotations}
 %\include{chapters/changes}