Added JavaDocs

java/com.sap.sse.security.ui/src/main/java/com/sap/sse/security/ui/authentication/decorator/AuthorizedContentDecorator.java

@@ -14,8 +14,13 @@ import com.sap.sse.security.ui.authentication.app.AuthenticationContext;
 import com.sap.sse.security.ui.authentication.app.NeedsAuthenticationContext;
 import com.sap.sse.security.ui.client.i18n.StringMessages;
 
+/**
+ * Decorator widget that either shows its child widget or depending on the authentication state a
+ * {@link NotLoggedInView}.
+ *
+ */
 public class AuthorizedContentDecorator extends Composite implements RequiresResize, NeedsAuthenticationContext {
-    
+
     private final SimplePanel contentHolder = new SimplePanel();
     private Widget content;
     private WidgetFactory contentWidgetFactory;
@@ -25,87 +30,124 @@ public class AuthorizedContentDecorator extends Composite implements RequiresRes
 
     public AuthorizedContentDecorator(NotLoggedInPresenter presenter, NotLoggedInView notLoggedInView) {
         this.notLoggedInView = notLoggedInView;
-        
+
         notLoggedInView.setPresenter(presenter);
         notLoggedInView.setSignInText(StringMessages.INSTANCE.signIn());
-        
+
         initWidget(contentHolder);
     }
-    
+
+    /**
+     * @param content the child widget to show if the user is authenticated and has the required permission
+     */
     @UiChild(limit = 1)
     public void addContent(Widget content) {
         this.content = content;
     }
-    
+
+    /**
+     * An alternative to setting the child widget to show for permitted users is to set a factory that creates the
+     * widget when needed the first time. This is useful if creating the UI required the user to be authenticated to
+     * make remote calls to succeed that would cause an error for non permitted users.
+     * 
+     * @param contentWidgetFactory
+     *            a factory that creates the child widget on demand when the user is authenticated and permitted the
+     *            first time
+     */
     public void setContentWidgetFactory(WidgetFactory contentWidgetFactory) {
         this.contentWidgetFactory = contentWidgetFactory;
     }
-    
+
     private Widget getContentWidget() {
-        if(contentWidgetFactory != null) {
+        if (contentWidgetFactory != null) {
             content = contentWidgetFactory.get();
             contentWidgetFactory = null;
         }
         return content;
     }
-    
+
     @Override
     protected void onLoad() {
         super.onLoad();
-        
-        if(getParent() instanceof ProvidesResize || getParent() instanceof HeaderPanel) {
+
+        if (getParent() instanceof ProvidesResize || getParent() instanceof HeaderPanel) {
             contentHolder.setSize("100%", "100%");
         }
     }
-    
+
     @Override
     public void onResize() {
         Widget currentContentWidget = contentHolder.getWidget();
-        if(currentContentWidget instanceof RequiresResize) {
+        if (currentContentWidget instanceof RequiresResize) {
             ((RequiresResize) currentContentWidget).onResize();
         }
     }
-    
+
+    /**
+     * You need to set the {@link AuthenticationContext} whenever the authentication changes to make the decorator react
+     * by showing the correct content.
+     */
     @Override
     public void setAuthenticationContext(AuthenticationContext authenticationContext) {
         boolean isAuthenticated = authenticationContext.isLoggedIn();
         boolean isPermitted = isPermitted(authenticationContext);
         boolean maySeeRealContent = isAuthenticated && isPermitted;
-        
+
         IsWidget isWidget = maySeeRealContent ? getContentWidget() : notLoggedInView;
-        
-        if(!maySeeRealContent) {
+
+        if (!maySeeRealContent) {
             String message = !isAuthenticated ? StringMessages.INSTANCE.youAreNotSignedIn() : StringMessages.INSTANCE
                     .youDontHaveRequiredPermission();
             notLoggedInView.setMessage(message);
         }
 
         Widget widget = isWidget.asWidget();
-        if(widget instanceof RequiresResize) {
+        if (widget instanceof RequiresResize) {
             widget.setSize("100%", "100%");
         }
         contentHolder.setWidget(widget);
-        if(widget instanceof RequiresResize) {
+        if (widget instanceof RequiresResize) {
             ((RequiresResize) widget).onResize();
         }
     }
 
     private boolean isPermitted(AuthenticationContext userManagementContext) {
-        return permissionToCheck == null || userManagementContext.getCurrentUser().hasPermission(permissionToCheck, permissionsForRoleProvider);
+        return permissionToCheck == null
+                || userManagementContext.getCurrentUser().hasPermission(permissionToCheck, permissionsForRoleProvider);
     }
-    
+
+    /**
+     * @param permissionsForRoleProvider the PermissionsForRoleProvider used when checking the required permission of a user.
+     */
     public void setPermissionsForRoleProvider(PermissionsForRoleProvider permissionsForRoleProvider) {
         this.permissionsForRoleProvider = permissionsForRoleProvider;
     }
-    
+
+    /**
+     * Setting a permission causes that the user not only needs to be logged in but also needs to have the given permission.
+     * 
+     * @param permissionToCheck the permission to check
+     */
     public void setPermissionToCheck(String permissionToCheck) {
         this.permissionToCheck = permissionToCheck;
     }
-    
+
+    /**
+     * Setting a permission causes that the user not only needs to be logged in but also needs to have the given permission.
+     * 
+     * @param permissionToCheck the permission to check
+     */
     public void setPermissionToCheck(Permission permissionToCheck) {
         setPermissionToCheck(permissionToCheck.getStringPermission());
     }
+
     
+    /**
+     * Setting a permission causes that the user not only needs to be logged in but also needs to have the given permission.
+     * 
+     * @param permissionToCheck the permission to check
+     * @param permissionsForRoleProvider the PermissionsForRoleProvider used when checking the required permission of a user.
+     */
     public void setPermissionToCheck(Permission permissionToCheck, PermissionsForRoleProvider permissionsForRoleProvider) {
         setPermissionToCheck(permissionToCheck);
         setPermissionsForRoleProvider(permissionsForRoleProvider);

java/com.sap.sse.security.ui/src/main/java/com/sap/sse/security/ui/authentication/decorator/FlyoutBasedAuthorizedContentDecorator.java

@@ -2,6 +2,11 @@ package com.sap.sse.security.ui.authentication.decorator;
 
 import com.google.web.bindery.event.shared.EventBus;
 
+/**
+ * {@link AuthorizedContentDecorator} that uses {@link FlyoutNotLoggedInPresenter} internally to handle the sign in
+ * case.
+ *
+ */
 public class FlyoutBasedAuthorizedContentDecorator extends AuthorizedContentDecorator {
 
     public FlyoutBasedAuthorizedContentDecorator(EventBus eventBus, NotLoggedInView notLoggedInView) {

java/com.sap.sse.security.ui/src/main/java/com/sap/sse/security/ui/authentication/decorator/FlyoutNotLoggedInPresenter.java

@@ -1,10 +1,18 @@
 package com.sap.sse.security.ui.authentication.decorator;
 
+import org.apache.tools.ant.taskdefs.Javac.ImplementationSpecificArgument;
+
 import com.google.web.bindery.event.shared.EventBus;
 import com.sap.sse.security.ui.authentication.AuthenticationRequestEvent;
 
+/**
+ * {@link NotLoggedInPresenter} {@link ImplementationSpecificArgument} that fires an {@link AuthenticationRequestEvent}
+ * which is used by authentication UI implementations using a flyout to host the authentication UI. This event triggers
+ * the flyout to be shown.
+ *
+ */
 public class FlyoutNotLoggedInPresenter implements NotLoggedInPresenter {
-    
+
     private final EventBus eventBus;
 
     public FlyoutNotLoggedInPresenter(EventBus eventBus) {

java/com.sap.sse.security.ui/src/main/java/com/sap/sse/security/ui/authentication/decorator/NotLoggedInPresenter.java

@@ -1,5 +1,12 @@
 package com.sap.sse.security.ui.authentication.decorator;
 
+/**
+ * Used by {@link AuthorizedContentDecorator} to trigger login when the button is pressed on the {@link NotLoggedInView}.
+ *
+ */
 public interface NotLoggedInPresenter {
+    /**
+     * When called this must show the login form to the user.
+     */
     void doTriggerLoginForm();
 }

java/com.sap.sse.security.ui/src/main/java/com/sap/sse/security/ui/authentication/decorator/NotLoggedInView.java

@@ -2,11 +2,25 @@ package com.sap.sse.security.ui.authentication.decorator;
 
 import com.google.gwt.user.client.ui.IsWidget;
 
+/**
+ * A view that is shown by {@link AuthorizedContentDecorator} if the user isn't logged in or doen't have the required
+ * permissions.
+ * The view must show a message and a button that leads the user to the login form when being clicked.
+ */
 public interface NotLoggedInView extends IsWidget {
 
+    /**
+     * @param presenter the presenter to call when the "sign in" button is clicked
+     */
     void setPresenter(NotLoggedInPresenter presenter);
 
+    /**
+     * @param message the message to show to the user
+     */
     void setMessage(String message);
 
+    /**
+     * @param signInText the text to set on the "sign in" button
+     */
     void setSignInText(String signInText);
 }

java/com.sap.sse.security.ui/src/main/java/com/sap/sse/security/ui/authentication/decorator/WidgetFactory.java

@@ -2,8 +2,15 @@ package com.sap.sse.security.ui.authentication.decorator;
 
 import com.google.gwt.user.client.ui.Widget;
 
+/**
+ * Factory used to create a widget deferred.
+ *
+ */
 public interface WidgetFactory {
-    
+
+    /**
+     * @return the created widget instance
+     */
     Widget get();
 
 }