Javadoc and xml documentation improvements

src/main/java/org/springframework/samples/petclinic/Pet.java

@@ -22,7 +22,7 @@ import org.springframework.beans.support.PropertyComparator;
 import org.springframework.format.annotation.DateTimeFormat;
 
 /**
- * Simple JavaBean business object representing a pet.
+ * Simple business object representing a pet.
  *
  * @author Ken Krebs
  * @author Juergen Hoeller

src/main/java/org/springframework/samples/petclinic/Vets.java

@@ -23,7 +23,7 @@ import javax.xml.bind.annotation.XmlElement;
 import javax.xml.bind.annotation.XmlRootElement;
 
 /**
- * Simple JavaBean domain object representing a list of veterinarians. Mostly here to be used for the 'vets'
+ * Simple domain object representing a list of veterinarians. Mostly here to be used for the 'vets'
  * {@link org.springframework.web.servlet.view.xml.MarshallingView}.
  *
  * @author Arjen Poutsma

src/main/java/org/springframework/samples/petclinic/web/CrashController.java

@@ -9,13 +9,16 @@ import org.springframework.web.bind.annotation.RequestMethod;
  * Controller used to showcase what happens when an exception is thrown
  * 
  * @author Michael Isvy
+ * 
+ * Also see how the bean of type 'SimpleMappingExceptionResolver' has been declared inside /WEB-INF/mvc-core-config.xml
  */
 @Controller
 public class CrashController {	
 
 	@RequestMapping(value="/oups", method = RequestMethod.GET)
 	public String triggerException() {
-		throw new RuntimeException("Something went wrong...");
+		throw new RuntimeException("Expected: controller used to showcase what " +
+				"happens when an exception is thrown");
 	}
 
 	

src/main/java/org/springframework/samples/petclinic/web/OwnerController.java

@@ -21,7 +21,6 @@ import org.springframework.web.bind.support.SessionStatus;
 import org.springframework.web.servlet.ModelAndView;
 
 /**
- * JavaBean form controller that is used to handle <code>Owner</code>s .
  *
  * @author Juergen Hoeller
  * @author Ken Krebs

src/main/java/org/springframework/samples/petclinic/web/PetController.java

@@ -22,8 +22,6 @@ import org.springframework.web.bind.annotation.SessionAttributes;
 import org.springframework.web.bind.support.SessionStatus;
 
 /**
- * JavaBean form controller that is used to add a new <code>Pet</code> to the
- * system.
  *
  * @author Juergen Hoeller
  * @author Ken Krebs

src/main/java/org/springframework/samples/petclinic/web/PetTypeFormatter.java

@@ -11,6 +11,14 @@ import org.springframework.samples.petclinic.PetType;
 import org.springframework.samples.petclinic.service.ClinicService;
 
 /**
+ * Instructs Spring MVC on how to parse and print elements of type 'PetType'.
+ * Starting from Spring 3.0, Formatters have come as an improvement in comparison to legacy PropertyEditors.
+ * See the following links for more details: 
+ * - The Spring ref doc: {@linktourl http://static.springsource.org/spring/docs/current/spring-framework-reference/html/validation.html#format-Formatter-SPI
+ * - A nice blog entry from Gordon Dickens: http://gordondickens.com/wordpress/2010/09/30/using-spring-3-0-custom-type-converter/
+ * 
+ * Also see how the bean 'conversionService' has been declared inside /WEB-INF/mvc-core-config.xml
+ * 
  * @author Mark Fisher
  * @author Juergen Hoeller
  * @author Michael Isvy

src/main/java/org/springframework/samples/petclinic/web/VetController.java

@@ -6,12 +6,9 @@ import org.springframework.samples.petclinic.Vets;
 import org.springframework.samples.petclinic.service.ClinicService;
 import org.springframework.stereotype.Controller;
 import org.springframework.ui.Model;
-import org.springframework.ui.ModelMap;
 import org.springframework.web.bind.annotation.RequestMapping;
 
 /**
- * Annotation-driven <em>MultiActionController</em> that handles all non-form
- * URL's.
  *
  * @author Juergen Hoeller
  * @author Mark Fisher
@@ -29,18 +26,10 @@ public class VetController {
 		this.clinicService = clinicService;
 	}
 
-	/**
-	 * Custom handler for displaying vets.
-	 *
-	 * <p>Note that this handler returns a plain {@link ModelMap} object instead of
-	 * a ModelAndView, thus leveraging convention-based model attribute names.
-	 * It relies on the RequestToViewNameTranslator to determine the logical
-	 * view name based on the request URL: "/vets.do" -&gt; "vets".
-	 *
-	 * @return a ModelMap with the model attributes for the view
-	 */
 	@RequestMapping("/vets")
 	public String showVetList(Model model) {
+		// Here we are returning an object of type 'Vets' rather than a collection of Vet objects 
+		// so it is simpler for Object-Xml mapping
 		Vets vets = new Vets();
 		vets.getVetList().addAll(this.clinicService.findVets());
 		model.addAttribute("vets", vets);

src/main/java/org/springframework/samples/petclinic/web/VisitController.java

@@ -20,12 +20,11 @@ import org.springframework.web.bind.support.SessionStatus;
 import org.springframework.web.servlet.ModelAndView;
 
 /**
- * JavaBean form controller that is used to add a new <code>Visit</code> to the
- * system.
  *
  * @author Juergen Hoeller
  * @author Ken Krebs
  * @author Arjen Poutsma
+ * @author Michael Isvy
  */
 @Controller
 @SessionAttributes("visit")
@@ -65,12 +64,6 @@ public class VisitController {
 		}
 	}
 
-	/**
-	 * Custom handler for displaying an list of visits.
-	 *
-	 * @param petId the ID of the pet whose visits to display
-	 * @return a ModelMap with the model attributes for the view
-	 */
 	@RequestMapping(value="/owners/*/pets/{petId}/visits", method=RequestMethod.GET)
 	public ModelAndView showVisits(@PathVariable int petId) {
 		ModelAndView mav = new ModelAndView("visitList");

src/main/java/org/springframework/samples/petclinic/web/VisitsAtomView.java

-/*
- * Copyright 2002-2009 the original author or authors.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package org.springframework.samples.petclinic.web;
 
 import java.util.ArrayList;

src/main/webapp/WEB-INF/mvc-core-config.xml

@@ -46,12 +46,11 @@
 
 	<!--
 		- This bean resolves specific types of exceptions to corresponding logical 
-		- view names for error views. The default behaviour of DispatcherServlet 
-		- is to propagate all exceptions to the servlet container: this will happen 
-		- here with all other types of exceptions.
+		- view names for error views.
 	-->
 	<bean class="org.springframework.web.servlet.handler.SimpleMappingExceptionResolver">
-		<property name="defaultErrorView" value="exception"/>
+		<!-- view name resolved using bean of type InternalResourceViewResolver (declared in mvc-view-config.xml) -->
+		<property name="defaultErrorView" value="exception"/> <!-- results into 'WEB-INF/jsp/exception.jsp' -->		
 		<property name="warnLogCategory" value="warn"/>
 	</bean>
 

src/test/java/org/springframework/samples/petclinic/web/VisitsAtomViewTest.java

@@ -20,7 +20,6 @@ import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNotNull;
 
 import java.util.ArrayList;
-import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;