@Qualifier @Retention(RUNTIME) @Target({METHOD,FIELD,PARAMETER}) public @interface Push

The CDI annotation @Push allows you to inject a PushContext associated with a given <f:websocket> channel in any container managed artifact in WAR.

 @Inject
 @Push
 private PushContext channelName;

Configuration

First enable the websocket endpoint by below boolean context parameter in web.xml.

 <context-param>
     <param-name>jakarta.faces.ENABLE_WEBSOCKET_ENDPOINT</param-name>
     <param-value>true</param-value>
 </context-param>

Declare <f:websocket> tag in the Jakarta Faces view with at least a channel name and an onmessage JavaScript listener function. The channel name may not be a Jakarta Expression Language expression and it may only contain alphanumeric characters, hyphens, underscores and periods.

Here's an example which refers an existing JavaScript listener function.

 <f:websocket channel="someChannel" onmessage="someWebsocketListener" />

 function someWebsocketListener(message, channel, event) {
     console.log(message);
 }

Here's an example which declares an inline JavaScript listener function.

 <f:websocket channel="someChannel" onmessage="function(message) { console.log(message); }" />

The onmessage JavaScript listener function will be invoked with three arguments:

message: the push message as JSON object.
channel: the channel name.
event: the raw MessageEvent instance.

In case your server is configured to run WS container on a different TCP port than the HTTP container, then you can use the optional jakarta.faces.WEBSOCKET_ENDPOINT_PORT integer context parameter in web.xml to explicitly specify the port.

 <context-param>
     <param-name>jakarta.faces.WEBSOCKET_ENDPOINT_PORT</param-name>
     <param-value>8000</param-value>
 </context-param>

When successfully connected, the websocket is by default open as long as the document is open, and it will auto-reconnect at increasing intervals when the connection is closed/aborted as result of e.g. a network error or server restart. It will not auto-reconnect when the very first connection attempt already fails. The websocket will be implicitly closed once the document is unloaded.

Usage (server)

In WAR side, you can inject PushContext via @Push annotation on the given channel name in any CDI/container managed artifact such as @Named, @WebServlet, etc wherever you'd like to send a push message and then invoke PushContext.send(Object) with any Java object representing the push message.

 @Inject
 @Push
 private PushContext someChannel;

 public void sendMessage(Object message) {
     someChannel.send(message);
 }

By default the name of the channel is taken from the name of the variable into which injection takes place. The channel name can be optionally specified via the channel attribute. The example below injects the push context for channel name foo into a variable named bar.

 @Inject
 @Push(channel = "foo")
 private PushContext bar;

The message object will be encoded as JSON and be delivered as message argument of the onmessage JavaScript listener function associated with the channel name. It can be a plain vanilla String, but it can also be a collection, map and even a javabean.

Although websockets support two-way communication, the <f:websocket> push is designed for one-way communication, from server to client. In case you intend to send some data from client to server, continue using Jakarta Faces ajax the usual way. This has among others the advantage of maintaining the Jakarta Faces view state, the HTTP session and, importantly, all security constraints on business service methods.

Scopes and users

By default the websocket is application scoped, i.e. any view/session throughout the web application having the same websocket channel open will receive the same push message. The push message can be sent by all users and the application itself.

The optional scope attribute can be set to session to restrict the push messages to all views in the current user session only. The push message can only be sent by the user itself and not by the application.

 <f:websocket channel="someChannel" scope="session" ... />

The scope attribute can also be set to view to restrict the push messages to the current view only. The push message will not show up in other views in the same session even if it's the same URL. The push message can only be sent by the user itself and not by the application.

 <f:websocket channel="someChannel" scope="view" ... />

The scope attribute may not be a Jakarta Expression Language expression and allowed values are application, session and view, case insensitive.

Additionally, the optional user attribute can be set to the unique identifier of the logged-in user, usually the login name or the user ID. This way the push message can be targeted to a specific user and can also be sent by other users and the application itself. The value of the user attribute must at least implement Serializable and have a low memory footprint, so putting entire user entity is not recommended.

E.g. when you're using container managed authentication or a related framework/library:

 <f:websocket channel="someChannel" user="#{request.remoteUser}" ... />

Or when you have a custom user entity around in Jakarta Expression Language as #{someLoggedInUser} which has an id property representing its identifier:

 <f:websocket channel="someChannel" user="#{someLoggedInUser.id}" ... />

When the user attribute is specified, then the scope defaults to session and cannot be set to application.

In the server side, the push message can be targeted to the user specified in the user attribute via PushContext.send(Object, Serializable). The push message can be sent by all users and the application itself.

 @Inject
 @Push
 private PushContext someChannel;

 public void sendMessage(Object message, User recipientUser) {
     Long recipientUserId = recipientUser.getId();
     someChannel.send(message, recipientUserId);
 }

