@Qualifier @Retention(value=RUNTIME) @Target(value={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;
First enable the web socket endpoint by below boolean context parameter in web.xml
.
<context-param> <param-name>javax.faces.ENABLE_WEBSOCKET_ENDPOINT</param-name> <param-value>true</param-value> </context-param>
Declare <f:websocket>
tag in the Jakarta Server 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 javax.faces.WEBSOCKET_ENDPOINT_PORT
integer context parameter in
web.xml
to explicitly specify the port.
<context-param> <param-name>javax.faces.WEBSOCKET_ENDPOINT_PORT</param-name> <param-value>8000</param-value> </context-param>
When successfully connected, the web socket 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 web socket will be implicitly closed once the document is unloaded.
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 web sockets 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 Server Faces ajax the usual way. This has among others the advantage of maintaining the Jakarta Server Faces view
state, the HTTP session and, importantly, all security constraints on business service methods.
By default the web socket is application
scoped, i.e. any view/session throughout the web application
having the same web socket 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); }
You can use the optional connected
attribute to control whether to auto-connect the web
socket 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 web socket 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 jsf.push.open(clientId)
, passing the component's client ID.
<h:commandButton ... onclick="jsf.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
jsf.push.close(clientId)
, passing the component's client ID. For example, in the
onmessage
JavaScript listener function as below:
function someWebsocketListener(message) { // ... jsf.push.close('foo'); }
The optional onopen
JavaScript listener function can be used to listen on open of a web
socket 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 web socket 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 onclose
JavaScript listener function can be used to listen on (ab)normal
close of a web socket. 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 web socket can make an auto-reconnect attempt on a broken
connection after the first successful connection.
<f:websocket ... onclose="websocketCloseListener" />
function websocketCloseListener(code, channel, event) { if (code == -1) { // Web sockets 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 web socket
is simply not supported by the client. If this is 1000
,
then it was normally closed. 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 socket is automatically closed with close reason code 1000
by the server
(and thus not manually by the client via jsf.push.close(clientId)
), then it means that the session
or view has expired.
When a web socket has been opened, a new CDI WebsocketEvent
will be fired with
@
WebsocketEvent.Opened
qualifier. When a web socket 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. // ... } }
If the socket 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 /javax.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 /javax.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>/javax.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 web socket 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 web socket 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 sockets remain open and are still
reachable from server end even when the session or view associated with the page in client side is expired.
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}
.
PushContext
,
UIWebsocket
,
WebsocketEvent
Modifier and Type | Optional Element and Description |
---|---|
java.lang.String |
channel
(Optional) The name of the push channel.
|