jakarta.faces.application.FacesMessage Maven / Gradle / Ivy
Show all versions of jakarta.faces Show documentation
/*
* Copyright (c) 2022, 2023 Contributors to Eclipse Foundation.
* Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package jakarta.faces.application;
import static java.util.Arrays.stream;
import static java.util.function.Function.identity;
import static java.util.stream.Collectors.toUnmodifiableMap;
import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.io.Serializable;
import java.util.List;
import java.util.Map;
import java.util.Objects;
/**
*
* FacesMessage represents a single validation (or other) message, which is typically associated with a
* particular component in the view. A {@link jakarta.faces.application.FacesMessage} instance may be created based on a
* specific messageId. The specification defines the set of messageIds for which there must be
* {@link jakarta.faces.application.FacesMessage} instances.
*
*
*
* The implementation must take the following steps when creating FacesMessage instances given a
* messageId:
*
*
*
*
*
* Call {@link Application#getMessageBundle}. If non-null, locate the named ResourceBundle,
* using the Locale from the current {@link jakarta.faces.component.UIViewRoot} and see if it has a value
* for the argument messageId. If it does, treat the value as the summary of the
* FacesMessage. If it does not, or if {@link Application#getMessageBundle} returned null,
* look in the ResourceBundle named by the value of the constant {@link #FACES_MESSAGES} and see if it has
* a value for the argument messageId. If it does, treat the value as the summary of the
* FacesMessage. If it does not, there is no initialization information for the FacesMessage
* instance.
*
*
*
* In all cases, if a ResourceBundle hit is found for the {messageId}, look for further hits
* under the key {messageId}_detail. Use this value, if present, as the detail for the
* returned FacesMessage.
*
*
*
* Make sure to perform any parameter substitution required for the summary and detail of the
* FacesMessage.
*
*
*
*
*/
public class FacesMessage implements Serializable {
// --------------------------------------------------------------- Constants
private static final long serialVersionUID = -1180773928220076822L;
/**
*
* ResourceBundle identifier for messages whose message identifiers are defined in the Jakarta Faces
* specification.
*
*/
public static final String FACES_MESSAGES = "jakarta.faces.Messages";
// ------------------------------------------------- Message Severity Levels
// Any new Severity values must go at the end of the list, or we will break
// backwards compatibility on serialized instances
private static final String SEVERITY_INFO_NAME = "INFO";
/**
*
* Message severity level indicating an informational message rather than an error.
*
*/
public static final Severity SEVERITY_INFO = new Severity(SEVERITY_INFO_NAME);
private static final String SEVERITY_WARN_NAME = "WARN";
/**
*
* Message severity level indicating that an error might have occurred.
*
*/
public static final Severity SEVERITY_WARN = new Severity(SEVERITY_WARN_NAME);
private static final String SEVERITY_ERROR_NAME = "ERROR";
/**
*
* Message severity level indicating that an error has occurred.
*
*/
public static final Severity SEVERITY_ERROR = new Severity(SEVERITY_ERROR_NAME);
private static final String SEVERITY_FATAL_NAME = "FATAL";
/**
*
* Message severity level indicating that a serious error has occurred.
*
*/
public static final Severity SEVERITY_FATAL = new Severity(SEVERITY_FATAL_NAME);
/**
*
* Array of all defined values, ascending order of ordinal value. Be sure you include any new instances created above,
* in the same order.
*
*/
private static final Severity[] values = { SEVERITY_INFO, SEVERITY_WARN, SEVERITY_ERROR, SEVERITY_FATAL };
/**
*
* Immutable List of valid {@link jakarta.faces.application.FacesMessage.Severity} instances, in ascending
* order of their ordinal value.
*
*/
public static final List VALUES = List.of(values);
/**
*
* Immutable Map of valid {@link jakarta.faces.application.FacesMessage.Severity} instances, keyed by name.
*
*/
public final static Map VALUES_MAP = stream(values).collect(toUnmodifiableMap(severity -> severity.severityName, identity()));
// ------------------------------------------------------ Instance Variables
private transient Severity severity = SEVERITY_INFO;
private transient String summary = null;
private transient String detail = null;
private transient boolean rendered;
// ------------------------------------------------------------ Constructors
/**
*
* Construct a new {@link jakarta.faces.application.FacesMessage} with no initial values. The severity is set to
* Severity.INFO.
*
*/
public FacesMessage() {
super();
}
/**
*
* Construct a new {@link jakarta.faces.application.FacesMessage} with just a summary. The detail is null,
* the severity is set to Severity.INFO.
*
*
* @param summary the summary.
*/
public FacesMessage(String summary) {
super();
setSummary(summary);
}
/**
*
* Construct a new {@link jakarta.faces.application.FacesMessage} with the specified initial values. The severity is set
* to Severity.INFO.
*
*
* @param summary Localized summary message text
* @param detail Localized detail message text
*
* @throws IllegalArgumentException if the specified severity level is not one of the supported values
*/
public FacesMessage(String summary, String detail) {
super();
setSummary(summary);
setDetail(detail);
}
/**
*
* Construct a new FacesMessage with the specified initial values.
*
*
* @param severity the severity
* @param summary Localized summary message text
* @param detail Localized detail message text
*
* @throws IllegalArgumentException if the specified severity level is not one of the supported values
*/
public FacesMessage(Severity severity, String summary, String detail) {
super();
setSeverity(severity);
setSummary(summary);
setDetail(detail);
}
// ---------------------------------------------------------- Public Methods
/**
*
* Return the localized detail text. If no localized detail text has been defined for this message, return the localized
* summary text instead.
*
*
* @return the localized detail text.
*/
public String getDetail() {
if (detail == null) {
return summary;
}
return detail;
}
/**
*
* Set the localized detail text.
*
*
* @param detail The new localized detail text
*/
public void setDetail(String detail) {
this.detail = detail;
}
/**
*
* Return the severity level.
*
*
* @return the severity level.
*/
public Severity getSeverity() {
return severity;
}
/**
*
* Set the severity level.
*
*
* @param severity The new severity level
*
* @throws IllegalArgumentException if the specified severity level is not one of the supported values
*/
public void setSeverity(Severity severity) {
if (severity.getOrdinal() < SEVERITY_INFO.getOrdinal() || severity.getOrdinal() > SEVERITY_FATAL.getOrdinal()) {
throw new IllegalArgumentException(String.valueOf(severity));
}
this.severity = severity;
}
/**
*
* Return the localized summary text.
*
*
* @return the localized summary text.
*/
public String getSummary() {
return summary;
}
/**
*
* Set the localized summary text.
*
*
* @param summary The new localized summary text
*/
public void setSummary(String summary) {
this.summary = summary;
}
/**
* @return true if {@link #rendered()} has been called, otherwise false
*
* @since 2.0
*/
public boolean isRendered() {
return rendered;
}
/**
*
* Marks this message as having been rendered to the client.
*
*
* @since 2.0
*/
public void rendered() {
rendered = true;
}
/**
* @since 4.1
*/
@Override
public int hashCode() {
return Objects.hash(severity, summary, detail);
}
/**
* @since 4.1
*/
@Override
public boolean equals(Object object) {
return (object == this) || (object != null && object.getClass() == getClass()
&& Objects.equals(severity, ((FacesMessage) object).severity)
&& Objects.equals(summary, ((FacesMessage) object).summary)
&& Objects.equals(detail, ((FacesMessage) object).detail));
}
/**
* @since 4.1
*/
@Override
public String toString() {
return getClass().getSimpleName() + "["
+ "severity='" + severity + "', "
+ "summary='" + summary + "', "
+ "detail='" + detail + "']"
;
}
/**
*
* Persist {@link jakarta.faces.application.FacesMessage} artifacts, including the non serializable
* Severity.
*
*
* @param out The target stream to which the object will be written.
*
* @throws IOException Any of the usual Input/Output related exceptions.
*/
private void writeObject(ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
out.writeInt(severity.getOrdinal());
out.writeObject(summary);
out.writeObject(detail);
out.writeObject(rendered);
}
/**
*
* Reconstruct {@link jakarta.faces.application.FacesMessage} from serialized artifacts.
*
*
* @param in The binary input of the object to be read
*
* @throws IOException Any of the usual Input/Output related exceptions.
* @throws ClassNotFoundException Class of a serialized object cannot be found.
*
*/
private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();
severity = SEVERITY_INFO;
summary = null;
detail = null;
int ordinal = in.readInt();
if (ordinal == SEVERITY_INFO.getOrdinal()) {
severity = SEVERITY_INFO;
} else if (ordinal == SEVERITY_WARN.getOrdinal()) {
severity = SEVERITY_WARN;
} else if (ordinal == SEVERITY_ERROR.getOrdinal()) {
severity = SEVERITY_ERROR;
} else if (ordinal == SEVERITY_FATAL.getOrdinal()) {
severity = SEVERITY_FATAL;
}
summary = (String) in.readObject();
detail = (String) in.readObject();
rendered = (Boolean) in.readObject();
}
/**
*
* Class used to represent message severity levels in a typesafe enumeration.
*
*/
public static class Severity implements Comparable {
// ------------------------------------------------------- Constructors
/**
*
* Private constructor to disable the creation of new instances.
*
*/
private Severity(String newSeverityName) {
severityName = newSeverityName;
}
// -------------------------------------------------- Instance Variables
/**
*
* The ordinal value assigned to this instance.
*
*/
private final int ordinal = nextOrdinal++;
/**
*
* The (optional) name for this severity.
*
*/
String severityName;
// ----------------------------------------------------- Public Methods
/**
*
* Compare this {@link jakarta.faces.application.FacesMessage.Severity} instance to the specified one. Returns a
* negative integer, zero, or a positive integer if this object is less than, equal to, or greater than the specified
* object.
*
*
* @param severity The other object to be compared to
*/
@Override
public int compareTo(Object severity) {
return ordinal - ((Severity)severity).ordinal;
}
/**
*
* Return the ordinal value of this {@link FacesMessage.Severity} instance.
*
*
* @return the ordinal.
*/
public int getOrdinal() {
return ordinal;
}
/**
*
* Return a String representation of this {@link FacesMessage.Severity} instance.
*
*/
@Override
public String toString() {
if (severityName == null) {
return Integer.toString(ordinal);
}
return severityName + ' ' + ordinal;
}
// --------------------------------------------------- Static Variables
/**
*
* Static counter returning the ordinal value to be assigned to the next instance that is created.
*
*/
private static int nextOrdinal = 0;
}
}