svn commit: r1099215 - in /incubator/wookie/trunk/src/org/apache/wookie/updates: UpdatesController.java UpdatesHelper.java

[sc...@apache.org]

Author: scottbw
Date: Tue May  3 19:54:31 2011
New Revision: 1099215

URL: http://svn.apache.org/viewvc?rev=1099215&view=rev
Log:
improved javadoc and comments in updates classes

Modified:
    incubator/wookie/trunk/src/org/apache/wookie/updates/UpdatesController.java
    incubator/wookie/trunk/src/org/apache/wookie/updates/UpdatesHelper.java

Modified: incubator/wookie/trunk/src/org/apache/wookie/updates/UpdatesController.java
URL: http://svn.apache.org/viewvc/incubator/wookie/trunk/src/org/apache/wookie/updates/UpdatesController.java?rev=1099215&r1=1099214&r2=1099215&view=diff
==============================================================================
--- incubator/wookie/trunk/src/org/apache/wookie/updates/UpdatesController.java (original)
+++ incubator/wookie/trunk/src/org/apache/wookie/updates/UpdatesController.java Tue May  3 19:54:31 2011
@@ -46,10 +46,10 @@ import org.apache.wookie.w3c.updates.Upd
 /**
  * Controller for managing widget updates
  * 
- * GET - gets the list of updates available
- * GET/{internal_widget_id} - redirects you to the UDD for the widget
- * POST - attempts to apply ALL available updates
- * PUT/{internal_widget_id} - applies update to specified widget only
+ * GET: gets the list of updates available
+ * GET/{internal_widget_id} : redirects you to the UDD for the widget
+ * POST: attempts to apply ALL available updates
+ * PUT/{internal_widget_id} : applies available update to specified widget only
  */
 public class UpdatesController extends Controller {
 
@@ -57,6 +57,11 @@ public class UpdatesController extends C
 	
 	static Logger _logger = Logger.getLogger(UpdatesController.class.getName());
 
+	/**
+	 * A GET request with no path arguments will return the list of all updates available for
+	 * all widgets. 
+	 * TODO Note that this call can take a while to complete so it may be better in future to make the call asynchronous, or to schedule update checks and then cache the results
+	 */
 	@Override
 	protected void index(HttpServletRequest request,
 			HttpServletResponse response) throws UnauthorizedAccessException,
@@ -66,6 +71,11 @@ public class UpdatesController extends C
 		returnXml(UpdatesHelper.createXML(updates),response);
 	}
 
+	/**
+	 * A GET request with a resource part requests a redirect to the Update Description Document for
+	 * the widget specified in the resource path, if one is available - otherwise the call will return 
+	 * a 404 status code.
+	 */
 	/* (non-Javadoc)
 	 * @see org.apache.wookie.controller.Controller#show(java.lang.String, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)
 	 */
@@ -73,7 +83,8 @@ public class UpdatesController extends C
 	protected void show(String resourceId, HttpServletRequest request,
 			HttpServletResponse response) throws ResourceNotFoundException,
 			UnauthorizedAccessException, IOException {
-		// attempt to get specific widget by id
+		// attempt to get specific widget by id; note that this is the internal
+		// widget integer ID and not the widget URI
 		IPersistenceManager persistenceManager = PersistenceManagerFactory.getPersistenceManager();
 		IWidget widget = persistenceManager.findById(IWidget.class, resourceId);
 		if (widget == null) throw new ResourceNotFoundException();
@@ -82,16 +93,23 @@ public class UpdatesController extends C
 		response.sendRedirect(widget.getUpdateLocation());
 	}
 
+	/**
+	 * A POST  requests all updates available to be installed.
+	 * TODO Note that this call can take a while to complete so it may be better in future to make the call asynchronous and spawn a background task to complete the update process
+	 */
 	@Override
 	protected boolean create(String resourceId, HttpServletRequest request)
 			throws ResourceDuplicationException, InvalidParametersException,
 			UnauthorizedAccessException {
-		
+			// Check to see if we're requiring updates over HTTPS - if not output a warning
 			boolean onlyUseHttps = Boolean.parseBoolean(request.getParameter("use-https"));
 			if (!onlyUseHttps) _logger.warn("checking for updates using non-secure method");
+			// Get all installed widgets
 			IPersistenceManager persistenceManager = PersistenceManagerFactory.getPersistenceManager();
 			IWidget[] widgets = persistenceManager.findAll(IWidget.class);
+			// Create a W3CWidget factory for the current context
 			W3CWidgetFactory factory  = getFactory(request.getSession().getServletContext());
+			// Iterate over the widgets and attempt to install updates
 			for (IWidget widget: widgets){
 				try {
 					installUpdate(factory, widget, onlyUseHttps);
@@ -102,6 +120,9 @@ public class UpdatesController extends C
 			return true;
 	}
 
+	/**
+	 * A PUT requests a single widget to be updated if there is an update available.
+	 */
 	@Override
 	protected void update(String resourceId, HttpServletRequest request)
 			throws ResourceNotFoundException, InvalidParametersException,
@@ -187,14 +208,16 @@ public class UpdatesController extends C
 	/**
 	 * Get available updates for all installed widgets. Note that this method takes a long
 	 * time to return as it has to poll all the available update sites, so where possible
-	 * cache the returned updates
+	 * we ought to cache the returned updates
 	 * @return a list containing all the updates available.
 	 */
 	public List<UpdateInformation> getAllUpdates(){
 		ArrayList<UpdateInformation> updates = new ArrayList<UpdateInformation>();
+		// Get all installed widgets
 		IPersistenceManager persistenceManager = PersistenceManagerFactory.getPersistenceManager();
 		IWidget[] widgets = persistenceManager.findAll(IWidget.class);
 		for (IWidget widget: widgets){
+			// Check for a valid update document; if there is one, create a new UpdateInformation object and add to list
 			UpdateDescriptionDocument udd = UpdateUtils.checkForUpdate(widget.getUpdateLocation(), widget.getVersion());
 			if (udd != null){
 				UpdateInformation info = new UpdateInformation();

Modified: incubator/wookie/trunk/src/org/apache/wookie/updates/UpdatesHelper.java
URL: http://svn.apache.org/viewvc/incubator/wookie/trunk/src/org/apache/wookie/updates/UpdatesHelper.java?rev=1099215&r1=1099214&r2=1099215&view=diff
==============================================================================
--- incubator/wookie/trunk/src/org/apache/wookie/updates/UpdatesHelper.java (original)
+++ incubator/wookie/trunk/src/org/apache/wookie/updates/UpdatesHelper.java Tue May  3 19:54:31 2011
@@ -25,11 +25,19 @@ import org.jdom.output.XMLOutputter;
  */
 public class UpdatesHelper {
 
+	/**
+	 * Creates an XML serialization of a List of updates, including information about
+	 * the widget as well as the update description document associated with it
+	 * @param updates a List of UpdateInformation objects to render
+	 * @return a String containing the XML serialization of the updates
+	 */
 	public static String createXML(
 			List<UpdateInformation> updates) {
 		Document document = new Document();
+		// The returned XML uses the Widgets namespace
 		Element root = new Element("updates",IW3CXMLConfiguration.MANIFEST_NAMESPACE);
 		for (UpdateInformation info: updates){
+			// We use the toXml method on the UpdateInformation class to serialize each
 			root.addContent(info.toXml());
 		}
 		document.setRootElement(root);