Multiple users can be targeted by passing a Collection holding user identifiers to PushContext.send(Object, Collection).

 public void sendMessage(Object message, Group recipientGroup) {
     Collection<Long> recipientUserIds = recipientGroup.getUserIds();
     someChannel.send(message, recipientUserIds);
 }

Conditionally connecting

You can use the optional connected attribute to control whether to auto-connect the websocket or not.

 <f:websocket ... connected="#{bean.pushable}" />

It defaults to true and it's under the covers interpreted as a JavaScript instruction whether to open or close the websocket push connection. If the value is a Jakarta Expression Language expression and it becomes false during an ajax request, then the push connection will explicitly be closed during oncomplete of that ajax request.

You can also explicitly set it to false and manually open the push connection in client side by invoking faces.push.open(clientId), passing the component's client ID.

 <h:commandButton ... onclick="faces.push.open('foo')">
     <f:ajax ... />
 </h:commandButton>
 <f:websocket id="foo" channel="bar" scope="view" ... connected="false" />

In case you intend to have an one-time push and don't expect more messages, you can optionally explicitly close the push connection from client side by invoking faces.push.close(clientId), passing the component's client ID. For example, in the onmessage JavaScript listener function as below:

 function someWebsocketListener(message) {
     // ...
     faces.push.close('foo');
 }

Events (client)

The optional onopen JavaScript listener function can be used to listen on open of a websocket in client side. This will be invoked on the very first connection attempt, regardless of whether it will be successful or not. This will not be invoked when the websocket auto-reconnects a broken connection after the first successful connection.

 <f:websocket ... onopen="websocketOpenListener" />

 function websocketOpenListener(channel) {
     // ...
 }

The onopen JavaScript listener function will be invoked with one argument:

channel: the channel name, useful in case you intend to have a global listener.

The optional onerror JavaScript listener function can be used to listen on a connection error whereby the websocket will attempt to reconnect. This will be invoked when the websocket can make an auto-reconnect attempt on a broken connection after the first successful connection. This will be not invoked when the very first connection attempt fails, or the server has returned close reason code 1000 (normal closure) or 1008 (policy violated), or the maximum reconnect attempts has exceeded. Instead, the onclose will be invoked.

 <o:socket ... onerror="websocketErrorListener" />

 function websocketErrorListener(code, channel, event) {
     if (code == 1001) {
         // Server has returned an unexpected response code. E.g. 503, because it's shutting down.
     } else if (code == 1006) {
         // Server is not reachable anymore. I.e. it's not anymore listening on TCP/IP requests.
     } else {
         // Any other reason which is usually not -1, 1000 or 1008, as the onclose will be invoked instead.
     }

     // In any case, the websocket will attempt to reconnect. This function will be invoked again.
     // Once the websocket gives up reconnecting, the onclose will finally be invoked.
 }

The onerror JavaScript listener function will be invoked with three arguments:

code: the close reason code as integer. See also RFC 6455 section 7.4.1 and CloseReason.CloseCodes API for an elaborate list of all close codes.
channel: the channel name, useful in case you intend to have a global listener.
event: the raw CloseEvent instance, useful in case you intend to inspect it.

The optional onclose JavaScript listener function can be used to listen on (ab)normal close of a websocket. This will be invoked when the very first connection attempt fails, or the server has returned close reason code 1000 (normal closure) or 1008 (policy violated), or the maximum reconnect attempts has exceeded. This will not be invoked when the websocket can make an auto-reconnect attempt on a broken connection after the first successful connection. Instead, the onerror will be invoked.

 <f:websocket ... onclose="websocketCloseListener" />

 function websocketCloseListener(code, channel, event) {
     if (code == -1) {
         // websockets not supported by client.
     } else if (code == 1000) {
         // Normal close (as result of expired session or view).
     } else {
         // Abnormal close reason (as result of an error).
     }
 }

The onclose JavaScript listener function will be invoked with three arguments:

code: the close reason code as integer. If this is -1, then the websocket is simply not supported by the client. If this is 1000, then it was normally closed due to an expired session or view. Else if this is not 1000, then there may be an error. See also RFC 6455 section 7.4.1 and CloseReason.CloseCodes API for an elaborate list of all close codes.
channel: the channel name.
event: the raw CloseEvent instance.

When a session or view scoped websocket is automatically closed with close reason code 1000 by the server (and thus not manually by the client via faces.push.close(clientId)), then it means that the session or view has expired.

Events (server)

