Package: Encoder$BinaryStream

Encoder$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.OutputStream;
22: import java.io.Writer;
23: import java.nio.ByteBuffer;
24:
25: /**
26: * The Encoder interface defines how developers can provide a way to convert their custom objects into web socket
27: * messages. The Encoder interface contains subinterfaces that allow encoding algorithms to encode custom objects to:
28: * text, binary data, character stream and write to an output stream. The websocket implementation creates a new
29: * instance of the encoder per endpoint instance per connection. This means that each encoder instance has at most one
30: * calling thread at a time. The lifecycle of the Encoder instance is governed by the container calls to the
31: * {@link Encoder#init(jakarta.websocket.EndpointConfig)} and {@link Encoder#destroy() } methods.
32: *
33: * @author dannycoward
34: */
35: public interface Encoder {
36:
37: /**
38: * This method is called with the endpoint configuration object of the endpoint this encoder is intended for when it
39: * is about to be brought into service.
40: *
41: * @implSpec The default implementation takes no action.
42: *
43: * @param config the endpoint configuration object when being brought into service
44: */
45: default void init(EndpointConfig config) {
46: }
47:
48: /**
49: * This method is called when the encoder is about to be removed from service in order that any resources the
50: * encoder used may be closed gracefully.
51: *
52: * @implSpec The default implementation takes no action.
53: */
54: default void destroy() {
55: }
56:
57: /**
58: * This interface defines how to provide a way to convert a custom object into a text message.
59: *
60: * @param <T> The type of the custom developer object that this Encoder can encode into a String.
61: */
62: interface Text<T> extends Encoder {
63: /**
64: * Encode the given object into a String.
65: *
66: * @param object the object being encoded.
67: * @return the encoded object as a string.
68: *
69: * @throws EncodeException The provided object could not be encoded as a string
70: */
71: String encode(T object) throws EncodeException;
72:
73: }
74:
75: /**
76: * This interface may be implemented by encoding algorithms that want to write the encoded object to a character
77: * stream.
78: *
79: * @param <T> the type of the object this encoder can encode to a CharacterStream.
80: */
81: interface TextStream<T> extends Encoder {
82: /**
83: * Encode the given object to a character stream writing it to the supplied Writer. Implementations of this
84: * method may use the EncodeException to indicate a failure to convert the supplied object to an encoded form,
85: * and may use the IOException to indicate a failure to write the data to the supplied stream.
86: *
87: * @param object the object to be encoded.
88: * @param writer the writer provided by the web socket runtime to write the encoded data.
89: * @throws EncodeException if there was an error encoding the object due to its state.
90: * @throws IOException if there was an exception writing to the writer.
91: */
92: void encode(T object, Writer writer) throws EncodeException, IOException;
93: }
94:
95: /**
96: * This interface defines how to provide a way to convert a custom object into a binary message.
97: *
98: * @param <T> The type of the custom object that this Encoder can encoder to a ByteBuffer.
99: */
100: interface Binary<T> extends Encoder {
101: /**
102: * Encode the given object into a byte array.
103: *
104: * @param object the object being encoded.
105: * @return the binary data.
106: *
107: * @throws EncodeException The provided object could not be encoded to a byte buffer
108: */
109: ByteBuffer encode(T object) throws EncodeException;
110: }
111:
112: /**
113: * This interface may be implemented by encoding algorithms that want to write the encoded object to a binary
114: * stream.
115: *
116: * @param <T> the type of the object this encoder can encode.
117: */
118: interface BinaryStream<T> extends Encoder {
119: /**
120: * Encode the given object into a binary stream written to the implementation provided OutputStream.
121: *
122: * @param object the object being encoded.
123: * @param os the output stream where the encoded data is written.
124: *
125: * @throws EncodeException The provided object could not be encoded to an output stream
126: * @throws IOException If an error occurred writing to the output stream
127: */
128: void encode(T object, OutputStream os) throws EncodeException, IOException;
129: }
130: }