Module org.omnifaces
Package org.omnifaces.cdi

Interface PushContext

All Superinterfaces:
Serializable
All Known Implementing Classes:
SocketPushContext, SsePushContext
public interface PushContext extends Serializable

CDI interface to send a message object to the push channel as identified by @Push. This can be injected via @Push in any container managed artifact in WAR (not in EAR/EJB!). 

 @Inject @Push
 private PushContext channelName;

By default this uses Web Socket as transport. To use Server-Sent Events (SSE) instead, set Push.type() to Push.Type.SSE: 

 @Inject @Push(type=SSE)
 private PushContext channelName;

To use browser notifications via SSE, set Push.type() to Push.Type.NOTIFICATION: 

 @Inject @Push(type=NOTIFICATION)
 private PushContext channelName;

For detailed usage instructions, see Socket, Sse and Notification javadocs.

Since:
2.3
Author:
Bauke Scholtz
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    SOCKET_URI_PREFIX
    The context-relative web socket URI prefix where the endpoint should listen on.
    static final String
    SSE_URI_PREFIX
    The context-relative server sent events URI prefix where the async servlet should listen on.
    static final String
    URI_PREFIX
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use SOCKET_URI_PREFIX instead.

  • Method Summary

    Modifier and Type
    Method
    Description
    Set<Future<Void>>
    send(Object message)
    Send given message object to the push channel as identified by @Push.
    <S extends Serializable>
    Map<S,Set<Future<Void>>>
    send(Object message, Collection<S> users)
    Send given message object to the push channel as identified by @Push, targeted to the given users as identified by <o:socket user> or <o:sse user>.
    <S extends Serializable>
    Set<Future<Void>>
    send(Object message, S user)
    Send given message object to the push channel as identified by @Push, targeted to the given user as identified by <o:socket user> or <o:sse user>.

  • Field Details

    • SOCKET_URI_PREFIX

      static final String SOCKET_URI_PREFIX
      The context-relative web socket URI prefix where the endpoint should listen on.
      See Also:

    • SSE_URI_PREFIX

      static final String SSE_URI_PREFIX
      The context-relative server sent events URI prefix where the async servlet should listen on.
      See Also:

    • URI_PREFIX

      @Deprecated(since="5.2", forRemoval=true) static final String URI_PREFIX
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use SOCKET_URI_PREFIX instead.
      The context-relative web socket URI prefix where the endpoint should listen on.
      See Also:

  • Method Details

    • send

      Set<Future<Void>> send(Object message)
      Send given message object to the push channel as identified by @Push. The message object will be encoded as JSON and be available as first argument of the JavaScript listener function declared in <o:socket onmessage> or <o:sse onmessage>.
      Parameters:
      message - The push message object.
      Returns:
      The results of the send operation. If it returns an empty set, then there was no open session associated with given push channel. The returned futures will return null on Future.get() if the message was successfully delivered and otherwise throw ExecutionException.
      Throws:
      IllegalArgumentException - If given message object cannot be encoded as JSON.
      See Also:

    • send

      <S extends Serializable> Set<Future<Void>> send(Object message, S user)
      Send given message object to the push channel as identified by @Push, targeted to the given user as identified by <o:socket user> or <o:sse user>. The message object will be encoded as JSON and be available as first argument of the JavaScript listener function declared in <o:socket onmessage> or <o:sse onmessage>.
      Type Parameters:
      S - The generic type of the user identifier.
      Parameters:
      message - The push message object.
      user - The user to which the push message object must be delivered to.
      Returns:
      The results of the send operation. If it returns an empty set, then there was no open session associated with given push channel and user. The returned futures will return null on Future.get() if the message was successfully delivered and otherwise throw ExecutionException.
      Throws:
      IllegalArgumentException - If given message object cannot be encoded as JSON.
      See Also:

    • send

      <S extends Serializable> Map<S,Set<Future<Void>>> send(Object message, Collection<S> users)
      Send given message object to the push channel as identified by @Push, targeted to the given users as identified by <o:socket user> or <o:sse user>. The message object will be encoded as JSON and be available as first argument of the JavaScript listener function declared in <o:socket onmessage> or <o:sse onmessage>.
      Type Parameters:
      S - The generic type of the user identifier.
      Parameters:
      message - The push message object.
      users - The users to which the push message object must be delivered to.
      Returns:
      The results of the send operation grouped by user. If it contains an empty set, then there was no open session associated with given push channel and user. The returned futures will return null on Future.get() if the message was successfully delivered and otherwise throw ExecutionException.
      Throws:
      IllegalArgumentException - If given message object cannot be encoded as JSON.
      See Also: