Skip to content

docs: improve javadocs #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
paodb merged 1 commit into from
May 22, 2023
Merged

docs: improve javadocs #63

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions src/main/java/com/flowingcode/vaadin/addons/errorwindow/DefaultErrorWindowFactory.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,18 @@

package com.flowingcode.vaadin.addons.errorwindow;

/**
* Default implementation of {@link ErrorWindowFactory}. Displays error details using an {@link
* ErrorWindow}.
*/
public class DefaultErrorWindowFactory implements ErrorWindowFactory {

/**
* Displays the error details creating a new instance of {@link ErrorWindow}. The error window is
* displayed on the screen by invoking {@link ErrorWindow#open()}.
*
* @param details the error details to display
*/
@Override
public void showError(ErrorDetails details) {
ErrorWindow w = new ErrorWindow(details);
Expand Down
27 changes: 27 additions & 0 deletions src/main/java/com/flowingcode/vaadin/addons/errorwindow/ErrorDetails.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,29 +21,56 @@

package com.flowingcode.vaadin.addons.errorwindow;

/** Encapsulates error details, including the throwable object and the cause of the error. */
public class ErrorDetails {

private Throwable throwable;
private String cause;

/**
* Constructs a new ErrorDetails object with the given throwable and cause.
*
* @param throwable the throwable object that caused the error
* @param cause the cause of the error
*/
public ErrorDetails(Throwable throwable, String cause) {
super();
this.throwable = throwable;
this.cause = cause;
}

/**
* Retrieves the throwable object that caused the error.
*
* @return the throwable object that caused the error
*/
public Throwable getThrowable() {
return throwable;
}

/**
* Sets the throwable object that caused the error.
*
* @param throwable the throwable object that caused the error
*/
public void setThrowable(Throwable throwable) {
this.throwable = throwable;
}

/**
* Retrieves the cause of the error.
*
* @return the cause of the error
*/
public String getCause() {
return cause;
}

/**
* Sets the cause of the error.
*
* @param cause the cause of the error
*/
public void setCause(String cause) {
this.cause = cause;
}
Expand Down
38 changes: 38 additions & 0 deletions src/main/java/com/flowingcode/vaadin/addons/errorwindow/ErrorManager.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;

/**
* Manages errors and displays error messages through different ErrorWindowFactory implementations.
*/
public final class ErrorManager {

private static final Map<Class<?>, ErrorWindowFactory> factories = new ConcurrentHashMap<>();
Expand All @@ -46,29 +49,64 @@ private ErrorManager() {
throw new IllegalStateException("Utility class not meant to be instantiated");
}

/**
* Displays an error message for the given Throwable.
*
* @param throwable the Throwable object for which the error message should be displayed
*/
public static void showError(Throwable throwable) {
showError(throwable, throwable.getLocalizedMessage());
}

/**
* Displays an error message for the given Throwable with the specified cause message.
*
* @param throwable the Throwable object for which the error message should be displayed
* @param cause the cause for the error
*/
public static void showError(Throwable throwable, String cause) {
ErrorDetails details = new ErrorDetails(throwable, cause);
getErrorWindowFactory(throwable.getClass()).showError(details);
}

/**
* Sets the ErrorWindowFactory for the specified Throwable class.
*
* @param clazz the class of Throwable for which the ErrorWindowFactory should be set
* @param errorWindowFactory the ErrorWindowFactory implementation to be set for the specified
* class
*/
public static void setErrorWindowFactory(Class<? extends Throwable> clazz,
ErrorWindowFactory errorWindowFactory) {
factories.put(clazz.asSubclass(Throwable.class), errorWindowFactory);
}

/**
* Gets the ErrorWindowFactory implementation for the specified class or its super classes.
*
* @param clazz the class for which the ErrorWindowFactory implementation is needed
* @return the ErrorWindowFactory implementation associated with the specified class or its super
* classes
*/
public static ErrorWindowFactory getErrorWindowFactory(Class<?> clazz) {
return Optional.ofNullable(factories.get(clazz))
.orElseGet(() -> getErrorWindowFactory(clazz.getSuperclass()));
}

/**
* Sets the default ErrorWindowFactory implementation.
*
* @param errorWindowFactory the default ErrorWindowFactory implementation to be set
*/
public static void setErrorWindowFactory(ErrorWindowFactory errorWindowFactory) {
factories.put(Throwable.class, errorWindowFactory);
}

/**
* Gets the default ErrorWindowFactory implementation.
*
* @return the default ErrorWindowFactory implementation
*/
public static ErrorWindowFactory getErrorWindowFactory() {
return getErrorWindowFactory(Throwable.class);
}
Expand Down
9 changes: 9 additions & 0 deletions src/main/java/com/flowingcode/vaadin/addons/errorwindow/ErrorView.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,21 @@
import com.vaadin.flow.router.internal.DefaultErrorHandler;
import org.apache.http.HttpStatus;

/** View used to display an error message when navigation fails due to an exception. */
@SuppressWarnings("serial")
@DefaultErrorHandler
@javax.annotation.security.PermitAll
@jakarta.annotation.security.PermitAll
public class ErrorView extends VerticalLayout implements HasErrorParameter<Exception> {

/**
* This method sets the error parameter to display the error message and returns an HTTP status
* code of 500 Internal Server Error.
*
* @param event a {@code BeforeEnterEvent} object
* @param parameter an {@code ErrorParameter} object containing the caught exception
* @return an int representing the HTTP status code 500 Internal Server Error
*/
@Override
public int setErrorParameter(BeforeEnterEvent event, ErrorParameter<Exception> parameter) {
setSizeFull();
Expand Down
58 changes: 56 additions & 2 deletions src/main/java/com/flowingcode/vaadin/addons/errorwindow/ErrorWindow.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,18 @@
import org.slf4j.LoggerFactory;

/**
* Component to visualize an error, caused by an exception, as a modal sub-window. <br>
* When in production mode it shows a code to report. <br>
* Component to visualize an error, caused by an exception, as a modal sub-window.
* When in production mode it shows a code to report.
* When in debug mode it allows to visualize the stack trace of the error.
*
* <p>This class has several constructors that allow specifying the cause of the error, an error message, whether the application is in production mode,
* and the internationalization of the error message.</p>
*
* <p>This class also provides constructors that accept an {@link ErrorDetails} instance, which provides additional information about the error.</p>
*
* <p>A unique identifier is assigned to the dialog window, for use in reporting the error when in production mode.</p>
*
* @see ErrorDetails
* @author pbartolo
*/
@SuppressWarnings("serial")
Expand All @@ -68,26 +76,65 @@ public class ErrorWindow extends Dialog {

private Registration attachListenerRegistration;

/**
* Constructs and initializes an ErrorWindow object with the supplied cause and default production mode and i18n.
*
* @param cause: The cause of the error
*/
public ErrorWindow(final Throwable cause) {
this(cause, null, isProductionMode(), ErrorWindowI18n.createDefault());
}

/**
* Constructs and initializes an ErrorWindow object with the supplied details and and default production mode.
*
* @param cause: The cause of the error
* @param i18n: The internationalization of the ErrorWindow
*/
public ErrorWindow(final Throwable cause, final ErrorWindowI18n i18n) {
this(cause, null, isProductionMode(), i18n);
}

/**
* Constructs and initializes an ErrorWindow object with the supplied details and default and default production mode and i18n.
*
* @param cause: The cause of the error
* @param errorMessage: An optional error message
*/
public ErrorWindow(final Throwable cause, final String errorMessage) {
this(cause, errorMessage, isProductionMode(), ErrorWindowI18n.createDefault());
}

/**
* Constructs and initializes an ErrorWindow object with the supplied details and default production mode.
*
* @param cause: The cause of the error
* @param errorMessage: An optional error message
* @param i18n: The internationalization of the ErrorWindow
*/
public ErrorWindow(final Throwable cause, final String errorMessage, final ErrorWindowI18n i18n) {
this(cause, errorMessage, isProductionMode(), i18n);
}

/**
* Constructs and initializes an ErrorWindow object with the supplied details and default i18n.
*
* @param cause: The cause of the error
* @param errorMessage: An optional error message
* @param productionMode: The mode in which the Application is running. If true, a code is displayed with error details, else debug information is shown
*/
public ErrorWindow(final Throwable cause, final String errorMessage, boolean productionMode) {
this(cause, errorMessage, productionMode, ErrorWindowI18n.createDefault());
}

/**
* Constructs and initializes an ErrorWindow object with the supplied details.
*
* @param cause: The cause of the error
* @param errorMessage: An optional error message
* @param productionMode: The mode in which the Application is running. If true, a code is displayed with error details, else debug information is shown
* @param i18n: The internationalization of the ErrorWindow
*/
public ErrorWindow(
final Throwable cause,
final String errorMessage,
Expand Down Expand Up @@ -126,6 +173,13 @@ public ErrorWindow(ErrorDetails errorDetails, boolean productionMode) {
this(errorDetails.getThrowable(), errorDetails.getCause(), productionMode);
}

/**
* Constructs and initializes an ErrorWindow object with the supplied error details and internationalization.
* This constructor allows for provision of additional information, which is an ErrorDetails object.
*
* @param errorDetails: The ErrorDetails object
* @param i18n: The internationalization of the ErrorWindow
*/
public ErrorWindow(ErrorDetails errorDetails, final ErrorWindowI18n i18n) {
this(errorDetails.getThrowable(), errorDetails.getCause(), i18n);
}
Expand Down
11 changes: 11 additions & 0 deletions src/main/java/com/flowingcode/vaadin/addons/errorwindow/ErrorWindowFactory.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,21 @@

package com.flowingcode.vaadin.addons.errorwindow;

/** A factory interface for creating error windows. */
public interface ErrorWindowFactory {

/**
* Shows the error details on a new window.
*
* @param details the details of the error to be shown
*/
void showError(ErrorDetails details);

/**
* Checks whether the application is in production mode.
*
* @return true if the application is in production mode, false otherwise
*/
default boolean isProductionMode() {
return ("true".equals(System.getProperty("productionMode")));
}
Expand Down
32 changes: 24 additions & 8 deletions src/main/java/com/flowingcode/vaadin/addons/errorwindow/ErrorWindowI18n.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@

/**
* Internationalization object for customizing the component UI texts. An instance with the default
* messages can be obtained using {@link ErrorWindowI18n#createDefault()}
* messages can be obtained using {@link ErrorWindowI18n#createDefault()}.
*
* @author [email protected]
*/
Expand All @@ -38,6 +38,7 @@ public class ErrorWindowI18n {
private String defaultErrorMessage;
private String clipboard;

/** Constructor for creating the default instance of the object. */
private ErrorWindowI18n() {
this.caption = "An error has occurred";
this.instructions = "Please report the following code to your system administrator";
Expand All @@ -47,6 +48,11 @@ private ErrorWindowI18n() {
this.clipboard = "Copy details to clipboard";
}

/**
* Constructor for creating an instance of the object from a message translator function.
*
* @param i18nTranslator a message translation function
*/
private ErrorWindowI18n(SerializableFunction<String, String> i18nTranslator) {
this.caption = i18nTranslator.apply("com.flowingcode.vaadin.addons.errorwindow.caption");
this.instructions =
Expand All @@ -58,11 +64,21 @@ private ErrorWindowI18n(SerializableFunction<String, String> i18nTranslator) {
this.clipboard = i18nTranslator.apply("com.flowingcode.vaadin.addons.errorwindow.clipboard");
}

/** @return a new instance with the default messages */
/**
* Creates a new instance with the default messages.
*
* @return a new instance with the default messages
*/
public static ErrorWindowI18n createDefault() {
return new ErrorWindowI18n();
}

/**
* Creates a new instance with the provided message translation function.
*
* @param i18nTranslator a message translation function
* @return a new instance with the provided message translation function
*/
public static ErrorWindowI18n create(SerializableFunction<String, String> i18nTranslator) {
return new ErrorWindowI18n(i18nTranslator);
}
Expand All @@ -72,7 +88,7 @@ public void setCaption(final String caption) {
this.caption = caption;
}

/** @return returns the caption of the error window. */
/** @return returns the caption of the error window */
public String getCaption() {
return this.caption;
}
Expand All @@ -82,7 +98,7 @@ public void setInstructions(final String instructions) {
this.instructions = instructions;
}

/** @return returns the instructions for the user if the UUID is displayed in production mode. */
/** @return returns the instructions for the user if the UUID is displayed in production mode */
public String getInstructions() {
return this.instructions;
}
Expand All @@ -92,7 +108,7 @@ public void setClose(final String close) {
this.close = close;
}

/** @return returns the text of the "Close"-Button. */
/** @return returns the text of the "Close"-Button */
public String getClose() {
return this.close;
}
Expand All @@ -102,7 +118,7 @@ public void setDetails(final String details) {
this.details = details;
}

/** @return returns the text of the "Details"-Button. */
/** @return returns the text of the "Details"-Button */
public String getDetails() {
return this.details;
}
Expand All @@ -117,13 +133,13 @@ public void setDefaultErrorMessage(final String defaultErrorMessage) {

/**
* @return returns the default error message shown if the message passed to the error window is
* <code>null</code>.
* <code>null</code>
*/
public String getDefaultErrorMessage() {
return this.defaultErrorMessage;
}

/** @return returns the text for the "Copy details to clipboard" button. */
/** @return returns the text for the "Copy details to clipboard" button */
public String getClipboard() {
return clipboard;
}
Expand Down
Loading