updated API description

db/src/main/java/de/muehlencord/shared/db/CommonAbstractController.java

@@ -105,7 +105,7 @@ public abstract class CommonAbstractController {
      * updated. Otherwise these fields are skipped.
      * @param changedBy the username to apply
      * @return an updated audit object to use for the updated entity.
-     * @throws ControllerException
+     * @throws ControllerException if the audit object cannot be updated
      */
     public Audit applyAuditChanges(Audit audit, boolean onCreate, String changedBy) throws ControllerException {
         if (audit == null) {

db/src/main/java/de/muehlencord/shared/db/ControllerException.java

@@ -18,6 +18,7 @@ package de.muehlencord.shared.db;
 import javax.ejb.ApplicationException;
 
 /**
+ * Generic exception if an exception inside a Controller class occurs
  *
  * @author Joern Muehlencord (joern@muehlencord.de)
  */
@@ -39,7 +40,8 @@ public class ControllerException extends Exception {
      * message.
      *
      * @param cause the reason code
-     * @param message an explanation
+     * @param message the detail message. The detail message is saved for later
+     * retrieval by the {@link #getMessage()} method.
      */
     public ControllerException(int cause, String message) {
         super(message);
@@ -48,15 +50,23 @@ public class ControllerException extends Exception {
 
     /**
      *
-     * @param causeCode
+     * @param causeCode the reason code
-     * @param message
+     * @param message the detail message. The detail message is saved for later
-     * @param cause
+     * retrieval by the {@link #getMessage()} method.
+     *
+     * @param cause the cause (which is saved for later retrieval by the
+     * {@link #getCause()} method). (A {@code null} value is permitted, and
+     * indicates that the cause is nonexistent or unknown.)
      */
     public ControllerException(int causeCode, String message, Throwable cause) {
         super(message, cause);
         this.causeCode = causeCode;
     }
 
+    /**
+     * returns the cause code
+     * @return the cause code
+     */
     public int getCauseCode() {
         return causeCode;
     }

jeeutil/src/main/java/de/muehlencord/shared/jeeutil/FacesUtil.java

@@ -20,6 +20,7 @@ import javax.faces.application.FacesMessage;
 import javax.faces.context.FacesContext;
 
 /**
+ * Helper class for java faces application.
  *
  * @author Joern Muehlencord (joern@muehlencord.de)
  */
@@ -29,17 +30,32 @@ public abstract class FacesUtil {
         // hide constructor of abstract class
     }
 
+    /**
+     * returns true, if the current request is in the request phase. False
+     * otherwise.
+     *
+     * @return true, if the current request is in the request phase. False
+     * otherwise.
+     */
     public static boolean isRenderRequest() {
         return !FacesContext.getCurrentInstance().getRenderResponse();
     }
 
+    /**
+     * returns true, if the current request is in the response phase. True
+     * otherwise.
+     *
+     * @return true, if the current request is in the response phase. True
+     * otherwise.
+     */
     public static boolean isRenderResponse() {
         return FacesContext.getCurrentInstance().getRenderResponse();
     }
 
     /**
+     * Adds the given message to the "messages" object
      *
-     * @param message
+     * @param message the message to display
      * @deprecated use addMessage(clientId, message) or
      * addGlobalMessage(message) instead
      */
@@ -48,57 +64,114 @@ public abstract class FacesUtil {
         FacesContext.getCurrentInstance().addMessage("messages", message);
     }
 
+    /**
+     * Adds the given message to the object with the id specified by clientId.
+     *
+     * @param clientId the id of the object to bind the message to.
+     * @param message the message to display
+     */
     public static void addMessage(String clientId, FacesMessage message) {
         FacesContext.getCurrentInstance().addMessage(clientId, message);
     }
 
+    /**
+     * Adds the given message as global message.
+     *
+     * @param message the message to display
+     */
     public static void addGlobalMessage(FacesMessage message) {
         FacesContext.getCurrentInstance().addMessage(null, message);
     }
 
+    /**
+     * Adds the given message as global message with severity "Information".
+     *
+     * @param summary the message to add
+     */
     public static void addGlobalInfoMessage(String summary) {
         FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_INFO, summary, null);
         FacesContext.getCurrentInstance().addMessage(null, message);
     }
 
+    /**
+     * Adds the given message as global message with severity "Information".
+     *
+     * @param summary the summary message to display
+     * @param detail the detailed message to display
+     */
     public static void addGlobalInfoMessage(String summary, String detail) {
         FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_INFO, summary, detail);
         FacesContext.getCurrentInstance().addMessage(null, message);
     }
 
+    /**
+     * Adds the given message as global message with severity "Warning".
+     *
+     * @param summary the summary message to display
+     */
     public static void addGlobalWarningMessage(String summary) {
         FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_WARN, summary, null);
         FacesContext.getCurrentInstance().addMessage(null, message);
     }
 
+    /**
+     * Adds the given message as global message with severity "Warning".
+     *
+     * @param summary the summary message to display
+     * @param detail the detailed message to display
+     */
     public static void addGlobalWarningMessage(String summary, String detail) {
         FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_WARN, summary, detail);
         FacesContext.getCurrentInstance().addMessage(null, message);
     }
 
+    /**
+     * Adds the given message as global message with severity "Error".
+     *
+     * @param summary the message to display
+     */
     public static void addGlobalErrorMessage(String summary) {
         FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_ERROR, summary, null);
         FacesContext.getCurrentInstance().addMessage(null, message);
     }
 
+    /**
+     * Adds the given message as global message with severity "Error".
+     *
+     * @param summary the summary message to display
+     * @param detail the detailed message to display
+     */
     public static void addGlobalErrorMessage(String summary, String detail) {
         FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_ERROR, summary, detail);
         FacesContext.getCurrentInstance().addMessage(null, message);
     }
 
+    /**
+     * Adds the given message as global message with severity "Fatal".
+     *
+     * @param summary the message to display
+     */
     public static void addGlobalFatalMessage(String summary) {
         FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_FATAL, summary, null);
         FacesContext.getCurrentInstance().addMessage(null, message);
     }
 