When a websocket has been opened, a new CDI WebsocketEvent will be fired with @WebsocketEvent.Opened qualifier. When a websocket has been closed, a new CDI WebsocketEvent will be fired with @WebsocketEvent.Closed qualifier. They can only be observed and collected in an application scoped CDI bean as below.

 @ApplicationScoped
 public class WebsocketObserver {

     public void onOpen(@Observes @Opened WebsocketEvent event) {
         String channel = event.getChannel(); // Returns <f:websocket channel>.
         Long userId = event.getUser(); // Returns <f:websocket user>, if any.
         // ...
     }

     public void onClose(@Observes @Closed WebsocketEvent event) {
         String channel = event.getChannel(); // Returns <f:websocket channel>.
         Long userId = event.getUser(); // Returns <f:websocket user>, if any.
         CloseCode code = event.getCloseCode(); // Returns close reason code.
         // ...
     }

 }

Security considerations

If the websocket is declared in a page which is only restricted to logged-in users with a specific role, then you may want to add the URL of the push handshake request URL to the set of restricted URLs.

The push handshake request URL is composed of the URI prefix /jakarta.faces.push/, followed by channel name. So, in case of for example container managed security which has already restricted an example page /user/foo.xhtml to logged-in users with the example role USER on the example URL pattern /user/* in web.xml like below,

 <security-constraint>
     <web-resource-collection>
         <web-resource-name>Restrict access to role USER.</web-resource-name>
         <url-pattern>/user/*</url-pattern>
     </web-resource-collection>
     <auth-constraint>
         <role-name>USER</role-name>
     </auth-constraint>
 </security-constraint>

.. and the page /user/foo.xhtml in turn contains a <f:websocket channel="foo">, then you need to add a restriction on push handshake request URL pattern of /jakarta.faces.push/foo like below.

 <security-constraint>
     <web-resource-collection>
         <web-resource-name>Restrict access to role USER.</web-resource-name>
         <url-pattern>/user/*</url-pattern>
         <url-pattern>/jakarta.faces.push/foo</url-pattern>
     </web-resource-collection>
     <auth-constraint>
         <role-name>USER</role-name>
     </auth-constraint>
 </security-constraint>

As extra security, particularly for those public channels which can't be restricted by security constraints, the <f:websocket> will register all so far declared channels in the current HTTP session, and any incoming websocket open request will be checked whether they match the so far registered channels in the current HTTP session. In case the channel is unknown (e.g. randomly guessed or spoofed by endusers or manually reconnected after the session is expired), then the websocket will immediately be closed with close reason code CloseReason.CloseCodes.VIOLATED_POLICY (1008). Also, when the HTTP session gets destroyed, all session and view scoped channels which are still open will explicitly be closed from server side with close reason code CloseReason.CloseCodes.NORMAL_CLOSURE (1000). Only application scoped websockets remain open and are still reachable from server end even when the session or view associated with the page in client side is expired.

Ajax support

In case you'd like to perform complex UI updates depending on the received push message, then you can nest <f:ajax> inside <f:websocket>. Here's an example:

 <h:panelGroup id="foo">
     ... (some complex UI here) ...
 </h:panelGroup>

 <h:form>
     <f:websocket channel="someChannel" scope="view">
         <f:ajax event="someEvent" listener="#{bean.pushed}" render=":foo" />
     </f:websocket>
 </h:form>

Here, the push message simply represents the ajax event name. You can use any custom event name.

 someChannel.send("someEvent");

An alternative is to combine <w:websocket> with <h:commandScript>. E.g.

 <h:panelGroup id="foo">
     ... (some complex UI here) ...
 </h:panelGroup>

 <f:websocket channel="someChannel" scope="view" onmessage="someCommandScript" />
 <h:form>
     <h:commandScript name="someCommandScript" action="#{bean.pushed}" render=":foo" />
 </h:form>

If you pass a Map<String,V> or a JavaBean as push message object, then all entries/properties will transparently be available as request parameters in the command script method #{bean.pushed}.

Since:

2.3

See Also:

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static final class

Push.Literal

Supports inline instantiation of the Push qualifier.
Optional Element Summary

Optional Elements

Modifier and Type

Optional Element

Description

String

channel

(Optional) The name of the push channel.

Element Details
- channel
  
  String channel
  
  (Optional) The name of the push channel. If not specified the name of the injection target field will be used.
  
  Returns:
  
  The name of the push channel.
  
  Default:
  
  ""

Annotation Interface Push

Configuration

Usage (client)

Usage (server)

Scopes and users

Conditionally connecting

Events (client)

Events (server)

Security considerations

Ajax support

Nested Class Summary

Optional Element Summary

Element Details

channel