Package: ServerEndpoint

ServerEndpoint

Coverage

1: /*
2: * Copyright (c) 2018, 2019 Oracle and/or its affiliates and others.
3: * All rights reserved.
4: *
5: * This program and the accompanying materials are made available under the
6: * terms of the Eclipse Public License v. 2.0, which is available at
7: * http://www.eclipse.org/legal/epl-2.0.
8: *
9: * This Source Code may also be made available under the following Secondary
10: * Licenses when the conditions for such availability set forth in the
11: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
12: * version 2 with the GNU Classpath Exception, which is available at
13: * https://www.gnu.org/software/classpath/license.html.
14: *
15: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
16: */
17:
18: package jakarta.websocket.server;
19:
20: import java.lang.annotation.ElementType;
21: import java.lang.annotation.Retention;
22: import java.lang.annotation.RetentionPolicy;
23: import java.lang.annotation.Target;
24: import jakarta.websocket.Decoder;
25: import jakarta.websocket.Encoder;
26:
27: /**
28: * This class level annotation declares that the class it decorates is a web socket endpoint that will be deployed and
29: * made available in the URI-space of a web socket server. The annotation allows the developer to define the URL (or URI
30: * template) which this endpoint will be published, and other important properties of the endpoint to the websocket
31: * runtime, such as the encoders it uses to send messages.
32: *
33: * <p>
34: * The annotated class must have a public no-arg constructor.
35: *
36: * <p>
37: * For example:
38: *
39: * <pre>
40: * <code>
41: * @ServerEndpoint("/hello");
42: * public class HelloServer {
43: *
44: * @OnMessage
45: * public void processGreeting(String message, Session session) {
46: * System.out.println("Greeting received:" + message);
47: * }
48: *
49: * }
50: * </code>
51: * </pre>
52: *
53: * @author dannycoward
54: */
55: @Retention(RetentionPolicy.RUNTIME)
56: @Target(ElementType.TYPE)
57: public @interface ServerEndpoint {
58:
59: /**
60: * The URI or URI-template, level-1 (<a href="http://tools.ietf.org/html/rfc6570">See RFC 6570</a>) where the
61: * endpoint will be deployed. The URI us relative to the root of the web socket container and must begin with a
62: * leading "/". Trailing "/"'s are ignored. Examples:
63: *
64: * <pre>
65: * <code>
66: * @ServerEndpoint("/chat")
67: * @ServerEndpoint("/chat/{user}")
68: * @ServerEndpoint("/booking/{privilege-level}")
69: * </code>
70: * </pre>
71: *
72: * @return the URI or URI-template
73: */
74: public String value();
75:
76: /**
77: * The ordered array of web socket protocols this endpoint supports. For example, {"superchat", "chat"}.
78: *
79: * @return the subprotocols.
80: */
81: public String[] subprotocols() default {};
82:
83: /**
84: * The ordered array of decoder classes this endpoint will use. For example, if the developer has provided a
85: * MysteryObject decoder, this endpoint will be able to receive MysteryObjects as web socket messages. The websocket
86: * runtime will use the first decoder in the list able to decode a message, ignoring the remaining decoders.
87: *
88: * @return the decoders.
89: */
90: public Class<? extends Decoder>[] decoders() default {};
91:
92: /**
93: * The ordered array of encoder classes this endpoint will use. For example, if the developer has provided a
94: * MysteryObject encoder, this class will be able to send web socket messages in the form of MysteryObjects. The
95: * websocket runtime will use the first encoder in the list able to encode a message, ignoring the remaining
96: * encoders.
97: *
98: * @return the encoders.
99: */
100: public Class<? extends Encoder>[] encoders() default {};
101:
102: /**
103: * The optional custom configurator class that the developer would like to use to further configure new instances of
104: * this endpoint. If no configurator class is provided, the implementation uses its own. The implementation creates
105: * a new instance of the configurator per logical endpoint.
106: *
107: * @return the custom configuration class, or ServerEndpointConfig.Configurator.class if none was set in the
108: * annotation.
109: */
110: public Class<? extends ServerEndpointConfig.Configurator> configurator() default ServerEndpointConfig.Configurator.class;
111: }