Home

Tyrus 1.7 User Guide

1. 1 final ClientManager client ClientManager createClient 2 3 System getProperties put javax net debug all 4 System getProperties put SSLContextConfigurator KEY_STORE_FILE 5 System getProperties put SSLContextConfigurator TRUST_STORE_FILE 6 System getProperties put SSLContextConfigurator KEY_STORE_PASSWORD 7 System getProperties put SSLContextConfigurator TRUST_STORE_PASSWORD 8 final SSLContextConfigurator defaultConfig new SSLContextConfigurator 9 10 defaultConfig retrieve System getProperties lt or setup SSLContextConfigurator using its API 12 13 SSLEngineConfigurator sslEngineConfigurator 14 new SSLEngineConfigurator defaultConfig true false false 15 client getProperties put GrizzlyEngine SSL ENGINE CONFIGURATOR 16 sslEngineConfigurator 17 client connectToServer ClientEndpointConfig Builder create build 18 new URI wss localhost 8181 sample echo echo 19 8 2 Asynchronous connectToServer methods WebSocketContainer connectToServer methods are by definition blocking declared exceptions needs to be thrown after connection attempt is made and it returns Session instance which needs to be ready for sending messages and invoking other methods which require already estabilished connection Existing connectToServer methods are fine for lots of uses but it might cause i
2. According to the deployment algorithm classes AnnotatedEndpointOne AnnotatedEndpointTwo Programmat icEndpointOne and Programmat icEndpointTwo will be deployed AnnotatedEndpointThree and ProgrammaticEndpointThree will not be deployed as these are not returned by the respective methods of MyApplicationConfigOne nor MyApplicationConfigTwo 3 2 Deploying endpoints via javax websocket server ServerContainer Endpoints may be deployed using javax websocket server ServerContainer during the application initialization phase For websocket enabled web containers developers may obtain a reference to the ServerContainer instance by retrieving it as an attribute named javax websocket server ServerContainer on the ServletContext see the following example for annotated endpoint Example 3 2 Deployment of Annotated Endpoint Using ServerContainer 1 WebListener Deploying WebSocket Endpoints 0 JOU DU N did 12 13 14 TS 16 17 18 19 20 21 22 23 24 25 ServerEndpoint annotated public class MyServletContextListenerAnnotated implements ServletContextListen Override public void contextInitialized ServletContextEvent servletContextEvent final ServerContainer serverContainer ServerContainer servletCont getAttribute javax webso try serverContainer addEndpoint MyServletContextListenerAnnotated clas catch DeploymentException e e printSt
3. 1 public class EchoEndpointConfig implements ServerEndpointConfig 2 3 private final Map lt String Object gt userProperties new HashMap lt String Obj 4 5 Override 6 public Class lt gt getEndpointClass 7 return EchoEndpoint class 8 9 10 Override 11 public String getPath 2 return echo 13 14 15 Override 16 public List lt String gt getSubprotocols dey return Arrays asList echol echo2 18 T9 20 Override 21 public List lt Extension gt getExtensions 19 Configurations 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 return null Override public Configurator getConfigurator return null Override public List lt Class lt extends Encoder gt gt getEncoders return Arrays asList SampleEncoder class Override public List lt Class lt extends Decoder gt gt getDecoders return Arrays asList SampleDecoder class Override public Map lt String Object gt getUserProperties return userProperties To make the development easy the javax websocket server ServerEndpointConfig provides a builder to construct the configuration object Example 5 2 ServerEndpointConfigu built using Builder 1 Server 2 3 EndpointConfig config ServerEndpointConfig Builder create EchoEndpoint decoders Arrays lt Class lt extends Decoder gt gt asList
4. 13 public static Builder builder Frame frame 16 17 public final static class Builder 18 19 public Builder 20 public Builder Frame frame 21 public Frame build 22 public Builder fin boolean fin 23 public Builder rsvl boolean rsvl 24 public Builder rsv2 boolean rsv2 25 public Builder rsv3 boolean rsv3 26 public Builder mask boolean mask 27 public Builder opcode byte opcode 28 public Builder payloadLength long payloadLength 29 public Builder maskingKey int maskingKey 30 public Builder payloadData byte payloadData 1 31 Frame is immutable so if you want to create new one you need to create new builder modify what you want and build it 1 Frame newFrame Frame builder originalFrame rsvl true build Note that there is only one convenience method isControlFrame Other information about frame type etc needs to be evaluated directly from opcode simply because there might not be enough information to get the correct outcome or the information itself would not be very useful For example opcode 0x00 means continuation frame but you don t have any chance to get the information about actual type text or binary without intercepting data from previous frames Consider Frame class as raw representation as possible isControlFrame can be also gathered from opcode but it is at least always deterministic and it will be used by most
5. 1 OnMessage 2 public String echo String m 3 return m Ai The other option how to send a message is to obtain the javax websocket RemoteEndpoint instance via the javax websocket Session instance See the following example Example 6 3 Sending message via RemoteEndpoint Basic instance 1 OnMessage 2 public void echo String message Session session 3 session getBasicRemote sendText message at 6 4 RemoteEndpoint 6 4 1 The interface javax websocket RemoteEndpoint part of Java API for WebSocket is designed to represent the other end of the communication related to the endpoint so the developer uses it to send the message There are two basic interfaces the user may use javax websocket RemoteEndpoint SBasic and javax websocket RemoteEndpoint SAsync javax websocket RemoteEndpoint Basic is used to send synchronous messages The point of completion of the send is defined when all the supplied data has been written to the underlying connection The methods for sending messages on the javax websocket RemoteEndpoint Basic block until this point of completion is 22 Endpoint Lifecycle Sessions Sending Messages 6 4 2 reached except for javax websocket RemoteEndpointSBasic getSendStream and javax websocket RemoteEndpoint Basic getSendWriter which present traditional blocking I O streams to write messages See the example Sending message
6. 10 return endpointConfigs 11 12 1 3 Override 14 public Set lt Class lt gt gt getAnnotatedEndpointClasses Set lt Class lt gt gt scanned 15 all scanned endpoints will be used 16 return scanned 17 18 19 20 public class EchoEndpoint extends Endpoint Zl Override 22 public void onOpen Session session EndpointConfig config 32 Tyrus proprietary configuration 8 6 2 23 24 25 CryptoExtensionApplicationConfig will be found by servlets scanning mechanism and automatically used for application configuration no need to add anything or even have web xml Per Message Deflate Extension The original goal of whole extension support was to implement Permessage extension as defined in draft ietf hybi permessage compression 15 and we were able to achieve that goal Well not completely current implementation ignores parameters But it seems like it does not matter much it was tested with Chrome and it works fine Also it passes newest version of Autobahn test suite which includes tests for this extension see PerMessageDeflateExtension java compatible with draft ietf hybi permessage compression 15 autobahn test suite and XWebKitDeflateExtension java compatible with Chrome and Firefox same as previous just different extension name 8 7 Client reconnect If you need semi persistent client connection you can always implement some reconnect logic by yourself but Tyrus Client of
7. 18 19 20 21 22 23 24 AroundInvoke public Object manageTransaction InvocationContext ctx throws SingletonEndpoint interceptorCalled true Logger getLogger getClass getName info LOGGING return ctx proceed counter Exception 25 Chapter 8 Tyrus proprietary configuration Following settings do have influence on Tyrus behaviour and are NOT part of WebSocket specification If you are using following configurable options your application might not be easily transferable to other WebSocket API implementation 8 1 Client side SSL configuration When accessing wss URLs Tyrus client will pick up whatever keystore and truststore is actually set for current JVM instance but that might not be always convenient WebSocket API does not have this feature yet see WEBSOCKET_SPEC 210 https java net jira browse WEBSOCKET_SPEC 210 so Tyrus exposed SSLEngineConfigurator https grizzly java net docs 2 3 apidocs org glassfish grizzly ssl SSLEngineConfigurator html class from Grizzly which can be used for specifying all SSL parameters to be used with current client instance Additionally WebSocket API does not have anything like a client only WebSocketContainer and it does not have any properties so you need to use Tyrus specific class ClientManager https tyrus java net apidocs 1 7 org glassfish tyrus client ClientManager html
8. SE OER Ve NEER Res E KEES 26 8 2 Asynchronous connectToServer methods iese see see se see Se ee ee ee ee ee ee ee 26 8 3 Optimized broadcast lt i OE EA EE EE OR sedans 27 8 4 Incoming buffer SIZ sissie EES ESEG S ESE SE EG EE GR dese lag GER EE GESKREE Gees Veg Ee RE Ee ese gee ie 27 8 5 Shared client Comtaimer ss es EES ESE Eg VERSE EKS BEE ERG SEE Ke DOE REG SEE sea bes dek Gee Eg EERW 28 8 6 WebSocket Extensions esse se se ee ee ee ee ee teen ceca Se Se RR ecu Ge Ge ee ee ee ee ee 29 8 6 1 ExtendedExtension Sample sisie sorene EP ER SEKTOR PERSE DEE EDGE EE PER GEE KORE GED Ek Ee 30 8 6 2 Per Message Deflate Extension eise see see se ee ee ee ee ee ee ee ee ee ek ee 33 oet AR N EE AE RE EO ad 33 8 8 Client behind VD SA EE OR EE EE EE bey 34 8 9 IDK 7 CHENE tis ede sonst AE AE ER EE RE EE EE 34 8 9 1 SSL confisu r ti i EO EE ER N RE OR ches 35 8 10 IMEX or AA RE RE EE EE ER EE est 35 8 10 1 Configuration sies SE RE EL a ees ieee ii 37 8 11 Maximal number of open sessions on server side iese see se ee ee ence ee ee ee ee 37 lil Tyrus 1 7 User Guide 8 11 1 Maximal number of open sessions per application esse see see ee ee ke tenes 8 11 2 Maximal number of open sessions per remote address ees see ee ee se 8 11 3 Maximal number of open sessions per endpoint iv List of Tables 2 17 Tyrus cote modules EER EE Ee ER GE ean ERG sa DER DR GEE ane De
9. annotations are supported 7 1 javax inject Inject sample The following example presents how to inject a bean to the javax websocket server ServerEndpoint annotated class using javax inject Inject Class InjectedSimpleBean gets injected into class SimpleEndpoint online 15 Example 7 1 Injecting bean into javax websocket server ServerEndpoint 1 public class InjectedSimpleBean 2 3 private static final String TEXT from your server 4 5 public String getText 6 return TEXT 7 8 9 10 ServerEndpoint value simple 11 public class SimpleEndpoint T2 13 private boolean postConstructCalled false 14 15 Inject 16 InjectedSimpleBean bean 17 18 OnMessage 19 public String echo String message 20 return String format Ss s message bean getText 21 22 7 2 EJB sample The following sample presents how to turn javax websocket server ServerEndpoint annotated class into javax ejb Singleton and use interceptor on it Example 7 2 Echo sample server endpoint 1 ServerEndpoint value singleton 2 Singleton 3 Interceptors LoggingInterceptor class 24 Injection Support 14 public class SingletonEndpoint int counter 0 public static boolean interceptorCalled false OnMessage public String echo String message return interceptorCalled String format s s message 15 public class LoggingInterceptor 16 Ly
10. checkOrigin String originHeaderValue 12 Plug your own algorithm here 13 14 15 public void modifyHandshake ServerEndpointConfig sec HandshakeRequest reg 16 Plug your own algorithm here 17 18 T9 public lt T gt T getEndpointInstance Class lt T gt endpointClass throws Instantiat 20 Plug your own algorithm here 2 22 3 14 WebSocket API Endpoints Sessions and MessageHandlers 4 1 2 javax websocket ClientEndpoint The ClientEndpoint class level annotation is used to turn a POJO into WebSocket client endpoint In the following sample the client sends text message Hello and prints out each received message Example 4 6 SampleClientEndpoint 1 ClientEndpoint 2 decoders SampleDecoder class 3 encoders SampleEncoder class 4 subprotocols subprtotocoll subprotocol2 5 configurator ClientConfigurator class 6 public class SampleClientEndpoint 7 8 OnOpen 9 public void onOpen Session p 10 try 11 p getBasicRemote sendText Hello 12 catch IOException e 13 e printStackTrace 14 15 16 17 OnMessage 18 public void onMessage String message 19 System out println String format s Ss Received message messag 20 21 3 22 4 1 2 1 decoders Contains list of classes that will be used decode incoming messages for the endpoint By decoding we mean transforming from text binary websocket message to some user defined ty
11. gt org glassfish tyrus lt groupld gt lt artifactld gt tyrus container grizzly server lt artifactld gt ing artifacts Getting Started lt version gt 1 7 lt version gt lt dependency gt Let s use the very same example like for Java API for WebSocket and deploy the EchoEndpointAnnot ated on the standalone Tyrus server on the hostname localhost port 8025 and path websocket so the endpoint will be available at address ws localhost 8025 websockets echo public void runServer Server server new Server localhost 8025 websocket null EchoEndpoint try server start BufferedReader reader new BufferedReader new InputStreamReader System in System out print Please press a key to stop the server reader readLine catch Exception e e printStackTrace finally server stop Chapter 2 Tyrus Modules and Dependencies Tyrus is built assembled and installed using Maven Tyrus is deployed to maven org maven repository at the following location http search maven org Jars jar sources jar javadoc and samples are all available on the java net maven repository All Tyrus components are built using Java SE 7 compiler It means you will also need at least Java SE 7 to be able to compile and run your application Developers using maven are likely to find it easier to include and manage dependencies of their applications than developers usin
12. resource to respond to a request based on the substituted URI Variables are denoted by curly braces For example look at the following ServerEndpoint annotation ServerEndpoint users username In this type of example a user will be prompted to enter their name and then a Tyrus web service configured to respond to requests to this URI path template will respond For example if the user entered their username as Galileo the web service will respond to the following URL http example com users Galileo To obtain the value of the username variable the javax websocket server PathParam may be used on method parameter of methods annotated with one of OnOpen OnMessage OnError OnClose Example 4 3 Specifying URI path parameter 1 ServerEndpoint users username 2 public class UserEndpoint 3 OnMessage public String getUser String message PathParam username String userNa OO J OU Hs 4 1 1 2 decoders Contains list of classes that will be used to decode incoming messages for the endpoint By decoding we mean transforming from text binary websocket message to some user defined type Each decoder needs to implement the Decoder interface 12 WebSocket API Endpoints Sessions and MessageHandlers SampleDecoder in the following example decodes String message and produces SampleType message see decode method on line 4 Example 4 4 SampleDecoder 1 public clas
13. se se ee Se ee ee ee ee ee 16 4 9 OnError with Session and Throwable parameters sees ee see see ee ee Se Ge Se Re ke ee ke ee 17 4 10 OnError with Session and Throwable parameters esse ee ee ee ee ee teen seen sean ee 17 4 11 M ssageHandler basic example ESE SEER GR ss PR ee santa sn GO GER GE ge n aa 17 5 1 Configuration for EchoEndpoint Deployment eise see see cece cece eee Se de ee de ee ee ee 19 5 2 ServerEndpointConfigu built using Builder iese se se ee ee ee ee ee Se cece AS Re Ge ke ke ee 20 5 3 ClientEndpointConfig built using Builder iese se se Sek Se Se ence ee ee ee ee ee ge ek ee 20 6 1 Lifecycle echo sample ER EER EE EED RO EE cc 21 6 2 Sending message in OnMessage iese se ek Se Se Se ee ee ee ee ee de eens eeu Re ke ee ke ee 22 6 3 Sending message via RemoteEndpoint Basic instance iis see see se se ee ee ee ee ee ee 22 6 4 Method for sending partial text message iese see se Se Se ee ee ee ee ee ee seen Se sean ee ee 23 6 5 Sending mesage the async way using Future iese se ee ee ee ee ee ee ceca cece een Re Ge ke ee ke ee 23 7 1 Injecting bean into javax websocket server ServerEndpoint iese sees see sees 24 1 2 Echo sainple server Endpoints oes EES cose DEE Ee AG DR DE SEER ER EE EE GE Oe RE Ge be DER basse ee Ep ER Did 24 vi Preface This is user guide for Tyrus 1 7 We are trying to keep it up to date as we add new features Please use als
14. tyrus spi tyrus websocket core org 9 Tyrus tyrus spi http search maven artifactdetails org glassfish t tyrus spil1 7 jar nothing org yrusl SPI Table 2 2 Tyrus containers Module Dependencies Description tyrus container glassfish cdi http search maven artifactdetails org glassfish t tyrus container glassfish cdil 1 7ljar tyrus spi org yrusl CDI support tyrus container glassfish ejb http search maven org glassfish t tyrus container tyrus spi jorg artifactdetails yrusl EJB support Tyrus Modules and Dependencies Module Dependencies Description glassfish ejbl 1 7ljar tyrus container grizzly http search maven artifactdetails org glassfish t tyrus container grizzlyl1 7 jar tyrus core tyrus spi tyrus websocket core org yrusl Grizzly integration for Tyrus client and standalone server usage tyrus container servlet http search maven org glassfish t tyrus container servletl1 7 bundle tyrus server tyrus core tyrus spi tyrus websocket core jorg artifactdetails yrusl Servlet support for integration into web containers Chapter 3 Deploying WebSocket Endpoints Deploying WebSocket endpoints can be done in two ways Either deploying via putting the endpoint in the W
15. via RemoteEndpoint Basic instance to see how the whole text message is send The following example demonstrates a method which sends the partial text method to the peer Example 6 4 Method for sending partial text message 1 public void sendPartialTextMessage String message Boolean isLast Session ses 2 try 3 session getBasicRemote sendText message isLast 4 catch IOException e 5 e printStackTrace 6 ke javax websocket RemoteEndpoint Async This representation of the peer of a web socket conversation has the ability to send messages asynchronously The point of completion of the send is defined when all the supplied data has been written to the underlying connection The completion handlers for the asynchronous methods are always called with a different thread from that which initiated the send Example 6 5 Sending mesage the async way using Future 1 public void sendWholeAsyncMessage String message Session session 2 Future lt Void gt future session getAsyncRemote sendText message 3 23 Chapter 7 Injection Support As required in Java API for WebSocket Tyrus supports full field method and constructor injection using javax inject Inject into all websocket endpoint classes as well as the use of the interceptors on these classes Except this Tyrus also supports some of the EJB annotations Currently javax ejb Stateful javax ejb Singletonand javax ejb Stateless
16. AR file or using the ServerContainer methods to deploy the programmatic endpoint in the deployment phase 3 1 Deploying Endpoints as a WAR file The classes that are scanned for in WAR are the following ones e Classes that implement the javax websocket ServerApplicationConfig e Classes annotated with javax websocket server ServerEndpoint e Classes that extend javax websocket 3 1 1 Deployment Algorithm Endpoint 1 If one or more classes implementing ServerApplicationConfiguration are present in the WAR file Tyrus deploys endpoints provided by all of these classes Tyrus doesn t deploy any other classes present in the WAR annotated by javax websocket server ServerEndpoint orextending javax websocket Endpoint 2 If no class implementing ServerApplicationConfiguration is present Tyrus deploys all classes annotated with ServerEndpoint or extending Endpoint present in the WAR Let s have the following classes in the WAR Example 3 1 Deployment of WAR containing several classes extending javax websocket server ServerApplicationConfig 1 2 3 4 3 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 public class public Se yApplicationCo t lt ServerEndpoin Set lt Class lt extends s add retur public Se n Ss t lt Class gt getAnnotated nfigOne impl tConfig gt get Endpoint gt gt s ProgrammaticEndpointOne class ments ServerApplicationConfig
17. Client 2 private static CountDownLatch messageLatch 3 private static final String SENT_MESSAGE Hello World 4 5 public static void main String args 6 try 7 messageLatch new CountDownLatch 1 8 9 final ClientEndpointConfig cec ClientEndpointConfig Builder crea 10 11 ClientManager client ClientManager createClient 12 Client connectToServer new Endpoint 13 14 Override 15 public void onOpen Session session EndpointConfig config 16 try 17 session addMessageHandler new MessageHandler Whole lt Str 18 19 Override 20 public void onMessage String message 21 System out println Received message messag 22 messageLatch countDown 23 24 H 25 session getBasicRemote sendText SENT MESSAGE 26 catch IOException e 21 e printStackTrace 28 29 30 cec new URI ws localhost 8025 websockets echo 31 messageLatch await 100 TimeUnit SECONDS 32 catch Exception e Getting Started 1 1 3 1 1 4 33 e printStackTrace 34 35 36 Creating Server Endpoint Programmatically Similarly to Client Endpoint the server registered endpoint may also be the programmatic one Example 1 3 Programmatic Echo Endpoint 1 public class EchoEndpointProgrammatic extends Endpoint 2 Override 3 public void onOpen final Session session EndpointConfig config 4 session addMessageHandler new MessageHandler Who
18. EndpointConfigs Set lt Class lt extends m EN new HashSet lt Class lt extends Endpoin EndpointClasses Set lt Class lt gt gt scanned Set lt Class lt gt gt s new HashSet lt Class lt gt gt s add retur n Ss public class MyApplicationCo public Set lt ServerEndpoin Set lt Class lt extends s add return Ss tConfig gt get Endpoint gt gt s AnnotatedEndpointOne class nfigIwo implements ServerApplicationConfig EndpointConfigs Set lt Class lt extends m EN new HashSet lt Class lt extends Endpoin ProgrammaticEndpointTwo class Deploying WebSocket Endpoints 21 22 public Set lt Class gt getAnnotatedEndpointClasses Set lt Class lt gt gt scanned 23 Set lt Class lt gt gt s new HashSet lt Class lt gt gt 24 s add AnnotatedEndpointTwo class 25 return s 26 BT 28 29 ServerEndpoint value annotatedone 30 public class AnnotatedEndpointOne 31 32 5 33 34 ServerEndpoint value annotatedtwo 35 public class AnnotatedEndpointTwo 36 ST sh 38 39 ServerEndpoint value annotatedthree 40 public class AnnotatedEndpointThree 41 42 43 44 public class ProgrammaticEndpointOne extends Endpoint 45 46 47 48 public class ProgrammaticEndpointTwo extends Endpoint 49 50 51 52 public class ProgrammaticEndpointThree extends Endpoint 53 54
19. JsonDecoder class encoders Arrays lt Class lt extends Encoder gt gt asList JsonEncoder class build 5 2 javax websocket ClientEndpointConfig The javax websocket Client client endpoint via registering the programmatic endpoint instance which is javax websocket Client Some of the configuration methods come from the EndpointC EndpointConfig is used when deploying the programmatic at the WebSocketContainer onfigclass extended by both javax websocket server ServerEndpointConfig and EndpointConfig Then there are methods for configuring the preferred subprotocols the client endpoint wants to use and supported extensions It is also possible to use the ClientEndpointConfig Configurator in order to be able to affect the endpoint behaviour before and after request Similarly to the ServerEndpointConfig there is a Builder provided to construct the configuration easily Example 5 3 ClientEndpointConfig built using Builder 1 2 3 4 ClientEndpointConfig Builder create decoders Arrays lt Class lt extends Decoder gt gt asList JsonDecoder class encoders Arrays lt Class lt extends Encoder gt gt asList Json Encoder class preferredSubprotocols Arrays asList echol echo2 build 20 Chapter 6 Endpoint Lifecycle Sessions Sending Messages 6 1 Endpoint Lifecycle AS mentioned before the endpoint in Java API for WebSocket is repr
20. Tyrus 1 7 User Guide Tyrus 1 7 User Guide Table of Contents SERE N EE RE EE N ME ER Ed N vii Ty Getting Started erines e EE EE EE OE OE OR EN 1 1 1 WebSocket Services Using Java API for WebSocket 00 0 0 cece ee ee ee ee ee ee ee 1 1 1 1 Creating Annotated Server Endpoint esse sesse see see see ee ee ee seen sean ee eens 1 1 12 Client Endpomt ascitis ita sates 2 1 1 3 Creating Server Endpoint Programmatically 2 0 0 0 see see ss ee ee ee ee teen seen ee 3 1 14 Tyrus in Standalone Mode iss EES EE RE EERS EERS Ee EDE ELE TAES ORE ESI PERIERE PIERRE ESR 3 2 Tyrus Modules and Dependencies cece cece cece ee ee ee seen seca Ge sean GR eeu Ge ke ee ee ee ee 5 3 Deploying WebSocket Endpoint sis Er EE ie NESER si sen dese ESE GE GR ESE EK Bee gos EGGO GESE sa GO Ge nero ed 8 3 1 Deploying Endpoints as a WAR file ese see see see see ge Se ee ek een ee ee ee ee ee 8 3 1 1 Deployment Algorithm i s 08 03 KERSE ER ER ESE KORE GER GEE ERG EG ESE EE ROES DE be Ge EESTE PER De ged 8 3 2 Deploying endpoints via javax websocket server ServerContainer 9 4 WebSocket API Endpoints Sessions and MessageHandlers see ese see ss ee see see see seca ek scans 11 4 1 Endpoint Classes 2 OER ER ER EE ER vec idgetesin oes 11 4 1 1 javax websocket server ServerEndpoint esse ss ee ss ee ss eee ee se ee see een ee ke ee ke ee ke ee 11 4 1 2 javax websocket ClientE
21. ackTrace OnMessage public String onMessage String message return message Override public void contextDestroyed ServletContextEvent servletContextEvent 10 Chapter 4 WebSocket API Endpoints Sessions and MessageHandlers This chapter presents an overview of the core WebSocket API concepts endpoints configurations and message handlers The JAVA API for WebSocket specification draft can be found online here http jcp org aboutJava communityprocess pfd jsr356 index html 4 1 Endpoint Classes Server endpoint classes are POJOs Plain Old Java Objects that are annotated with javax websocket server ServerEndpoint Similarly client endpoint classes are POJOs annotated with javax websocket ClientEndpoint This section shows how to use Tyrus to annotate Java objects to create WebSocket web services The following code example is a simple example of a WebSocket endpoint using annotations The example code shown here is from echo sample which ships with Tyrus Example 4 1 Echo sample server endpoint 1 ServerEndpoint echo 2 public class EchoEndpoint 3 4 OnOpen 5 public void onOpen Session session throws IOException 6 session getBasicRemote sendText onOpen i 8 9 OnMessage 10 public String echo String message 11 return message from your server 12 13 14 OnError 15 public void onError Throwable t 16 t printStac
22. ageHandler new MessageHandler Whole lt String gt 6 Override 7 public void onMessage String message 17 WebSocket API Endpoints Sessions and MessageHandlers 8 System out println Received message message 9 10 11 L2 There are two orthogonal criterions which classify MessageHandlers According the WebSocket Protocol RFC 6455 the message may be sent either complete or in chunks In Java API for WebSocket this fact is reflected by the interface which the handler implements Whole messages are processed by handler which implements javax websocket MessageHandler Whole interface Partial messages are processed by handlers that implement javax websocket MessageHandler Partial interface However if user registers just the whole message handler it doesn t mean that the handler will process solely whole messages If partial message is received the parts are cached by Tyrus until the final part is received Then the whole message is passed to the handler Similarly if the user registers just the partial message handler and whole message is received it is passed directly to the handler The second criterion is the data type of the message WebSocket Protocol RFC 6455 defines four message data type text message According to Java API for WebSocket the text messages will be processed by MessageHandlers with the following types e java lang String e java io Reader e any developer object for w
23. allowed This example will set maximal number of open sessions per whole application to 500 lt web app version 2 5 xmlns http java sun com xml ns javaee xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http java sun com xml ns javaee http java sun com lt context param gt lt param name gt org glassfish tyrus maxSessionsPerApp lt param name gt lt param value gt 500 lt param value gt lt context param gt lt web app gt 8 11 2 Maximal number of open sessions per remote address The number of open sessions per remote address can be configured by setting property org glassfish tyrus maxSessionsPerRemoteAddr Property can be used as lt context param gt in web xml or as an entry in parameter map in standalone Server properties Remote address value is obtained from ServletRequest getRemoteAddr http docs oracle com javaee 6 api javax servlet ServletRequest html getRemoteAddr or its alternative when using Grizzly server implementation Beware that this method returns always the last node which sending HTTP request so all clients behind one proxy will be treated as clients from single remote address Note that only positive integer is allowed This example will set maximal number of open sessions from unique IP address or last proxy to 5 38 Tyrus proprietary configuration lt web app version 2 5 xmlns http java sun com xml ns javaee xmlns xsi http xsi schemaL
24. and accessing some runtime properties and metrics at the server side using JMX Java management extension technology The monitoring API has been available since version 1 6 and the following properties are available at runtime through MXBeans Number of open sessions maximal number of open session since the start of monitoring and list of deployed endpoint class names and paths are available for each application Endpoint class name and path the endpoint is registered on number of open session and maximal number of open sessions are available for each endpoint Apart from that message as well as error statistics are collected both per application and per individual endpoint The following message statistics are monitored for both sent and received messages 35 Tyrus proprietary configuration e messages count e messages count per second e average message size e smallest message size e largest message size Moreover all of them are collected separately for text binary and control messages and apart from the statistics being available for the three separate categories total numbers summing up statistics from the three types of messages are also available As has been already mentioned above Tyrus also monitors errors on both application and endpoint level An error is identified by the Throwable class name that has been thrown Statistics are collected about number of times each Throwable has been thrown so a list of errors toge
25. annotated endpoint or programmatic endpoint By annotated endpoint we mean endpoint constructed by using annotations javax websocket server ServerEndpoint for server endpoint and javax websocket ClientEndpoint for client endpoint like in Annotated Echo Endpoint Example 1 1 Annotated Echo Endpoint 1 ServerEndpoint value echo 2 public class EchoEndpointAnnotated 3 OnMessage public String onMessage String message Session session 4 5 return message 6 7 8 The functionality of the EchoEndpointAnnotated is fairly simple to send the received message back to the sender To turn a POJO Plain Old Java Object to WebSocket server endpoint the annotation ServerEndpoint value echo needs to be put on the POJO see line 1 The URI path of the endpoint is echo The annotation OnMessage line 3 on the method public String onMessage String message Session session indicates that this method will be called whenever text message is received On line 5 in this method the message is sent back to the user by returning it from the message The application containing only the E choEndpointAnnot ated class can be deployed to the container Getting Started 1 1 2 Client Endpoint Let s create the client part of the application The client part may be written in JavaScript or any other technology supporting WebSockets We will use Java API for WebSocke
26. e Ge abate Ge Ee De Ge GR Reg 2 2 TYTUS COMLAMETS Es ES ESE Ge Ge PANS AR EE Wb GE Ee GR EEE is List of Examples 1 1Anniotated Echo Endpoint id ses or ee RS GE GR DOE veda A Re Dee ee GE Ee HE GE Ge atta ssa eed 1 12 Chent STE RE OR EE RE EO RE 2 1 3 Programmatic Echo Endpoint sie EE EER Ses ss ER SEE ROES GEE EE RE GER Ee DR ses EER GE EDE EES ER EE EER EN GED Ee SAG Ee PERD 3 3 1 Deployment of WAR containing several classes extending javax websocket server ServerApplicationConfidg oo eee eee se se se ee se se se see 8 3 2 Deployment of Annotated Endpoint Using ServerContainer sessies sees see see see ee ee ence ee ee 9 41 Echo sample server endpoint ss es EERS BAR ERENS ES EE RES EG READ SE Se GR EG EP ER Ee GE GR EES GE OG ER Ge Ee PERS 11 4 2 javax websocket server ServerEndpoint with all fields specified 2 0 0 0 see see see se Se ee ee 12 4 3 Specifying URI path parameter sea ore AE SEE sa ESE ES EE EE ESE REG riera bos sabes GEGEE ses iva 12 44 SimpleDecoder si SEDES BEE GE DE GE ti 13 45 SampleEncoder Ese EE DEE SERS SS SEER GEE VOER GEE EE DERS GER ER EE iaa GER OE Re BE KEEP ER NEE DERE eg 13 4 6 SampleChentEnd point ii sie se EES cesta Ee ees Age RE ie bok coe vege ced DE ees ardid vd See Eed SEAN EE dees DA ge oi 15 4 7 OnOpen with Session and EndpointConfig parameters siese ss ee see see see ee eee Se ee ee 16 4 8 OnClose with Session and CloseReason parameters iese see
27. e frame 14 if frame isControlFrame amp amp frame getOpcode 0x02 15 final bytel payloadData frame getPayloadData 16 payloadData 0 Byte context getProperties get key 17 18 return Frame builder frame payloadData payloadData build 19 else 20 return frame 21 22 23 24 Override 25 public List onExtensionNegotiation ExtensionContext context 26 List requestedParameters 27 init context 28 no params 2 9 return null 30 31 32 Override 33 public void onHandshakeResponse ExtensionContext context 34 List responseParameters 35 init context 36 37 38 private void init ExtensionContext context 39 context getProperties put key byte 0x55 40 41 42 Override 43 public void destroy ExtensionContext context 44 context getProperties clear 45 46 47 Override 48 public String getName 49 return lame crypto extension 50 51 52 Override 53 public List getParameters 54 no params 31 Tyrus proprietary configuration ele 56 Iy return null You can see that ExtendedExtension is slightly more complicated that original Extension so the implementation has to be also not as straightforward on the other hand it does something Sample code above shows possible simplification mentioned earlier one process method will be enough but please take this as just sample implementation Real world case is usually more complica
28. entContainer SHARED_CONTAINER_IDLE_TIMEOU Last but not least you might want to specify thread pool sizes used by shared container please use this feature only when you do know what are you doing Grizzly by default does not limit max number of used threads so if you do that please make sure thread pool size fits your purpose 1 client getProperties put GrizzlyClientSocket SELECTOR THREAD POOL CONFIG Th 2 client getProperties put GrizzlyClientSocket WORKER THREAD POOL CONFIG Thre T 28 Tyrus proprietary configuration 8 6 WebSocket Extensions Please note that Extensions support is considered to be experimental and any API can be changed anytime Also you should ask yourself at least twice whether you don t want to achieve your goal by other means WebSocket Extension is very powerful and can easily break your application when not used with care or enough expertise WebSocket frame used in ExtendedExtension public class Frame 1 2 3 public boolean isFin 4 public boolean isRsvl 5 public boolean isRsv2 6 public boolean isRsv3 7 public boolean isMask 8 public byte getOpcode 9 public long getPayloadLength 10 public int getMaskingKey 11 public byte getPayloadData 12 public boolean isControlFrame 13 14 public static Builder builder
29. esented either by instance of javax websocket Endpoint or by class annotated with either javax websocket server ServerEndpoint or javax websocket ClientEndpoint Unless otherwise defined by developer provided configurator defined in instance of javax websocket server ServerEndpointConfig or javax websocket ClientEndpointConfig Tyrus uses one endpoint instance per VM per connected peer Therefore one endpoint instance typically handles connections from one peer 6 2 javax websocket Session The sequence of interactions between an endpoint instance and remote peer is in Java API for WebSocket modelled by javax websocket Session instance This interaction starts by mandatory open notification continues by O n websocket messages and is finished by mandatory closing notification The javax websocket Session instance is passed by Tyrus to the user in the following methods for programmatic endpoints e public void onOpen Session session EndpointConfig config e public void onClose Session session CloseReason closeReason e public void onError Session session Throwable thr The javax websocket Session instance is passed by Tyrus to the user in the methods annotated by following annotations for annotated endpoints e method annotated with javax websocket OnOpen e method annotated with javax websocket OnMessag e method annotated with javax websocket OnClose e method annotated wi
30. fers useful feature which should be much easier to use See short sample code 1 ClientManager client ClientManager createClient 2 ClientManager ReconnectHandler reconnectHandler new ClientManager ReconnectH 3 4 private int counter 0 5 6 Override 7 public boolean onDisconnect CloseReason closeReason 8 counter 9 if counter lt 3 10 System out printin Reconnecting reconnect count counter 11 return true 12 else 1 3 return false 14 15 16 17 Override 18 public boolean onConnectFailure Exception exception 19 counter 20 if counter lt 3 21 System out printin Reconnecting reconnect count counter 22 23 Thread sleep or something other sleep like expression can be p 24 to do it here to avoid potential DDoS when you don t limit number of 29 return true 26 else 27 return false 28 29 33 Tyrus proprietary configuration 30 31 32 client getProperties put ClientManager RECONNECT_HANDLER reconnectHandler 33 34 client connectToServer As you can see ReconnectHandler contains two methods onDisconnect and onConnectFailure First will be executed whenever OnClose annotated method or Endpoint onClose is executed on client side this should happen when established connection is lost for any reason You can find the reason in methods parameter Other one called onCo
31. g ant or other build technologies The following table provides an overview of all Tyrus modules and their dependencies with links to the respective binaries Table 2 1 Tyrus core modules Module Dependencies Description tyrus server tyrus core tyrus spi tyrus Basic server functionality http websocket core search maven org artifactdetails org glassfish tyrus tyrus serverl 1 7ljar tyrus core tyrus spi tyrus websocket core Core Tyrus functionality http search maven org artifactdetails org glassfish tyrus tyrus corel 1 7ljar tyrus client tyrus core tyrus spi tyrus Basic client functionality http websocket core search maven org artifactdetails org glassfish tyrus tyrus clientl 1 7ljar tyrus nothing Project documentation documentation http search maven org artifactdetails org glassfish tyrus tyrus documentation 1 7ljar tyrus nothing The WebSocket protocol websocket core http Tyrus Modules and Dependencies Module Dependencies Description search maven org artifactdetails org glassfish tyrus tyrus websocket corell 7ljar tyrus tyrus server tyrus client tyrus Samples of using Java API for WebSocket and samples http search maven remotecontent filepath org glassfish tyrus bundles tyrus samples 1 7 tyrus samples 1 7 all zip container grizzly tyrus core
32. h WebSocket protocol process ExtensionContext Frame is always invoked with unmasked frame you don t need to care about it On the other side payload is as it was received from the wire before any validation UTF 8 check for text messages This fact is particularly important when you are modifying text message content you need to make sure it is properly encoded in relation to other messages because encoding decoding process is stateful remainder after UTF 8 coding is used as input to coding process for next message If you want just test this feature and save yourself some headaches don t modify text message content or try binary messages instead 8 6 1 ExtendedExtension sample Let s say we want to create extension which will encrypt and decrypt first byte of every binary message Assume we have a key one byte and our symmetrical cipher will be XOR Just for simplicity a XOR key XOR key a so encrypt and decrypt functions are the same 30 Tyrus proprietary configuration 1 public class CryptoExtension implements ExtendedExtension 2 3 Override 4 public Frame processIncoming ExtensionContext context Frame frame 5 return lameCrypt context frame 6 7 8 Override 9 public Frame processOutgoing ExtensionContext context Frame frame 10 return lameCrypt context frame 11 12 13 private Frame lameCrypt ExtensionContext context Fram
33. hich there is a corresponding javax websocket Decoder Text or javax websocket Decoder TextStream The binary messages will be processed by MessageHandlers with the following types e java nio ByteBuffer e java io InputStream e any developer object for which there is a corresponding javax websocket Decoder Binary or javax websocket Decoder BinaryStream The Java API for WebSocket limits the registration of MessageHandlers per Session to be one MessageHandler per native websocket message type In other words the developer can only register at most one MessageHandler for incoming text messages one MessageHandler for incoming binary messages and one MessageHandler for incoming pong messages This rule holds for both whole and partial message handlers i e there may be one text MessageHandler either whole or partial not both 18 Chapter 5 Configurations javax websocket server ServerEndpointConfig and javax websocket ClientEndpointConfig objects are used to provide the user the ability to configure websocket endpoints Both server and client endpoints have some part of configuration in common namely encoders decoders and user properties The user properties may developers use to store the application specific data For the developer s convenience the builders are provided for both ServerEndpointConfig and ClientEndpointConfig 5 1 javax websocket server ServerEndpointCon The javax websocket server ServerEnd
34. ich represents the passed configuration object Note that the EndpointConfig allows the user to access the user properties Example 4 7 OnOpen with Session and EndpointConfig parameters 1 ServerEndpoint sample 2 public class EchoEndpoint 3 4 private Map lt String Object gt properties 5 6 OnOpen 7 public void onOpen Session session EndpointConfig config throws IOExcept 8 session getBasicRemote sendText onOpen 9 properties config getUserProperties 10 11 OnClose This annotation may be used on any method of ServerEndpoint or ClientEndpoint but only once per endpoint It is used to decorate a method which is called once the connection is being closed The method may have one Session parameter one CloseReason parameter and parameters annotated with PathParam Example 4 8 OnClose with Session and CloseReason parameters ServerEndpoint sample public class EchoEndpoint 1 2 3 4 OnClose 5 public void onClose Session session CloseReason reason throws IOExceptio 6 7 8 prepare the endpoint for closing 16 WebSocket API Endpoints Sessions and MessageHandlers 4 2 3 OnError This annotation may be used on any method of ServerEndpoint or ClientEndpoint but only once per endpoint It is used to decorate a method which is called once Exception is being thrown by any method annotated with OnOpen OnMessage and OnC
35. ill result in Grizzly client being used There is also an option how to use JDK client with the standard Websocket API 1 2 final WebSocketContainer client ContainerProvider getWebSocketContainer 3 34 Tyrus proprietary configuration 8 9 1 8 10 The code listed above will scan class path for Websocket client implementations A slight problem with this approach is that if there is more than one client on the classpath the first one discovered will be used Therefore if you intend to use JDK client with the standard API you have to make sure that there is not a Grizzly client on the classpath as it might be used instead The main reason why JDK client has been implemented is that it does not have any extra dependencies except JDK 7 and of course some other Tyrus modules which makes it considerable more lightweight compared to Tyrus Grizzly client which requires 1 4 MB of dependencies It is also important to note that the JDK client has been implemented in a way similar to Grizzly client shared container option which means that there is one thread pool shared among all clients Proxy configuration for JDK client is the same as for Grizzly client shown above SSL configuration Alike in case of Grizzly client accessing wss URLs will cause Tyrus client to pick up whatever keystore and truststore is actually set for the current JVM instance However specifying SSL parameters to be used with JDK client instance i
36. ithout the need to care about this property Same issue is present on client side There you can set this property via ClientManager 1 ClientManager client ClientManager createClient 2 client getProperties put org glassfish tyrus incomingBufferSize 6000000 3 client connectToServer 8 5 Shared client container By default WebSocket client implementation in Tyrus re creates client runtime whenever WebSocketContainer connectToServer is invoked This approach gives us some perks like out of the box isolation and relatively low thread count currently we have 1 selector thread and 2 worker threads Also it gives you the ability to stop the client runtime one Session instance is tied to exactly one client runtime so we can stop it when Session is closed This seems as a good solution for most of WebSocket client use cases you usually use java client from application which uses it for communicating with server side and you typically don t need more than 10 instances my personal estimate is that more than 90 applications won t use more than connection There are several reasons for it of it is just a client it needs to preserve server resources one WebSocket connection means one TCP connection and we don t really want clients to consume more than needed Previous statement may be invalidated by WebSocket multiplexing extension but for now it is still valid On the other hand WebSocket client i
37. kTrace j 17 18 19 OnClose 20 public void onClose Session session 21 22 23 Let s explain the JAVA API for WebSocket annotations 4 1 1 javax websocket server ServerEndpoint javax websocket server ServerEndpoint has got one mandatory field value and four optional fields See the example below 11 WebSocket API Endpoints Sessions and MessageHandlers Example 4 2 javax websocket server ServerEndpoint with all fields specified 1 ServerEndpoint 2 value sample 3 decoders ChatDecoder class 4 encoders DisconnectResponseEncoder class 5 subprotocols subprtotocoll subprotocol2 6 configurator Configurator class 7 8 public class SampleEndpoint 9 10 OnMessage 11 public SampleResponse receiveMessage SampleType message Session session 12 return new SampleResponse message 13 14 4 1 1 1 value Denotes a relative URI path at which the server endpoint will be deployed In the example javax websocket server ServerEndpoint with all fields specified the Java class will be hosted at the URI path samp1e The field value must begin with a and may or may not end in a it makes no difference Thus request URLs that end or do not end in a will both be matched WebSocket API for JAVA supports level 1 URI templates URI path templates are URIs with variables embedded within the URI syntax These variables are substituted at runtime in order for a
38. l monitoring can be enabled on Grizzly server 1 2 serverProperties put ApplicationEventListener APPLICATION_ EV ENT_LIST EN ER 3 Similarly endpoint level monitoring can be enabled on Grizzly server in the following way 1 2 serverProperties put ApplicationEventListener APPLICATION_ BV ENT LIST EN ER 3 Monitoring can be configured on Glassfish in web xml and the following code sample shows endpoint level configuration new new lt web app version 2 5 xmlns http java sun com xml ns javaee xmlns xsi ht xsi schemaLocation http java sun com xml ns javaee http lt context param gt EventListen lt param value gt org glassfish tyrus ext monitoring jmx SessionlessApplica lt context param gt lt web app gt 1 2 3 4 5 lt param name gt org glassfish tyrus core monitoring Application 6 7 8 9 Similarly session level monitoring can be configured on Glassfish in web xml in the following way lt web app version 2 5 xmlns http java sun com xml ns javaee xmlns xsi ht xsi schemaLocation http java sun com xml ns javaee http lt context param gt EventListen lt param value gt org glassfish tyrus ext monitoring jmx SessionAwareApplic lt context param gt lt web app gt 8 11 Maximal number of open sessions on server side 1 2 3 4 5 lt param name gt org glassfish tyru
39. le lt String gt 5 Override 6 public void onMessage String message 7 try 8 session getBasicRemote sendText message 9 catch IOException e 10 e printStackTrace 11 12 13 14 155 The functionality of the EchoEndpoint Programmatic is fairly simple to send the received message back to the sender The programmatic server endpoint needs to extend javax websocket Endpoint line 1 Mehod public void onOpen final Session session Endpoi ntConfig config gets called once new connection to this endpoin0t is opened In this method the MessageHandler is registered to the javax websocket Session instance which opened the connection Method public void onMessage String message gets called once the message is received On line 8 the message is sent back to the sender To see how both annotated and programmatic endpoints may be deployed please check the section Deployment In short you need to put the server endpoint classes into WAR deploy on server and the endpoints will be scanned by server and deployed Tyrus in Standalone Mode To use Tyrus in standalone mode it is necessary to depend on correct Tyrus artifacts The follow need to be added to your pom to use Tyrus lt dependency gt lt groupId gt org glassfish tyrus lt groupld gt lt artifactId gt tyrus server lt artifactId gt lt version gt 1 7 lt version gt lt dependency gt lt dependency gt lt groupId
40. lose The method may have optional Session parameter and Throwable parameters Example 4 9 OnError with Session and Throwable parameters 1 ServerEndpoint sample 2 public class EchoEndpoint 3 4 OnError 5 public void onError Session session 6 t printStackTrace j 7 8 4 2 4 OnMessage Throwable t This annotation may be used on certain methods of ServerEndpoint or ClientEndpoint but only once per endpoint It is used to decorate a method which is called once new message is received Example 4 10 OnError with Session and Throwable parameters 1 ServerEndpoint sample String message 2 public class EchoEndpoint 3 4 OnMessage 5 public void onMessage Session session 6 System out println Received message message 7 8 4 3 MessageHandlers Implementing the javax websocket MessageHandler interface is one of the ways how to receive messages on endpoints both server and client It is aimed primarily on programmatic endpoints as the annotated ones use the method level annotation javax websocket OnMessage to denote the method which receives messages The MessageHandlers get registered on the Session instance Example 4 11 MessageHandler basic example 1 public class MyEndpoint extends Endpoint 2 3 Override 4 public void onOpen Session session EndpointConfig EndpointConfig 5 session addMess
41. mentation of ServerEndpointConfiguration Configurator It allows them to control some algorithms used by Tyrus in the connection initialization phase e public String getNegotiatedSubprotocol List lt String gt supported List lt String gt requested allows the user to provide their own algorithm for selection of used subprotocol public List lt Extension gt getNegotiatedExtensions List lt Extension gt installed List lt Extension gt requested allows the user to provide their own algorithm for selection of used Extensions e public boolean checkOrigin String originHeaderValue allows the user to specify the origin checking algorithm e public void modifyHandshake ServerEndpointConfig sec HandshakeRequest request HandshakeResponse response allows the user to modify the handshake response that will be sent back to the client e public lt T gt T getEndpointInstance Class lt T gt endpointClass throws InstantiationException allows the user to provide the way how the instance of an Endpoint is created 1 public class ConfiguratorTest extends ServerEndpointConfig Configurator 2 3 public String getNegotiatedSubprotocol List lt String gt supported List lt String 4 Plug your own algorithm here 5 6 7 public List lt Extension gt getNegotiatedExtensions List lt Extension gt installed 8 Plug your own algorithm here 9 10 11 public boolean
42. mplementations in some other containers took another also correct approach they share client runtime for creating all client connections That means they might not have this strict one session one runtime policy they cannot really give user way how he to control system resources but surely it has another advantage it can handle much more opened connections Thread pools are share among client sessions which may or may not have some unforeseen consequences but if its implemented correctly it should outperform Tyrus solution mentioned in previous paragraph in some use cases like the one mentioned in TYRUS 275 https java net jira browse TY RUS 275 performance tests Reporter created simple program which used WebSocket API to create clients and connect to remote endpoint and he measured how many clients can he create or in other words how many parallel client connections can be created I guess that original test case is to measure possible number of concurrent clients on server side but that does not really matter for this post Tyrus implementation loose compared to some other and it was exactly because it did not have shared client runtime capability How can you use this feature 1 ClientManager client ClientManager createClient 2 3 client getProperties put GrizzlyClientContainer SHARED_CONTAINER true You might also want to specify container idle timeout 1 client getProperties put GrizzlyCli
43. n method is invoked and on client side onHandshakeResponse Server side method is a must client side could be somehow solved by implementing ClientEndpointConfig Configurator afterResponse or calling Session getNegotiatedExtenions but it won t be as easy to get this information back to extension instance and even if it was it won t be very elegant Also you might suggest replacing processIncoming and processOutgoing methods by just oneprocess Frame method That is also possible but then you might have to assume current direction from frame instance or somehow from ExtensionContext which is generally not a bad idea but it resulted it slightly less readable code ExtensionContext and related lifecycle method is there because original javax websocket Extension is singleton and ExtendedExtension must obey this fact But it does not meet some requirements we stated previously like per connection parameter negotiation and of course processing itself will most likely have some connection state Lifecycle of ExtensionContext is defined as follows ExtensionContext instance is created right before onExtensionNegotiation server side or onHandshakeResponse client side and destroyed after destroy method invocation Obviously processIncoming or processOutgoing cannot be called before ExtensionContext is created or after is destroyed You can think of handshake related methods as OnOpenand destroy as OnClose For those more familiar wit
44. ndpoint esse see see see see see Se Se Se Se ee ee ee ee 15 4 2 Endpoint method level annotations iese sees see see sek Se Se ee ee ee ee ee ee ee ek ee 16 Ad ONOPED wasn Sid i foe EE EE OE RE GEE OR EG 16 4 2 2 ONCIOSE AM EE EE EE RE RE 16 42 3 OIE ds EE EE EE EE OE EE OE EE 17 4 2 4 OnMESSape EE EE ESE ras DOE EED OER be bats Ry AG Re GE a BORS ER iria 17 4 3 MessageHandlers Viminale Nee GEGEE GEE SE dd RS ee E aii 17 Di CONTISUTALIONS RE AE EE KO KA EN 19 5 1 javax websocket server ServerEndpointConfig esse ss sesse sesse 19 3 2 Javak WebSocke tsClTEnt Endpoint Con FAG EE testes E EER oh DR REG Deeg 20 6 Endpoint Lifecycle Sessions Sending Messages eise se ee ee ee ee ee ee seen seen ek ee ee 21 6 1 Endpoint bie id OE ii so 21 6 2 Javax mMebsocket SESSION RES EER ee ve Een tas 21 6 32 Sending Messages AE N EE N N N NR NE 22 6 4 RemoteEnd VV ged geek Sen ss ER N OE N EE EO EE 22 6 4 1 javax websocket RemoteEndpoint BaSic iss see se see se see se ee 22 6 4 2 javax websocket RemoteEndpoint ASYNC iis sesse se eee se see se ee 23 Te de Ni vu AR EE ER EE ED canes sets 24 1 1 jayax Inject Inject sample ii SR Ee GEE SE ee ge Gee EG Ge ee De 24 T2 EJB Sample AR EE RE EE ER OE EA 24 8 Tyrus proprietary configuration 2 0 0 0 see see see see Sek Se ee ee ee ee ee ee ge Se seas Se Re Ge ke ee ke ee 26 8 1 Chent side SSL configuration sesse Ee SES ES EE bos sey SEED SE pes PES Og See Rg
45. nnectFailure is invoked when client fails to connect to remote endpoint for example due to temporary network issue or current high server load 8 8 Client behind proxy Tyrus client supports traversing proxies but it is Tyrus specific feature and its configuration is shown in the following code sample 1 2 ClientManager client ClientManager createClient 3 client getProperties put ClientManager PROXY_URI http my proxy com 80 4 Value is expected to be proxy URI Protocol part is currently ignored but must be present 8 9 JDK 7 client As has been said in previous chapters both Tyrus client and server were implemented on top of Grizzly NIO framework This still remains true but an alternative Tyrus Websocket client implementation based on Java 7 Asynchronous Channel API has been available since version 1 6 There are two options how to switch between client implementations If you do not mind using Tyrus specific API the most straightforward way is to use 1 2 final ClientManager client ClientManager createClient JdkClientContainer cla 3 You just have to make sure that the dependency on JDK client is included in your project lt dependency gt lt groupId gt org glassfish tyrus lt groupld gt lt artifactId gt tyrus container jdk client lt artifactId gt lt version gt 1 7 lt version gt lt dependency gt Grizzly client is the default option so creating a client without any parameters w
46. o our API documentation linked from the Tyrus http tyrus java net and Java API for WebSocket https java net projects websocket spec home pages as an additional source of information about Tyrus features and API If you would like to contribute to the guide or have questions on things not covered in our docs please contact us at users tyrus java net mailto users tyrus java net Vil Chapter 1 Getting Started This chapter provides a quick introduction on how to get started building WebSocket services using Java API for WebSocket and Tyrus The example described here presents how to implement simple websocket service as JavaEE web application that can be deployed on any servlet container supporting Servlet 3 1 and higher It also discusses starting Tyrus in standalone mode 1 1 WebSocket Services Using Java API for WebSocket First to use the Java API for WebSocket in your project you need to depend on the following artifact lt dependency gt lt groupId gt javax websocket lt groupId gt lt artifactld gt javax websocket api lt artifactld gt lt version gt 1 0 lt version gt lt dependency gt 1 1 1 Creating Annotated Server Endpoint In this section we will create a simple server side websocket endpoint which will echo the received message back to the sender We will deploy this endpoint on the container In Java API for WebSocket and Tyrus there are two basic approaches how to create an endpoint either
47. ocation http java sun com xml ns javaee http java sun com lt context param gt lt param name gt org glassfish tyrus maxSessionsPerRemoteAddr lt param name gt lt param value gt 5 lt param value gt lt context param gt lt web app gt 8 11 3 Maximal number of open sessions per endpoint Set maximum number of sessions in annotated endpoint 1 2 import javax websocket OnOpen 3 import javax websocket Session 4 import javax websocket server ServerEndpoint 5 6 import org glassfish tyrus core MaxSessions 7 8 x 9 Annotated endpoint 10 11 MaxSessions 100 12 ServerEndpoint value limited sessions endpoint 13 public static class LimitedSessionsEndpoint 14 OnOpen 15 public void onOpen Session s 16 17 18 19 20 Set maximum number of sessions for programmatic endpoint TyrusServerEndpointConfig Builder create LimitedSessionsEndpoint class limited sessions endpoint maxSessions 100 build PD OOND E Note that only positive integer is allowed 39
48. of extension implementations It is not usual to modify control frames as it might end with half closed connections or unanswered ping messages 29 Tyrus proprietary configuration ExtendedExtension representation needs to be able to handle extension parameter negotiation and actual processing of incoming and outgoing frames It also should be compatible with existing javax websocket Extension class since we want to re use existing registration API and be able to return new extension instance included in response from List lt Extension gt Session getNegotiatedExtensions call Consider following 1 public interface ExtendedExtension extends Extension 2 3 Frame processIncoming ExtensionContext context Frame frame 4 Frame processOutgoing ExtensionContext context Frame frame 5 6 ist onExtensionNegotiation ExtensionContext context List requestedParame T void onHandshakeResponse ExtensionContext context List responseParameters 8 9 void destroy ExtensionContext context 10 dd interface ExtensionContext 12 13 Map lt String Object gt getProperties 14 ES ExtendedExtension is capable of processing frames and influence parameter values during the handshake Extension is used on both client and server side and since the negotiation is only place where this fact applies we needed to somehow differentiate these sides On server side only onExtensionNegotiatio
49. pe Each decoder needs to implement the Decoder interface 4 1 2 2 encoders Contains list of classes that will be used to encode outgoing messages By encoding we mean transforming message from user defined type to text or binary type Each encoder needs to implement the Encoder interface 4 1 2 3 subprotocols List of names Strings of supported sub protocols 4 1 2 4 configurator Users may provide their own implementation of ClientEndpointConfiguration Configurator It allows them to control some algorithms used by Tyrus in the connection initialization phase Method beforeRequest allows the user to change the request headers constructed by Tyrus Method afterResponse allows the user to process the handshake response 15 WebSocket API Endpoints Sessions and MessageHandlers 1 public class Configurator 2 3 public void beforeRequest Map lt String List lt String gt gt headers 4 affect the headers before request is sent 5 6 7 public void afterResponse HandshakeResponse hr 8 process the handshake response 9 10 4 2 Endpoint method level annotations 4 2 1 4 2 2 OnOpen This annotation may be used on certain methods of ServerEndpoint or ClientEndpoint but only once per endpoint It is used to decorate a method which is called once new connection is established The connection is represented by the optional Session parameter The other optional parameter is EndpointConfig wh
50. pointConfig is used when deploying the endpoint either via implementing the javax websocket server ServerApplicationConfig or via registering the programmatic endpoint at the javax websocket server ServerContainer instance It allows the user to create the configuration programmatically The following example is used to deploy the EchoEndpoint programmatically In the method getEndpointClass the user has to specify the class of the deployed endpoint In the example Tyrus will create an instance of EchoEndpoint and deploy it This is the way how to tie together endpoint and it s configuration In the method get Path the user specifies that that the endpoint instance will be deployed at the path echo In the method public List lt String gt getSubprotocols the user specifies that the supported subprotocols are echo1 and echo2 The method getExtensions defines the extensions the endpoint supports Similarly the example configuration does not use any configurator Method public List lt Class lt extends Encoder gt gt getEncoders defines the encoders used by the endpoint The decoders and user properties map are defined in similar fashion If the endpoint class which is about to be deployed is an annotated endpoint note that the endpoint configuration will be taken from configuration object not from the annotation on the endpoint class Example 5 1 Configuration for EchoEndpoint Deployment
51. pplication e message statistics a directory containing message statistics MXBeans e text MXBean containing text message statistics e binary MXBean containing binary message statistics e control MXBean containing control message statistics e endpoints a directory containing application endpoint MXBeans e Endpoint 1 MXBean containing Endpoint 1 class name and path number of open sessions maximal number of open sessions error and total message statistics for the endpoint e text MXBean containing text message statistics e binary MXBean containing binary message statistics e control MXBean containing control message statistics e Endpoint 2 36 Tyrus proprietary configuration e Application 2 In fact the monitoring structure described above was a little bit simplistic because there is an additional monitoring level available which causes message metrics being also available per session The monitoring structure is very similar to the one described above with a small difference that there are four MXBeans registered for each session which contain text binary control and total message statistics In order to distinguish the two monitoring levels they will be referred to as endpoint level monitoring and session level monitoring 8 10 1 Configuration As has been already mentioned monitoring is supported only on the server side and is disabled by default The following code sample shows how endpoint leve
52. s SampleDecoder implements Decoder Text lt SampleType gt 2 3 Override 4 public SampleType decode String s 5 return new SampleType s 6 7 8 Override 9 public boolean willDecode String s 10 return s startsWith SampleType PREFIX 11 12 13 Override 14 public void init EndpointConfig config 15 do nothing 16 17 18 Override 19 public void destroy 20 do nothing 21 22 4 1 1 3 encoders Contains list of classes that will be used to encode outgoing messages By encoding we mean transforming message from user defined type to text or binary type Each encoder needs to implement the Encoder interface SampleEncoder in the following example decodes String message and produces SampleType message see decode method on line 4 Example 4 5 SampleEncoder 1 public class SampleEncoder implements Encoder Text lt SampleType gt 2 3 Override 4 public String encode SampleType message 5 return data toString 6 7 8 Override 9 public void init EndpointConfig config 10 do nothing 11 12 13 Override 14 public void destroy 1 5 do nothing 13 WebSocket API Endpoints Sessions and MessageHandlers 16 ETY 4 1 1 4 subprotocols List of names Strings of supported sub protocols The first protocol in this list that matches with sub protocols provided by the client side is used 4 1 1 5 configurator Users may provide their own imple
53. s core monitoring Application 6 7 8 9 Tyrus offers a few ways to limit the number of open sessions which can be used to save limited resources on a server hosting system The limits can be configured in several scopes 37 Tyrus proprietary configuration e per whole application e per endpoint e per remote address client IP address If the number of simultaneously opened sessions exceeds any of these limits Tyrus will close the session with close code 1013 Try Again Later Limits mentioned above can be combined together For example let s say we have an application with two endpoints Overall limit per application will be 1000 open sessions and the first one non critical endpoint will be limited to 75 open sessions at maximum So we know that the second endpoint can handle 925 1000 opened sessions depends on how many open sessions are connected to the first endpoint 0 75 8 11 1 Maximal number of open sessions per application This configuration property can be used to limit overall number of open sessions per whole application The main purpose of this configurable limit is to restrict how many resources the application can consume The number of open sessions per whole application can be configured by setting property org glassfish tyrus maxSessionsPerApp Property can be used as lt context param gt in web xml or as an entry in parameter map in standalone Server properties Note that only positive integer is
54. s little different from Grizzly client because Grizzly client uses SSLEngineConfigurator https grizzly java net docs 2 3 apidocs org glassfish grizzly ssl SSLEngineConfigurator html end SSLContextConfigurator https grizzly java net docs 2 3 apidocs org glassfish grizzly ssl SSLContextConfigurator html from Grizzly project The main configuration principle stays the same for the JDK client but classes SslEngineConfigurator https tyrus java net apidocs 1 7 org glassfish tyrus container jdk client SslEngineConfigurator html and SslContextConfigurator https tyrus java net apidocs 1 7 org elassfish tyrus container dk client SsIContextConfigurator html from Tyrus project must be used instead The following code sample shows an example of some SSL parameters configuration for the JDK client de 2 SslContextConfigurator sslContextConfigurator new SslContextConfigurator 3 sslContextConfigurator setTrustStoreFile 4 sslContextConfigurator setTrustStorePassword 5 sslContextConfigurator setTrustStoreType 6 sslContextConfigurator setKeyStoreFile 7 sslContextConfigurator setKeyStorePassword 8 sslContextConfigurator setKeyStoreType 9 SslEngineConfigurator sslEngineConfigurator new SslEngineConfigurator sslCon 10 11 client getProperties put ClientManager SSL_ENGINE_CONFIGURATOR EngineCon 12 JMX Monitoring Tyrus allows monitoring
55. ssue when you are designing application with highly responsible user interface Tyrus introduces asynchronous variants to each connectToServer method prefixed with async which returns Future lt Session gt These methods do only simple check for provided URL and the rest is executed in separate thread All exceptions thrown during this phase are reported as cause of ExecutionException thrown when calling Future lt Session gt get 26 Tyrus proprietary configuration Asynchronous connect methods are declared on Tyrus implementation of WebSocketContainer called ClientManager ClientManager client ClientManager createClient final Future lt Session gt future client asyncConnectToServer Client Endpoint cl future get 1 2 3 try 4 5 catch 6 ClientManager contains async alternative to each connectToServer method 8 3 Optimized broadcast One of the typical usecases we ve seen so far for WebSocket server side endpoints is broadcasting messages to all connected clients something like 1 OnMessage 2 public void onMessage Session session String message throws IOException 3 for Session s session getOpenSessions s getBasicRemote sendText message 4 5 6 Executing this code might cause serious load increase on your application server Tyrus provides optimized broadcast implementation which takes advantage of the fact that we are sending exac
56. t and Tyrus to demonstrate how to develop programmatic client endpoint The following code is used as a client part to communicate with the EchoEndpoint deployed on server using Tyrus and Java API for WebSocket The example Client Endpoint utilizes the concept of the programmatic endpoint By programmatic endpoint we mean endpoint which is created by extending class javax websocket Endpoint The example is standalone java application which needs to depend on some Tyrus artifacts to work correctly see Tyrus Standalone Mode In the example first the Count DownLat ch is initialized It is needed as a bocking data structure on line 31 it either waits for 100 seconds or until it gets counted down line 22 On line 9 the javax websocket ClientEndpointConfig is created we will need it later to connect the endpoint to the server On line 11 the org glassfish tyrus client ClientManager is created it implements the javax websocket WebSocketContainer and is used to connect to server This happens on next line The client endpoint functionality is contained in the javax websocket Endpoint lazy instantiation In the onOpen method new MessageHandler is registered the received message is just printed on the console and the latch is counted down After the registration the message is sent to tje servere line 25 Example 1 2 Client Endpoint 1 public class Doc
57. ted Now when we have our CryptoExtension implemented we want to use it There is nothing new compared to standard WebSocket Java API feel free to skip this part if you are already familiar with it Only programmatic version will be demonstrated It is possible to do it for annotated version as well but it is little bit more complicated on the server side and I want to keep the code as compact as possible Client registration OO JOU DRE CS e O E a wo 10 11 12 13 14 ArrayList extensions new ArrayList extensions add new Cryptol Extension final ClientEndpointConfig clientConfiguration ClientEndpointConfig Builder create extensions extensions build WebSocketContainer client final Session session client connectToServer n Override ContainerProvider getWebSocketContainer w Endpoint public void onOpen Session session EndpointConfig config clientConfiguration Server registration URI create 1 public class CryptoExtensionApplicationConfig implements ServerApplicationConf 2 3 Override 4 public Set getEndpointConfigs Set lt Class lt extends Endpoint gt gt endpointClass 2 Set endpointConfigs new HashSet 6 endpointConfigs add 7 ServerEndpointConfig Builder create EchoEndpoint class echo 8 extensions Arrays asList new CryptoExtension build 9
58. th javax websocket OnError In each of the methods annotated with the preceeding annotations the user may use parameter of type javax websocket Session In the following example the developer wants to send a message in the method annotated with javax websocket OnOpen As we will demonstrate later the developer needs the session instance to do so According to Java API for WebSocket Session is one of the allowed parameters in methods annotated with javax websocket OnOpen Once the annotated method gets called Tyrus passes in the correct instance of javax websocket Session Example 6 1 Lifecycle echo sample 1 ServerEndpoint echo 2 public class EchoEndpoint 3 21 Endpoint Lifecycle Sessions Sending Messages 4 OnOpen 5 public void onOpen Session session throws IOException 6 session getBasicRemote sendText onOpen 7 8 9 OnMessage 10 public String echo String message 11 return message 12 13 14 OnError 15 public void onError Throwable t 16 t printStackTrace j 17 18 6 3 Sending Messages Generally there are two ways how to send message to the peer endpoint First one is usable for annotated endpoints only The user may send the message by returning the message content from the method annotated with javax websocket OnMessage In the following example the message m is sent back to the remote endpoint Example 6 2 Sending message in OnMessage
59. ther with a number of times each error occurred is available on both application and endpoint level The monitored errors correspond to invocation of OnError method on an annotated endpoint or its equivalent on a programmatic endpoint The invocation of OnError method is just an analogy and an error will be monitored even if no OnError method is provided on the endpoint Errors that occur in OnOpen OnClose methods and methods handling incoming messages are monitored Errors that occurred during handshake will not be among the monitored errors The collected metrics as well as the endpoint properties mentioned above are accessible at runtime through Tyrus MXBeans As has been already mention the information is available on both application and endpoint level with each application or endpoint being represented with four MXBeans One of those MXBeans contains total message statistics for both sent and received messages as well as any properties specific for applications or endpoints such as endpoint path in the case of an endpoint The other three MXBeans contain information about sent and received text binary and control messages When a user connects to a tyrus application MBean server using an JMX client such as JConsole they will see the following structure e Application 1 MXBean containing a list of deployed endpoint class names and paths number of open sessions maximal number of open sessions error and total message statistics for the a
60. tly same message to all clients so dataframe can be created and serialized only once Furthermore Tyrus can iterate over set of opened connections faster than Session getOpenSession 1 OnMessage 2 public void onMessage Session session String message 3 TyrusSession session broadcast message As Unfortunately WebSocket API forbids anything else than Session in OnMessage annotated method parameter so you cannot use TyrusSession there directly and you might need to perform instanceof check 8 4 Incoming buffer size Sevlet container buffers incoming WebSocket frames and there must be a size limit to precede OutOfMemory Exception and potentially DDoS attacks Configuration property is named org glassfish tyrus servlet incoming buffer size and you can set it in web xml this particular snipped sets the buffer size to 17000000 bytes 16M payload lt web app version 2 5 xmlns http java sun com xml ns javaee xm xsi schemaLocation http java sun com xml ns javaee http java lt param name gt org glassfish tyrus servlet incoming buffer size lt p lt param value gt 17000000 lt param value gt 1 2 3 4 lt context param gt 3 6 7 lt context param gt 27 lns xsi ht sun com xm aram name gt Tyrus proprietary configuration 8 lt web app gt Default value is 4194315 which correspond to 4M plus few bytes to frame headers so you should be able to receive up to 4M long message w

Tyrus 1.7 User Guide

Contents

Download Pdf Manuals

Related Search

Related Contents