+    /**
+     * Adds the given message as global message with severity "Fatal".
+     *
+     * @param summary the summary message to display
+     * @param detail the detailed message to display
+     */
     public static void addGlobalFatalMessage(String summary, String detail) {
         FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_FATAL, summary, detail);
         FacesContext.getCurrentInstance().addMessage(null, message);
     }
 
     /**
+     * Adds the given message to the object with id "messages" and severity
+     * "Information".
      *
-     * @param summary
+     * @param summary the message to display
      * @deprecated use addInfoMessage(clientId, summary) or addGlobalInfoMessage
      * instead
      */
@@ -108,9 +181,11 @@ public abstract class FacesUtil {
     }
 
     /**
+     * Adds the given message to the object with id "messages" and severity
+     * "Information".
      *
-     * @param summary
+     * @param summary the summary message to display
-     * @param detail
+     * @param detail the detailed message to display
      * @deprecated use addInfoMessage (clientId, summary, detail) or
      * addGlobalInfoMessage(summary, detail) instead
      */
@@ -119,14 +194,24 @@ public abstract class FacesUtil {
         addInfoMessage("messages", summary, detail);
     }
 
+    /**
+     * Adds the given message with severity "Info" to the object with the id
+     * specified by clientId.
+     *
+     * @param clientId the id of the object to bind the message to.
+     * @param summary the summary message to display
+     * @param detail the detailed message to display
+     */
     public static void addInfoMessage(String clientId, String summary, String detail) {
         FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_INFO, summary, detail);
         FacesContext.getCurrentInstance().addMessage(clientId, message);
     }
 
     /**
+     * Adds the given message to the object with id "warnings" and severity
+     * "Error".
      *
-     * @param summary
+     * @param summary the message to display
      * @deprecated use addErrorMessage (clientId, summary, detail) or
      * addGlobalErrorMessage(summary, detail) instead
      */
@@ -136,9 +221,12 @@ public abstract class FacesUtil {
     }
 
     /**
+     * Adds the given message to the object with id "warnings" and severity
+     * "Error".
      *
-     * @param summary
+     *
-     * @param detail
+     * @param summary the summary message to display
+     * @param detail the detailed message to display
      * @deprecated use addErrorMessage (clientId, summary, detail) or
      * addGlobalErrorMessage(summary, detail) instead
      */
@@ -147,14 +235,24 @@ public abstract class FacesUtil {
         addErrorMessage("warnings", summary, detail);
     }
 
+    /**
+     * Adds the given message with severity "Error" to the object with the id
+     * specified by clientId.
+     *
+     * @param clientId the id of the object to bind the message to.
+     * @param summary the summary message to display
+     * @param detail the detailed message to display
+     */
     public static void addErrorMessage(String clientId, String summary, String detail) {
         FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_ERROR, summary, detail);
         FacesContext.getCurrentInstance().addMessage(clientId, message);
     }
 
     /**
+     * Adds the given message to the object with id "warnings" and severity
+     * "Warning".
      *
-     * @param summary
+     * @param summary the message to display
      * @deprecated use addWarningMessage (clientId, summary, detail) or
      * addGlobalWarningMessage(summary, detail) instead
      */
