-
Notifications
You must be signed in to change notification settings - Fork 36
/
deployment.xml
182 lines (157 loc) · 7.51 KB
/
deployment.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
<?xml version="1.0"?>
<!--
Copyright (c) 2013, 2017 Oracle and/or its affiliates. All rights reserved.
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0, which is available at
http://www.eclipse.org/legal/epl-2.0.
This Source Code may also be made available under the following Secondary
Licenses when the conditions for such availability set forth in the
Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
version 2 with the GNU Classpath Exception, which is available at
https://www.gnu.org/software/classpath/license.html.
SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
-->
<!DOCTYPE chapter [<!ENTITY % ents SYSTEM "tyrus.ent" > %ents; ]>
<chapter xmlns="http://docbook.org/ns/docbook"
version="5.0"
xml:lang="en"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
xml:id="deployment">
<title>Deploying WebSocket Endpoints</title>
<para>
Deploying WebSocket endpoints can be done in two ways. Either deploying via putting the endpoint in the WAR
file, or using the ServerContainer methods to deploy the programmatic endpoint in the deployment phase.
</para>
<section>
<title>Deploying Endpoints as a WAR file</title>
<para>
The classes that are scanned for in WAR are the following ones:
<itemizedlist mark='opencircle'>
<listitem>
<para>
Classes that implement the <code>jakarta.websocket.ServerApplicationConfig</code>.
</para>
</listitem>
<listitem>
<para>
Classes annotated with <code>jakarta.websocket.server.ServerEndpoint</code>.
</para>
</listitem>
<listitem>
<para>
Classes that extend <code>jakarta.websocket.Endpoint</code>.
</para>
</listitem>
</itemizedlist>
</para>
<section>
<title>Deployment Algorithm</title>
<para>
<orderedlist numeration="arabic">
<listitem>
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
<code>jakarta.websocket.server.ServerEndpoint</code> or extending <code>jakarta.websocket.Endpoint</code>).
</listitem>
<listitem>
If no class implementing ServerApplicationConfiguration is present, Tyrus deploys all classes annotated
with @ServerEndpoint or extending Endpoint present in the WAR.
</listitem>
</orderedlist>
</para>
</section>
<para>
Let's have the following classes in the WAR:
<example xml:id="deployment-serverapplicationconfig">
<title>Deployment of WAR containing several classes extending <code>jakarta.websocket.server.ServerApplicationConfig</code></title>
<programlisting language="java" linenumbering="numbered">public class MyApplicationConfigOne implements ServerApplicationConfig {
public Set<ServerEndpointConfig> getEndpointConfigs(Set<Class<? extends Endpoint>> endpointClasses);
Set<Class<? extends Endpoint>> s = new HashSet<Class<? extends Endpoint>>;
s.add(ProgrammaticEndpointOne.class);
return s;
}
public Set<Class> getAnnotatedEndpointClasses(Set<Class<?>> scanned);
Set<Class<?>> s = new HashSet<Class<?>>;
s.add(AnnotatedEndpointOne.class);
return s;
}
}
public class MyApplicationConfigTwo implements ServerApplicationConfig {
public Set<ServerEndpointConfig> getEndpointConfigs(Set<Class<? extends Endpoint>> endpointClasses);
Set<Class<? extends Endpoint>> s = new HashSet<Class<? extends Endpoint>>;
s.add(ProgrammaticEndpointTwo.class);
return s;
}
public Set<Class> getAnnotatedEndpointClasses(Set<Class<?>> scanned);
Set<Class<?>> s = new HashSet<Class<?>>;
s.add(AnnotatedEndpointTwo.class);
return s;
}
}
@ServerEndpoint(value = "/annotatedone")
public class AnnotatedEndpointOne {
...
}
@ServerEndpoint(value = "/annotatedtwo")
public class AnnotatedEndpointTwo {
...
}
@ServerEndpoint(value = "/annotatedthree")
public class AnnotatedEndpointThree {
...
}
public class ProgrammaticEndpointOne extends Endpoint {
...
}
public class ProgrammaticEndpointTwo extends Endpoint {
...
}
public class ProgrammaticEndpointThree extends Endpoint {
...
}</programlisting>
</example>
According to the deployment algorithm classes <code>AnnotatedEndpointOne</code>, <code>AnnotatedEndpointTwo</code>,
<code>ProgrammaticEndpointOne</code> and <code>ProgrammaticEndpointTwo</code> will be deployed.
<code>AnnotatedEndpointThree</code> and <code>ProgrammaticEndpointThree</code> will not be
deployed, as these are not returned by the respective
methods of <code>MyApplicationConfigOne</code> nor <code>MyApplicationConfigTwo</code>.
</para>
</section>
<section>
<title>Deploying endpoints via <code>jakarta.websocket.server.ServerContainer</code></title>
<para>
Endpoints may be deployed using <code>jakarta.websocket.server.ServerContainer</code> 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 <code>jakarta.websocket.server.ServerContainer</code> on the ServletContext, see
the following example for annotated endpoint:
<example xml:id="deployment-servercontainer">
<title>Deployment of Annotated Endpoint Using ServerContainer</title>
<programlisting language="java" linenumbering="numbered">@WebListener
@ServerEndpoint("/annotated")
public class MyServletContextListenerAnnotated implements ServletContextListener {
@Override
public void contextInitialized(ServletContextEvent servletContextEvent) {
final ServerContainer serverContainer = (ServerContainer) servletContextEvent.getServletContext()
.getAttribute("jakarta.websocket.server.ServerContainer");
try {
serverContainer.addEndpoint(MyServletContextListenerAnnotated.class);
} catch (DeploymentException e) {
e.printStackTrace();
}
}
@OnMessage
public String onMessage(String message) {
return message;
}
@Override
public void contextDestroyed(ServletContextEvent servletContextEvent) {
}
}</programlisting>
</example>
</para>
</section>
</chapter>