GTNPORTAL-2975 Update java documentation comments for webui skeleton …

…classes

component/web/controller/src/main/java/org/exoplatform/web/WebAppController.java

@@ -92,9 +92,11 @@ public class WebAppController {
     private final AtomicReference<String> configurationPathRef;
 
     /**
-     * The WebAppControler along with the PortalRequestHandler defined in the init() method of the PortalController servlet
-     * (controller.register(new PortalRequestHandler())) also add the CommandHandler object that will listen for the incoming
-     * /command path in the URL.
+     * Must have 'controller.config' as init parameter configuration (in xml)
+     * that point to the controller.xml used to initialize navigation controller
+     *
+     * This service component is a container for applications: PortalApplication, PortletApplication, StandaloneApplication....
+     * It use the navigation controller to route the request to corresponding handlers (config as service plugin)
      *
      * @param params the init params
      * @throws Exception any exception
@@ -256,6 +258,12 @@ public void unregister(String[] paths) {
             handlers.remove(path);
     }
 
+    /**
+     * Delegate init action to handler, for example: PortalRequestHandler have
+     * a change to create and register PortalApplication with WebAppController
+     * @param config
+     * @throws Exception
+     */
     public void onHandlersInit(ServletConfig config) throws Exception {
         Collection<WebRequestHandler> hls = handlers.values();
         for (WebRequestHandler handler : hls) {

webui/framework/src/main/java/org/exoplatform/webui/core/UIApplication.java

@@ -30,7 +30,8 @@
 import org.exoplatform.webui.exception.MessageException;
 
 /**
- * Created by The eXo Platform SAS May 8, 2006
+ * This is abstract class for Root WebUI component of applications in GateIn. <br/>
+ * Act as container of WebUI components, it also provide method to show a Popup message
  */
 @Serialized
 public abstract class UIApplication extends UIContainer {
@@ -113,6 +114,10 @@ public void renderChildren() throws Exception {
         getUIPopupMessages().processRender(context);
     }
 
+    /**
+     * Wrap the action processing by a try catch, if there is exceptions, show a popup message
+     * if no exception the processAction will be delegate to the target of the action request
+     */
     public void processAction(WebuiRequestContext context) throws Exception {
         try {
             super.processAction(context);
@@ -125,6 +130,10 @@ public void processAction(WebuiRequestContext context) throws Exception {
         }
     }
 
+    /**
+     * Triggered when there is Ajax request. <br/>
+     * This method add xml structure that help PortalHttpRequest.js parse the response
+     */
     public void renderBlockToUpdate(UIComponent uicomponent, WebuiRequestContext context, Writer w) throws Exception {
         w.write("<div class=\"BlockToUpdate\">");
         w.append("<div class=\"BlockToUpdateId\">").append(uicomponent.getId()).append("</div>");

webui/portal/src/main/java/org/exoplatform/portal/application/PortalController.java

@@ -53,9 +53,9 @@ public class PortalController extends AbstractHttpServlet {
     /**
      * The onInit() method is used to prepare the portal to receive requests.
      *
-     * 1) Get the WebAppController component from the container 2) Create a new PortalApplication, init it with the
-     * ServletConfig object (which contains init params) 3) Register that PortalApplication inside WebAppController 4) Create a
-     * new PortalRequestHandler object and register it in the WebAppController
+     * 1) Get the WebAppController component from the container and delegate the init task to this component
+     * 2) WebAppController will then delegate to coressponsding handlers depends on the URL. For example:
+     * PortalRequestHandler is in charged of creating and registering PortalApplication and handle the requests for portal
      */
     private void onInit(ServletConfig sConfig, PortalContainer portalContainer) {
         // Keep the old ClassLoader
@@ -82,6 +82,8 @@ private void onInit(ServletConfig sConfig, PortalContainer portalContainer) {
     }
 
     /**
+     * Register onInit callback to PortalContainerPostCreateTask and register the servlet context with RootContainer.
+     * So that portal.war don't need PortalContainerConfigOwner listener. (extension project will need this listener)
      * @see org.exoplatform.container.web.AbstractHttpServlet#afterInit(javax.servlet.ServletConfig)
      */
     public void afterInit(final ServletConfig config) throws ServletException {

webui/portal/src/main/java/org/exoplatform/portal/application/PortalRequestHandler.java

@@ -50,8 +50,9 @@
 /**
  * Created by The eXo Platform SAS Dec 9, 2006
  *
- * This class handle the request that target the portal paths /public and /private
- *
+ * This is 'portal' handler, it handle the request of URLs that are routed by navigation controller (using urls parameter).
+ * This handler is registered to WebAppController by xml configuration.
+ * @see WebAppController
  */
 public class PortalRequestHandler extends WebRequestHandler {
 
@@ -84,6 +85,14 @@ public String getHandlerName() {
         return "portal";
     }
 
+    /**
+     * Dispatched from WebAppController, after the portal servlet init function called, this method create and register
+     * PortalApplication to WebAppController
+     *
+     * PortalApplication creation can be customized by registering PortalApplicationFactory implementation using ServiceLoader
+     *
+     * @see PortalApplication
+     */
     @Override
     public void onInit(WebAppController controller, ServletConfig sConfig) throws Exception {
         PortalApplication application;
@@ -101,16 +110,16 @@ public void onInit(WebAppController controller, ServletConfig sConfig) throws Ex
      *
      * Here are the steps done in the method:
      *
-     * 1) set the header Cache-Control to no-cache 2) Get the PortalApplication reference from the controller 3) Create a
-     * PortalRequestContext object that is a convenient wrapper on all the request information 4) Set that context in a
-     * ThreadLocal to easily access it 5) Get the collection of ApplicationLifecycle referenced in the PortalApplication and
-     * defined in the webui-configuration.xml of the portal application 6) Call onStartRequest() on each ApplicationLifecycle
-     * object 7) Get the StateManager object from the PortalApplication (also referenced in the XML file) 8) Use the
-     * StateManager to get a reference on the root UI component: UIApplication; the method used is
-     * restoreUIRootComponent(context) 9) If the UI component is not the current one in used in the PortalContextRequest, then
-     * replace it 10) Process decode on the PortalApplication 11) Process Action on the PortalApplication 12) Process Render on
-     * the UIApplication UI component 11) call onEndRequest on all the ApplicationLifecycle 12) Release the context from the
-     * thread
+     * 1) set the header Cache-Control to no-cache <br/>
+     * 2) Get the PortalApplication reference from the controller <br/>
+     * 3) Create a PortalRequestContext object that is a convenient wrapper on all the request information <br/>
+     * 4) Get the collection of ApplicationLifecycle referenced in the PortalApplication and defined in
+     * the webui-configuration.xml of the portal application <br/>
+     * 5) Set that context in a ThreadLocal to easily access it <br/>
+     * 6) Check if user have permission to access portal, if not, send 403 status code,
+     * if user has not login, redirect to login page <br/>
+     * 6) dispatch to processRequest method, this is protected method, we can extend and override this method to
+     * write a new requestHandler base on PortalRequestHandler (@see {@link StandaloneAppRequestHandler})
      *
      */
     @SuppressWarnings("unchecked")
