jakarta.faces.component.UIWebsocket Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jakarta.faces Show documentation
Show all versions of jakarta.faces Show documentation
EE4J Compatible Implementation for Jakarta Faces API
The newest version!
/*
* 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.component;
import static jakarta.faces.push.PushContext.ENABLE_WEBSOCKET_ENDPOINT_PARAM_NAME;
import static java.util.Collections.unmodifiableList;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collection;
import java.util.regex.Pattern;
import jakarta.el.ValueExpression;
import jakarta.faces.component.behavior.ClientBehaviorHolder;
import jakarta.faces.context.ExternalContext;
import jakarta.faces.context.FacesContext;
import jakarta.faces.push.Push;
import jakarta.faces.push.PushContext;
import jakarta.websocket.CloseReason.CloseCodes;
/**
*
* The <f:websocket> tag opens an one-way (server to client) websocket based push connection in
* client side which can be reached from server side via {@link PushContext} interface injected in any CDI/container
* managed artifact via @{@link Push} annotation.
*
*
*
* By default, the rendererType property must be set to "jakarta.faces.Websocket". This value
* can be changed by calling the setRendererType() method.
*
*
*
* For detailed usage instructions, see @{@link Push} javadoc.
*
*
* @see Push
* @since 2.3
*/
public class UIWebsocket extends UIComponentBase implements ClientBehaviorHolder {
// ---------------------------------------------------------------------------------------------- Manifest Constants
/**
*
* The standard component type for this component.
*
*/
public static final String COMPONENT_TYPE = "jakarta.faces.Websocket";
/**
*
* The standard component family for this component.
*
*/
public static final String COMPONENT_FAMILY = "jakarta.faces.Script";
/**
*
* Properties that are tracked by state saving.
*
*/
enum PropertyKeys {
channel, scope, user, onopen, onmessage, onerror, onclose, connected;
}
private static final Pattern PATTERN_CHANNEL_NAME = Pattern.compile("[\\w.-]+");
private static final String ERROR_ENDPOINT_NOT_ENABLED = "f:websocket endpoint is not enabled." + " You need to set web.xml context param '"
+ ENABLE_WEBSOCKET_ENDPOINT_PARAM_NAME + "' with value 'true'.";
private static final String ERROR_INVALID_CHANNEL = "f:websocket 'channel' attribute '%s' does not represent a valid channel name. It is required, it may not be an"
+ "Jakarta Expression Language expression and it may only contain alphanumeric characters, hyphens, underscores and periods.";
private static final String ERROR_INVALID_USER = "f:websocket 'user' attribute '%s' does not represent a valid user identifier. It must implement Serializable and"
+ " preferably have low memory footprint. Suggestion: use #{request.remoteUser} or #{someLoggedInUser.id}.";
// ---------------------------------------------------------------------------------------------------- Constructors
/**
*
* Create a new {@link UIWebsocket} instance with default property values.
*
*
* @throws IllegalStateException When Websocket endpoint is not enabled.
*/
public UIWebsocket() {
ExternalContext externalContext = FacesContext.getCurrentInstance().getExternalContext();
if (!Boolean.parseBoolean(externalContext.getInitParameter(ENABLE_WEBSOCKET_ENDPOINT_PARAM_NAME))) {
throw new IllegalStateException(ERROR_ENDPOINT_NOT_ENABLED);
}
}
// --------------------------------------------------------------------------------------------- UIComponent Methods
/**
*
* Returns {@link UIWebsocket#COMPONENT_FAMILY}.
*
*/
@Override
public String getFamily() {
return COMPONENT_FAMILY;
}
/**
*
* Set the {@link ValueExpression} used to calculate the value for the specified attribute or property name, if any. If
* a {@link ValueExpression} is set for the channel or scope property, regardless of the
* value, throw an illegal argument exception. If a {@link ValueExpression} is set for the user property,
* and the non-null value is not an instance of Serializable, throw an illegal argument exception.
*
*
* @throws IllegalArgumentException If name is one of id, parent,
* channel or scope, or it name is user and the non-null value is
* not an instance of Serializable.
* @throws NullPointerException If name is null.
*/
@Override
public void setValueExpression(String name, ValueExpression binding) {
if (PropertyKeys.channel.toString().equals(name) || PropertyKeys.scope.toString().equals(name)) {
throw new IllegalArgumentException(name);
}
if (PropertyKeys.user.toString().equals(name)) {
Object user = binding.getValue(getFacesContext().getELContext());
if (user != null && !(user instanceof Serializable)) {
throw new IllegalArgumentException(String.format(ERROR_INVALID_USER, user));
}
}
super.setValueExpression(name, binding);
}
// ------------------------------------------------------------------------------------ ClientBehaviorHolder Methods
/**
*
* Returns a non-null, empty, unmodifiable Collection which returns true on any
* Collection#contains() invocation, indicating that all client behavior event names are acceptable.
*
*/
@Override
public Collection getEventNames() {
return CONTAINS_EVERYTHING;
}
private static final Collection CONTAINS_EVERYTHING = unmodifiableList(new ArrayList() {
private static final long serialVersionUID = 1L;
@Override
public boolean contains(Object object) {
return true;
}
});
// ------------------------------------------------------------------------------------------------------ Properties
/**
* Returns the name of the websocket channel.
*
* @return The name of the websocket channel.
*/
public String getChannel() {
return (String) getStateHelper().eval(PropertyKeys.channel);
}
/**
* Sets the name of the websocket channel. It may not be an Jakarta Expression Language expression and it may only
* contain alphanumeric characters, hyphens, underscores and periods. All open websockets on the same channel will
* receive the same push message from the server.
*
* @param channel The name of the websocket channel.
* @throws IllegalArgumentException When the value does not represent a valid channel name.
*/
public void setChannel(String channel) {
if (channel == null || !PATTERN_CHANNEL_NAME.matcher(channel).matches()) {
throw new IllegalArgumentException(String.format(ERROR_INVALID_CHANNEL, channel));
}
getStateHelper().put(PropertyKeys.channel, channel);
}
/**
* Returns the scope of the websocket channel.
*
* @return The scope of the websocket channel.
*/
public String getScope() {
return (String) getStateHelper().eval(PropertyKeys.scope);
}
/**
* Sets the scope of the websocket channel. It may not be an Jakarta Expression Language expression and allowed values
* are application, session and view, case insensitive. When the value is
* application, then all channels with the same name throughout the application will receive the same push
* message. When the value is session, then only the channels with the same name in the current user
* session will receive the same push message. When the value is view, then only the channel in the current
* view will receive the push message. The default scope is application. When the user
* attribute is specified, then the default scope is session.
*
* @param scope The scope of the websocket channel.
*/
public void setScope(String scope) {
getStateHelper().put(PropertyKeys.scope, scope);
}
/**
* Returns the user identifier of the websocket channel.
*
* @return The user identifier of the websocket channel.
*/
public Serializable getUser() {
return (Serializable) getStateHelper().eval(PropertyKeys.user);
}
/**
* Sets the user identifier of the websocket channel, so that user-targeted push messages can be sent. All open
* websockets on the same channel and user will receive the same push message from the server. It must implement
* Serializable and preferably have low memory footprint. Suggestion: use
* #{request.remoteUser} or #{someLoggedInUser.id}.
*
* @param user The user identifier of the websocket channel.
*/
public void setUser(Serializable user) {
getStateHelper().put(PropertyKeys.user, user);
}
/**
* Returns the JavaScript event handler function that is invoked when the websocket is opened.
*
* @return The JavaScript event handler function that is invoked when the websocket is opened.
*/
public String getOnopen() {
return (String) getStateHelper().eval(PropertyKeys.onopen);
}
/**
* Sets the JavaScript event handler function that is invoked when the websocket is opened. The function will be invoked
* with one argument: the channel name.
*
* @param onopen The JavaScript event handler function that is invoked when the websocket is opened.
*/
public void setOnopen(String onopen) {
getStateHelper().put(PropertyKeys.onopen, onopen);
}
/**
* Returns the JavaScript event handler function that is invoked when a push message is received from the server.
*
* @return The JavaScript event handler function that is invoked when a push message is received from the server.
*/
public String getOnmessage() {
return (String) getStateHelper().eval(PropertyKeys.onmessage);
}
/**
* Sets the JavaScript event handler function that is invoked when a push message is received from the server. The
* function will be invoked with three arguments: the push message, the channel name and the raw MessageEvent itself.
*
* @param onmessage The JavaScript event handler function that is invoked when a push message is received from the
* server.
*/
public void setOnmessage(String onmessage) {
getStateHelper().put(PropertyKeys.onmessage, onmessage);
}
/**
*
* Returns the JavaScript event handler function that is invoked when a connection error has occurred and the websocket
* will attempt to reconnect.
*
*
* @return The JavaScript event handler function that is invoked when a connection error has occurred and the websocket
* will attempt to reconnect.
*
* @since 4.0
*/
public String getOnerror() {
return (String) getStateHelper().get(PropertyKeys.onerror);
}
/**
*
* Sets the JavaScript event handler function that is invoked when a connection error has occurred and the websocket
* will attempt to reconnect. The function will be invoked with three arguments: the error reason code, the
* channel name and the raw CloseEvent itself. Note that this will not be invoked on final close of the
* websocket, even when the final close is caused by an error. See also
* RFC 6455 section 7.4.1 and {@link CloseCodes} API
* for an elaborate list of all close codes.
*
*
* @param onerror The JavaScript event handler function that is invoked when a reconnection error has occurred.
*
* @since 4.0
*/
public void setOnerror(String onerror) {
getStateHelper().put(PropertyKeys.onerror, onerror);
}
/**
* Returns the JavaScript event handler function that is invoked when the websocket is closed
* and will not anymore attempt to reconnect.
*
* @return The JavaScript event handler function that is invoked when the websocket is closed and will not anymore
* attempt to reconnect.
*/
public String getOnclose() {
return (String) getStateHelper().eval(PropertyKeys.onclose);
}
/**
* Sets the JavaScript event handler function that is invoked when the websocket is closed
* and will not anymore attempt to reconnect. The function will be invoked
* with three arguments: the close reason code, the channel name and the raw CloseEvent itself.
* Note that this will also be invoked when the close is caused by an
* error and that you can inspect the close reason code if an actual connection error occurred and which one (i.e.
* when the code is not 1000 or 1008). See also RFC 6455
* section 7.4.1 and {@link CloseCodes} API for an elaborate list of all close codes.
*
* @param onclose The JavaScript event handler function that is invoked when the websocket is closed.
*/
public void setOnclose(String onclose) {
getStateHelper().put(PropertyKeys.onclose, onclose);
}
/**
* Returns whether to (auto)connect the websocket or not.
*
* @return Whether to (auto)connect the websocket or not.
*/
public boolean isConnected() {
return (Boolean) getStateHelper().eval(PropertyKeys.connected, Boolean.TRUE);
}
/**
* Sets whether to (auto)connect the websocket or not. Defaults to true. It's interpreted as a JavaScript
* instruction whether to open or close the websocket push connection. Note that this attribute is re-evaluated on every
* ajax request. You can also explicitly set it to false and then manually control in JavaScript by
*
* faces.push.open("channelName") and faces.push.close("channelName").
*
* @param connected Whether to (auto)connect the websocket or not.
*/
public void setConnected(boolean connected) {
getStateHelper().put(PropertyKeys.connected, connected);
}
}