Menu
▾
▴
[Treebase-guts] SF.net SVN: treebase:[806] trunk/treebase-web/src/main/java/org/cipres/ treebase/web/controllers
|
From: <rv...@us...> - 2011-04-26 00:28:57
|
Revision: 806
http://treebase.svn.sourceforge.net/treebase/?rev=806&view=rev
Author: rvos
Date: 2011-04-26 00:28:51 +0000 (Tue, 26 Apr 2011)
Log Message:
-----------
Added documentation.
Modified Paths:
--------------
trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSController.java
trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSMatrixController.java
trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSStudyController.java
trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSTaxonController.java
trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSTreeController.java
Modified: trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSController.java
===================================================================
--- trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSController.java 2011-04-25 22:45:37 UTC (rev 805)
+++ trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSController.java 2011-04-26 00:28:51 UTC (rev 806)
@@ -16,19 +16,59 @@
import org.cipres.treebase.TreebaseIDString.MalformedTreebaseIDString;
import org.cipres.treebase.web.Constants;
+/**
+ * This class re-directs clients to one of a number of other controllers depending
+ * on the provided URL pattern. Here are the patterns. Where it says 'study' in the
+ * example patterns, it can equally say 'matrix', 'tree' or 'taxon'. The part that
+ * says 'TB2:S1787' is supposed to be a valid NamespacedGUID:
+ * <ul>
+ * <li>
+ * - /phylows/study/TB2:S1787 - this is the general pattern for stable resource
+ * URLs, without a query string. URLs of this kind are sent on to the AnyObjectAsRDFController.
+ * If you want to work on content-negotiation, go there. The re-direct URL is generated by
+ * the method createResourceUrl
+ * </li>
+ *
+ * <li>
+ * - /phylows/study/TB2:S1787?format=html - this is the pattern for the web page
+ * version of a resource. URLs of this kind are sent on to the SearchSummaryController, except
+ * for trees, which are sent to the SearchMapToPhyloWidgetController. The re-direct URL is
+ * generated by the method createDisplayUrl
+ * </li>
+ *
+ * <li>
+ * - /phylows/study/TB2:S1787?format=nexml - this is the pattern for any other available
+ * serialization of the resource (i.e. nexml|nexus|rdf). URLs of this kind are sent to the
+ * downloadA*Controller controller (e.g. Matrix|Study|Tree). If an output format isn't
+ * working as it should, look in the download controllers (and the core services that ultimately
+ * produce the output). The re-direct URL is generated by the method createDownloadUrl
+ * </li>
+ *
+ * <li>
+ * - /phylows/study/find?query=... - this is the pattern for search queries. URLs of this
+ * kind are sent to the *SearchController controllers (e.g. Matrix|Study|Tree). To debug
+ * CQL queries, look in those controllers, as the class you are looking at now doesn't
+ * process CQL at all. The re-direct URL is generated by the method createSearchUrl
+ * </li>
+ * </ul>
+ * @author rvosa
+ *
+ */
+
public abstract class PhyloWSController implements Controller {
private static final long serialVersionUID = 1L;
private static String searchBase = "/treebase-web/search/";
/**
- *
+ * Child classes return the display page for the focal type
+ * of objects, e.g. for matrices, this returns "matrix.html"
* @return
*/
abstract String getDisplayPage();
/**
* Given an object ID and a servlet request object, constructs
- * a relative URL to an HTML page about that object.
+ * a relative URL to an HTML display page about that object.
* @param objectId is the primary key for the requested object
* @param request is the servlet request, which we need to check for reviewer access
* @return a relative URL to an HTML page
@@ -42,7 +82,8 @@
}
/**
- *
+ * Here the actual request is handled. See the class introduction at
+ * the top of this file for an overview of the logic implemented here.
*/
public ModelAndView handleRequest(HttpServletRequest req, HttpServletResponse res) throws IOException {
String url = null;
@@ -91,7 +132,9 @@
}
/**
- *
+ * Given a NamespacedGUID, which is a wrapper around an ID such as TB2:S1787, and
+ * a request object, returns a URL for the resource description of the object identified
+ * by the NamespacedGUID.
* @param guid
* @param req
* @return
@@ -114,13 +157,17 @@
}
/**
- *
+ * Child classes here return the search page; e.g. for matrices, returns "matrixSearch.html"
* @return
*/
abstract String getSearchPage();
/**
- *
+ * Constructs the URL that re-directs to the *SearchController classes. This involves:
+ * the getSearchPage() output (which identifies the seach controller), the CQL query,
+ * the output format (either rss1, or a web page in all other cases) and the recordSchema,
+ * which is used to project a search result set (e.g. a set of studies) into another class
+ * (e.g. the set of trees for those studies).
* @param request
* @return
*/
@@ -144,15 +191,21 @@
}
/**
- * Given an array of path fragments, returns whether an HTML web page
- * exists for the type of object the fragments map onto
+ * Given an ID prefix (as per those of TreebaseIDString), returns whether an HTML web page
+ * exists for the type of object the prefix identifies
* @param pathComponents
* @return true of web page exists, false otherwise
*/
abstract boolean hasWebPage(String prefix);
/**
- *
+ * Child classes return a map of query string parameters and their values. Typically these
+ * are the study id (parameter name "id") and the id of an object in that study, e.g.
+ * a "matrixid" or a "treeid". In the latter cases where we look for objects in a study
+ * (not the study per se) we first need to look up those objects, and then fetch the study
+ * for them. Hence we need to interact with service objects, which potentially might not
+ * be able to find the object identified by objectId, hence we may throw an ObjectNotFoundException
+ * here.
* @param objectId
* @return
* @throws ObjectNotFoundException
@@ -160,7 +213,9 @@
abstract Map<String,String> getObjectQueryParameters(Long objectId) throws ObjectNotFoundException;
/**
- *
+ * Creates a URL by concatenating the base + ? + the params as query string parameters, i.e.
+ * key1=value1&key2=value2 + potentially the x-access-code parameter, when dealing with
+ * embargoed objects
* @param base
* @param params
* @return
@@ -183,13 +238,17 @@
/**
- *
+ * Child classes return the focal download page here, e.g. for matrices, returns
+ * "downloadAMatrix.html"
* @return
*/
abstract String getDownloadPage();
/**
- *
+ * Creates the URL that re-directs to the DownloadA*Controllers. This involves concatenating
+ * getDownloadPage() with the query string parameters to identify the object to download, the
+ * format in which to serialize it (and potentially the x-access-code parameter, for
+ * embargoed objects).
* @param objectId
* @param format
* @return
@@ -204,7 +263,8 @@
}
/**
- *
+ * Exceptions of this kind are thrown when a non-existent objectId somehow ends up
+ * in a URL.
* @author rvosa
*
*/
Modified: trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSMatrixController.java
===================================================================
--- trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSMatrixController.java 2011-04-25 22:45:37 UTC (rev 805)
+++ trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSMatrixController.java 2011-04-26 00:28:51 UTC (rev 806)
@@ -11,16 +11,28 @@
private MatrixService mMatrixService;
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getSearchPage()
+ */
@Override
String getSearchPage() {
return "matrixSearch.html";
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getDownloadPage()
+ */
@Override
String getDownloadPage() {
return "downloadAMatrix.html";
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getObjectQueryParameters(java.lang.Long)
+ */
@Override
Map<String,String> getObjectQueryParameters(Long objectId) throws ObjectNotFoundException {
Matrix matrix = getMatrixService().findByID(objectId);
@@ -37,11 +49,19 @@
return params;
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getDisplayPage()
+ */
@Override
String getDisplayPage() {
return "matrix.html";
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#hasWebPage(java.lang.String)
+ */
@Override
boolean hasWebPage(String prefix) {
return "M".equals(prefix);
Modified: trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSStudyController.java
===================================================================
--- trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSStudyController.java 2011-04-25 22:45:37 UTC (rev 805)
+++ trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSStudyController.java 2011-04-26 00:28:51 UTC (rev 806)
@@ -10,16 +10,28 @@
private StudyService mStudyService;
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getSearchPage()
+ */
@Override
String getSearchPage() {
return "studySearch.html";
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getDownloadPage()
+ */
@Override
String getDownloadPage() {
return "downloadAStudy.html";
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getObjectQueryParameters(java.lang.Long)
+ */
@Override
Map<String,String> getObjectQueryParameters(Long objectId) throws ObjectNotFoundException {
Study study = getStudyService().findByID(objectId);
@@ -31,11 +43,19 @@
return params;
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getDisplayPage()
+ */
@Override
String getDisplayPage() {
return "summary.html";
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#hasWebPage(java.lang.String)
+ */
@Override
boolean hasWebPage(String prefix) {
return "S".equals(prefix);
Modified: trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSTaxonController.java
===================================================================
--- trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSTaxonController.java 2011-04-25 22:45:37 UTC (rev 805)
+++ trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSTaxonController.java 2011-04-26 00:28:51 UTC (rev 806)
@@ -5,28 +5,48 @@
public class PhyloWSTaxonController extends PhyloWSController {
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getSearchPage()
+ */
@Override
String getSearchPage() {
return "taxonSearch.html";
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getDownloadPage()
+ */
@Override
String getDownloadPage() {
return "downloadATaxon.html";
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getObjectQueryParameters(java.lang.Long)
+ */
@Override
Map<String,String> getObjectQueryParameters(Long objectId) throws ObjectNotFoundException {
// TODO Auto-generated method stub
return new HashMap<String,String>();
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getDisplayPage()
+ */
@Override
String getDisplayPage() {
// TODO Auto-generated method stub
return "taxon.html";
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#hasWebPage(java.lang.String)
+ */
@Override
boolean hasWebPage(String prefix) {
return false;
Modified: trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSTreeController.java
===================================================================
--- trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSTreeController.java 2011-04-25 22:45:37 UTC (rev 805)
+++ trunk/treebase-web/src/main/java/org/cipres/treebase/web/controllers/PhyloWSTreeController.java 2011-04-26 00:28:51 UTC (rev 806)
@@ -11,16 +11,28 @@
private PhyloTreeService mPhyloTreeService;
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getSearchPage()
+ */
@Override
String getSearchPage() {
return "treeSearch.html";
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getDownloadPage()
+ */
@Override
String getDownloadPage() {
return "downloadATree.html";
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getObjectQueryParameters(java.lang.Long)
+ */
@Override
Map<String,String> getObjectQueryParameters(Long objectId) throws ObjectNotFoundException {
PhyloTree phyloTree = getPhyloTreeService().findByID(objectId);
@@ -37,11 +49,19 @@
return params;
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#getDisplayPage()
+ */
@Override
String getDisplayPage() {
return "tree.html";
}
+ /*
+ * (non-Javadoc)
+ * @see org.cipres.treebase.web.controllers.PhyloWSController#hasWebPage(java.lang.String)
+ */
@Override
boolean hasWebPage(String prefix) {
return "Tr".equals(prefix);
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
