From a2430f748f1234b9ed03e0d3cf6f808ea4aed1ed Mon Sep 17 00:00:00 2001 From: Joern Muehlencord Date: Sun, 15 Sep 2019 13:37:38 +0200 Subject: [PATCH] updated API description --- .../shared/db/CommonAbstractController.java | 2 +- .../shared/db/ControllerException.java | 18 ++- .../muehlencord/shared/jeeutil/FacesUtil.java | 148 ++++++++++++++++-- .../shared/network/ldap/LDAPSearch.java | 2 +- .../tags/unsupported/PrincipalTag.java | 23 ++- 5 files changed, 166 insertions(+), 27 deletions(-) diff --git a/db/src/main/java/de/muehlencord/shared/db/CommonAbstractController.java b/db/src/main/java/de/muehlencord/shared/db/CommonAbstractController.java index 1e0d85f..565f9b2 100644 --- a/db/src/main/java/de/muehlencord/shared/db/CommonAbstractController.java +++ b/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) { diff --git a/db/src/main/java/de/muehlencord/shared/db/ControllerException.java b/db/src/main/java/de/muehlencord/shared/db/ControllerException.java index 126e57f..2dc8947 100644 --- a/db/src/main/java/de/muehlencord/shared/db/ControllerException.java +++ b/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 message - * @param cause + * @param causeCode the reason code + * @param message the detail message. The detail message is saved for later + * 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; } diff --git a/jeeutil/src/main/java/de/muehlencord/shared/jeeutil/FacesUtil.java b/jeeutil/src/main/java/de/muehlencord/shared/jeeutil/FacesUtil.java index 2c7df4c..1417ae6 100644 --- a/jeeutil/src/main/java/de/muehlencord/shared/jeeutil/FacesUtil.java +++ b/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 detail + * @param summary the summary message to display + * @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 detail + * @param summary the summary message to display + * @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 detail + * @param summary the summary message to display + * @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 messages) { messages.stream().map(msg -> msg.getFacesMessage()).forEach(msg -> { if (msg.getSeverity() == FacesMessage.SEVERITY_ERROR) { @@ -212,5 +334,5 @@ public abstract class FacesUtil { } }); } - + } diff --git a/network/src/main/java/de/muehlencord/shared/network/ldap/LDAPSearch.java b/network/src/main/java/de/muehlencord/shared/network/ldap/LDAPSearch.java index 7f5a968..895bda3 100644 --- a/network/src/main/java/de/muehlencord/shared/network/ldap/LDAPSearch.java +++ b/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; diff --git a/shiro-faces/src/main/java/de/muehlencord/shirofaces/tags/unsupported/PrincipalTag.java b/shiro-faces/src/main/java/de/muehlencord/shirofaces/tags/unsupported/PrincipalTag.java index 43e66bf..911fbc5 100644 --- a/shiro-faces/src/main/java/de/muehlencord/shirofaces/tags/unsupported/PrincipalTag.java +++ b/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; /** - *

+ *

* 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.

+ * specific principal as specified by the tag's attributes. + *
* - *

- * If no attributes are specified, the tag prints out the toString() - * value of the user's default principal. If the type attribute is + *

+ * If no attributes are specified, the tag prints out the toString() + * value of the user's default principal. If the type attribute is * specified, the tag looks for a principal with the given type. If the - * property attribute is specified, the tag prints the string value of + * property 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 defaultValue - * is specified.

+ * is not authenticated, the tag displays nothing unless a defaultValue + * is specified. + *
* * @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); }