@@ -164,9 +262,11 @@ public abstract class FacesUtil {
     }
 
     /**
+     * Adds the given message to the object with id "warnings" and severity
+     * "Warning".
      *
-     * @param summary
+     * @param summary the summary message to display
-     * @param detail
+     * @param detail the detailed message to display
      * @deprecated use addWarningMessage (clientId, summary, detail) or
      * addGlobalWarningMessage(summary, detail) instead
      */
@@ -176,15 +276,25 @@ public abstract class FacesUtil {
         FacesContext.getCurrentInstance().addMessage("warnings", message);
     }
 
+    /**
+     * Adds the given message with severity "Warning" to the object with the id
+     * specified by clientId.
+     *
+     * @param clientId the id of the object to bind the message to.
+     * @param summary the summary message to display
+     * @param detail the detailed message to display
+     */
     public static void addWarningMessage(String clientId, String summary, String detail) {
         FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_WARN, summary, detail);
         FacesContext.getCurrentInstance().addMessage(clientId, message);
     }
 
     /**
+     * Adds the given message to the object with id "warnings" and severity
+     * "Fatal".
      *
-     * @param summary
+     * @param summary the summary message to display
-     * @param detail
+     * @param detail the detailed message to display
      * @deprecated use addFatalMessage (clientId, summary, detail) or
      * addGlobalFatalMessage(summary, detail) instead
      */
@@ -194,11 +304,23 @@ public abstract class FacesUtil {
         FacesContext.getCurrentInstance().addMessage("warnings", message);
     }
 
+    /**
+     * Adds the given message with severity "Fatal" to the object with the id
+     * specified by clientId.
+     *
+     * @param clientId the id of the object to bind the message to.
+     * @param summary the summary message to display
+     * @param detail the detailed message to display
+     */
     public static void addFatalMessage(String clientId, String summary, String detail) {
         FacesMessage message = new FacesMessage(FacesMessage.SEVERITY_FATAL, summary, detail);
         FacesContext.getCurrentInstance().addMessage(clientId, message);
     }
 
+    /**
+     *
+     * @param messages the messages to add
+     */
     public static void addMessages(List<UIMessage> messages) {
         messages.stream().map(msg -> msg.getFacesMessage()).forEach(msg -> {
             if (msg.getSeverity() == FacesMessage.SEVERITY_ERROR) {

network/src/main/java/de/muehlencord/shared/network/ldap/LDAPSearch.java

@@ -223,7 +223,7 @@ public class LDAPSearch {
      * @return true, if the given contact, specified by the email address is
      * member of the specified group. Otherwise false is returned.
      *
-     * @throws de.muehlencord.shared.network.ldap.LDAPException
+     * @throws de.muehlencord.shared.network.ldap.LDAPException if the validation fails.
      */
     public boolean isMemberOfGroup(String email, String groupDn) throws LDAPException {
         boolean returnValue = false;

shiro-faces/src/main/java/de/muehlencord/shirofaces/tags/unsupported/PrincipalTag.java

@@ -22,23 +22,30 @@ import javax.faces.view.facelets.FaceletContext;
 import javax.faces.view.facelets.TagConfig;
 
 /**
- * <p>
+ * <div>
  * Tag used to print out the String value of a user's default principal, or a
- * specific principal as specified by the tag's attributes.</p>
+ * specific principal as specified by the tag's attributes.
+ * </div>
  *
- * <p>
+ * <div>
- * If no attributes are specified, the tag prints out the <tt>toString()</tt>
+ * If no attributes are specified, the tag prints out the <b>toString()</b>
- * value of the user's default principal. If the <tt>type</tt> attribute is
+ * value of the user's default principal. If the <b>type</b> attribute is
  * specified, the tag looks for a principal with the given type. If the
- * <tt>property</tt> attribute is specified, the tag prints the string value of
+ * <b>property</b> attribute is specified, the tag prints the string value of
  * the specified property of the principal. If no principal is found or the user
- * is not authenticated, the tag displays nothing unless a <tt>defaultValue</tt>
+ * is not authenticated, the tag displays nothing unless a <b>defaultValue</b>
- * is specified.</p>
+ * is specified.
+ * </div>
  *
  * @author Joern Muehlencord (joern at muehlencord.de)
  */
 public class PrincipalTag extends AbstractTag {
 
+    /**
+     * creates a new principal tag
+     *
+     * @param config the configuration to use
+     */
     public PrincipalTag(TagConfig config) {
         super(config);
     }