Package: Decoder$BinaryStream

Decoder$BinaryStream

Coverage

1: /*
2: * Copyright (c) 2018, 2020 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;
19:
20: import java.io.IOException;
21: import java.io.InputStream;
22: import java.io.Reader;
23: import java.nio.ByteBuffer;
24:
25: /**
26: * The Decoder interface holds member interfaces that define how a developer can provide the web socket container a way
27: * web socket messages into developer defined custom objects. The websocket implementation creates a new instance of the
28: * decoder per endpoint instance per connection. The lifecycle of the Decoder instance is governed by the container
29: * calls to the {@link Decoder#init(jakarta.websocket.EndpointConfig)} and {@link Decoder#destroy() } methods.
30: *
31: * @author dannycoward
32: */
33: public interface Decoder {
34:
35: /**
36: * This method is called with the endpoint configuration object of the endpoint this decoder is intended for when it
37: * is about to be brought into service.
38: *
39: * @implSpec The default implementation takes no action.
40: *
41: * @param config the endpoint configuration object when being brought into service
42: */
43: default void init(EndpointConfig config) {
44: }
45:
46: /**
47: * This method is called when the decoder is about to be removed from service in order that any resources the
48: * decoder used may be closed gracefully.
49: *
50: * @implSpec The default implementation takes no action.
51: */
52: default void destroy() {
53: }
54:
55: /**
56: * This interface defines how a custom object (of type T) is decoded from a web socket message in the form of a byte
57: * buffer.
58: *
59: * @param <T> The type of the object that is decoded
60: */
61: interface Binary<T> extends Decoder {
62:
63: /**
64: * Decode the given bytes into an object of type T.
65: * <p>
66: * It is not safe for other threads to use the ByteBuffer until the decoding of the given bytes is complete. If
67: * the decoding completes successfully, the buffer's limit will be unchanged and the buffer's position
68: * will be equal to the limit. If the decoding does not complete successfully, the state of the buffer is
69: * undefined.
70: *
71: * @param bytes the bytes to be decoded.
72: * @return the decoded object.
73: *
74: * @throws DecodeException If the provided bytes cannot be decoded to type T
75: */
76: T decode(ByteBuffer bytes) throws DecodeException;
77:
78: /**
79: * Answer whether the given bytes can be decoded into an object of type T.
80: * <p>
81: * It is not safe for other threads to use the ByteBuffer until this method completes. When the method
82: * completes, the buffer will be in the same state as it was at the start of the method call.
83: *
84: * @param bytes the bytes to be decoded.
85: * @return whether or not the bytes can be decoded by this decoder.
86: */
87: boolean willDecode(ByteBuffer bytes);
88:
89: }
90:
91: /**
92: * This interface defines how a custom object is decoded from a web socket message in the form of a binary stream.
93: *
94: * @param <T> The type of the object that is decoded
95: */
96: interface BinaryStream<T> extends Decoder {
97:
98: /**
99: * Decode the given bytes read from the input stream into an object of type T.
100: *
101: * @param is the input stream carrying the bytes.
102: * @return the decoded object.
103: *
104: * @throws DecodeException If the provided input stream cannot be decoded to type T
105: * @throws IOException If an error occurs reading the input stream
106: */
107: T decode(InputStream is) throws DecodeException, IOException;
108:
109: }
110:
111: /**
112: * This interface defines how a custom object is decoded from a web socket message in the form of a string.
113: *
114: * @param <T> The type of the object that is decoded
115: */
116: interface Text<T> extends Decoder {
117: /**
118: * Decode the given String into an object of type T.
119: *
120: * @param s string to be decoded.
121: * @return the decoded message as an object of type T
122: *
123: * @throws DecodeException If the provided string cannot be decoded to type T
124: */
125: T decode(String s) throws DecodeException;
126:
127: /**
128: * Answer whether the given String can be decoded into an object of type T.
129: *
130: * @param s the string being tested for decodability.
131: * @return whether this decoder can decoded the supplied string.
132: */
133: boolean willDecode(String s);
134:
135: }
136:
137: /**
138: * This interface defines how a custom object of type T is decoded from a web socket message in the form of a
139: * character stream.
140: *
141: * @param <T> The type of the object that is decoded
142: */
143: interface TextStream<T> extends Decoder {
144: /**
145: * Reads the websocket message from the implementation provided Reader and decodes it into an instance of the
146: * supplied object type.
147: *
148: * @param reader the reader from which to read the web socket message.
149: * @return the instance of the object that is the decoded web socket message.
150: *
151: * @throws DecodeException If the data from the provided reader cannot be decoded to type T
152: * @throws IOException If an error occurs reading from the reader
153: */
154: T decode(Reader reader) throws DecodeException, IOException;
155:
156: }
157: }