@@ -160,6 +169,24 @@ public boolean execute(ControllerContext controllerContext) throws Exception {
         return true;
     }
 
+    /**
+     * This method do the main job on processing a portal request:
+     *
+     * 1) Call onStartRequest() on each ApplicationLifecycle object <br/>
+     * 2) Get the StateManager object from the PortalApplication (also referenced in the XML file) <br/>
+     * 3) Use the StateManager to get a reference on the root UI component: UIApplication;
+     * the method used is restoreUIRootComponent(context) <br/>
+     * 4) If the UI component is not the current one in used in the PortalContextRequest, then replace it <br/>
+     * 5) Process decode on the PortalApplication <br/>
+     * 6) Process Action on the PortalApplication <br/>
+     * 7) Process Render on the UIApplication UI component <br/>
+     * 8) call onEndRequest on all the ApplicationLifecycle <br/>
+     * 9) Release the context from the thread
+     *
+     * @param context
+     * @param app
+     * @throws Exception
+     */
     @SuppressWarnings("unchecked")
     protected void processRequest(PortalRequestContext context, PortalApplication app) throws Exception {
         WebuiRequestContext.setCurrentInstance(context);

webui/portal/src/main/java/org/exoplatform/portal/webui/application/UIPortlet.java

@@ -108,7 +108,22 @@
 import java.util.Set;
 import java.util.UUID;
 
-/** May 19, 2006 */
+/**
+ * This UI component represent a portlet window on a page. <br/>
+ * Each user request to a portlet will be passed through this class then delegate call to the portlet container<br/>
+ * UIPortletLifecycle do the main request router: delegate the job to portlet action listeners according to the url parameters<br/>
+ *
+ * ProcessAction, ServeResource, Render action listeners will receive event if request url contain parameter
+ * point to them, those event will delegate call to portlet container to call JSR 286 portlet lifecycle method<br/>
+ *
+ * ProcessEvents, ChangePortletMode, ChangeWindowState listener will receive event after the portlet action invocation response.
+ * (dispatched during the process of ProcessActionListener)<br/>
+ *
+ * DeleteComponent, EditPortlet action listener is portal specific listener, come from the UI of portal
+ *
+ * @see UIPortletLifecycle
+ * @see UIPortletActionListener
+ */
 @ComponentConfig(lifecycle = UIPortletLifecycle.class, template = "system:/groovy/portal/webui/application/UIPortlet.gtmpl", events = {
         @EventConfig(listeners = RenderActionListener.class), @EventConfig(listeners = ChangePortletModeActionListener.class),
         @EventConfig(listeners = ChangeWindowStateActionListener.class),
@@ -229,6 +244,11 @@ public String getApplicationId() {
         return applicationId;
     }
 
+    /**
+     * portletStyle is 'Window' when it's in WebOS project - an GateIn extension,
+     * portletStyle is null if is not in WebOS
+     * @return a string represent current portlet style
+     */
     public String getPortletStyle() {
         return portletStyle;
     }
@@ -237,33 +257,67 @@ public void setPortletStyle(String s) {
         portletStyle = s;
     }
 
+    /**
+     * @return true if portlet is configured to show control icon that allow to change portlet mode
+     */
     public boolean getShowPortletMode() {
         return showPortletMode;
     }
 
+    /**
+     * Used by portal to show the icon that allow to change portlet mode
+     * @param b if show icon
+     */
     public void setShowPortletMode(Boolean b) {
         showPortletMode = b;
     }
 
+    /**
+     *  Used internally by portal to change current state
+     *  if portlet is in portal or in page
+     */
     public void setPortletInPortal(boolean b) {
         portletInPortal_ = b;
     }
 
+    /**
+     * Check if portlet is in portal
+     * @return true if portlet is in portal
+     */
     public boolean isPortletInPortal() {
         return portletInPortal_;
     }
 
+    /**
+     * Theme is composed of map between theme name and skin name.
+     * Theme format: {skinName}:{themeName}::{anotherSkin}:{anotherTheme}.
+     * For example: the default them is 'Default:DefaultTheme::Vista:VistaTheme::Mac:MacTheme'.
+     * Default theme means if portal skin is 'Default', this portlet's theme is 'DefaultTheme. If portal change skin to 'Vista',
+     * portlet theme will be change to 'VistaTheme'.
+     * @return current theme setting
+     */
     public String getTheme() {
         if (theme_ == null || theme_.trim().length() < 1) {
             return DEFAULT_THEME;
         }
         return theme_;
     }
 
+    /**
+     * Used internally by Portal to change current portlet theme.
+     * Theme format: {skinName}:{themeName}::{anotherSkin}:{anotherTheme}.
+     * For example: 'Default:DefaultTheme::Vista:VistaTheme::Mac:MacTheme'
+     */
     public void setTheme(String theme) {
         theme_ = theme;
     }
 
+    /**
+     * Get theme name according to portal skin.
+     * If there is no coressponding theme. return 'DefaultTheme'
+     * @param skin - portal skin
+     * @return theme name
+     */
     public String getSuitedTheme(String skin) {
         if (skin == null) {
             skin = Util.getUIPortalApplication().getSkin();
@@ -275,6 +329,11 @@ public String getSuitedTheme(String skin) {
         return DEFAULT_THEME.split(":")[1];
     }
 
+    /**
+     * Add map between portlet theme and portal skin
+     * @param skin - portal skin name
+     * @param theme - portlet theme name
+     */
     public void putSuitedTheme(String skin, String theme) {
         if (skin == null) {
             skin = Util.getUIPortalApplication().getSkin();
@@ -339,6 +398,13 @@ public void setSupportedPublicRenderParameters(Map<QName, String> supportedPubli
         supportedPublicParams_ = supportedPublicRenderParameters;
     }
 
+    /**
+     * Get localized displayName metadata configured in portlet.xml.<br/>
+     * If can't find localized displayName, return portlet name.<br/>
+     * If portlet doesn't exists anymore, return empty string.<br/>
+     * This value is cached in session, that means it only query to portlet container one time
+     * @return display name
+     */
     public String getDisplayName() {
         if (displayName == null) {
             org.gatein.pc.api.Portlet portlet = getProducedOfferedPortlet();
@@ -875,10 +941,21 @@ public void update(C updateState) throws Exception {
         setState(state);
     }
 
+    /**
+     * Return modifed portlet stated (after portlet action invovation)
+     * @param modifiedContext
+     * @throws Exception
+     */
     public C getModifiedState(PortletContext modifiedContext) throws Exception {
         return adapter.getStateFromModifiedContext(this.getPortletContext(), modifiedContext);
     }
 
+    /**
+     * Return cloned portlet state (updated after portlet action invocation).
+     * This method is used in case WSRP
+     * @param clonedContext
+     * @throws Exception
+     */
     public C getClonedState(PortletContext clonedContext) throws Exception {
         return adapter.getstateFromClonedContext(this.getPortletContext(), clonedContext);
     }
@@ -907,10 +984,20 @@ public PortletInvocationResponse invoke(PortletInvocation invocation) throws Por
         }
     }
 
+    /**
+     * navigationalState - internal portlet container parameter (go with portlet url).
+     * called when navigation state updated
+     * @param navigationalState
+     */
     void setNavigationalState(StateString navigationalState) {
         this.navigationalState = navigationalState;
     }
 
+    /**
+     * configuredTitle - the localized title configured in portlet.xml.
+     * This value returned ans set after portlet container invocation.
+     * @param _configuredTitle - portlet title responsed from portlet container
+     */
     protected void setConfiguredTitle(String _configuredTitle) {
         this.configuredTitle = _configuredTitle;
     }
@@ -940,6 +1027,20 @@ public String getDisplayTitle() {
         return getDisplayName();
     }
 
+    /**
+     * Parsing response from portlet container. The response contains:<br/>
+     * html markup, portlet title, response properties:<br/>
+     * - JS resource dependency (defined in gatein-resources.xml)<br/>
+     * - html header<br/>
+     * - cookie<br/>
+     * - extra markup header<br/>
+     * If errors occur during portlet lifecycle processing. PortletExceptionHandleService is called.
+     * Add plugins to this service to customize portlet error handler
+     * @param pir - response object from portlet container
+     * @param context - request context
+     * @return markup to render on browser
+     * @see PortletExceptionHandleService
+     */
     public Text generateRenderMarkup(PortletInvocationResponse pir, WebuiRequestContext context) {
         PortalRequestContext prcontext = (PortalRequestContext) context;
 

webui/portal/src/main/java/org/exoplatform/portal/webui/application/UIPortletActionListener.java

@@ -686,6 +686,10 @@ public static void setupPublicRenderParams(UIPortlet uiPortlet, Map<String, Stri
 
     }
 
+    /**
+     * This listener is called when the portlet portlet window state has to be changed.
+     * It can be changed by building specific URL, or by programatically in the portlet, then triggered after action or event response
+     */
     public static class ChangeWindowStateActionListener extends EventListener<UIPortlet> {
         public void execute(Event<UIPortlet> event) throws Exception {
             UIPortlet uiPortlet = event.getSource();