Package: TransportFacade

TransportFacade

Coverage

1: /*******************************************************************************
2: * Copyright (c) 2016, 2022 Eurotech and/or its affiliates and others
3: *
4: * This program and the accompanying materials are made
5: * available under the terms of the Eclipse Public License 2.0
6: * which is available at https://www.eclipse.org/legal/epl-2.0/
7: *
8: * SPDX-License-Identifier: EPL-2.0
9: *
10: * Contributors:
11: * Eurotech - initial API and implementation
12: *******************************************************************************/
13: package org.eclipse.kapua.transport;
14:
15: import org.eclipse.kapua.transport.exception.TransportSendException;
16: import org.eclipse.kapua.transport.exception.TransportTimeoutException;
17: import org.eclipse.kapua.transport.message.TransportChannel;
18: import org.eclipse.kapua.transport.message.TransportMessage;
19: import org.eclipse.kapua.transport.message.TransportPayload;
20:
21: import org.checkerframework.checker.nullness.qual.Nullable;
22: import javax.validation.constraints.NotNull;
23:
24: /**
25: * API to use the Transport layer for the device communication.
26: * <p>
27: * It extends {@link AutoCloseable} {@code interface} so the user MUST invoke the {@link #close()} method after usage.
28: *
29: * @param <C> The {@link TransportChannel} implementation class for the request.
30: * @param <P> The {@link TransportPayload} implementation class for the request.
31: * @param <MQ> The {@link TransportMessage} implementation class for the request.
32: * @param <MS> The {@link TransportMessage} implementation class for the response.
33: * @author alberto.codutti
34: * @see #close()
35: * @since 1.0.0
36: */
37: public interface TransportFacade<C extends TransportChannel, P extends TransportPayload, MQ extends TransportMessage<C, P>, MS extends TransportMessage<C, P>> extends AutoCloseable {
38:
39: //
40: // Message management
41: //
42:
43: /**
44: * Send a request message to a device waiting for the response.
45: * <p>
46: * The timeout is optional. If {@code null} the default one defined by the implementation will be used.
47: *
48: * @param message The request message to send.
49: * @param timeout The timeout for the operation.
50: * @return The response to the request message.
51: * @throws TransportTimeoutException if waiting of the response goes on timeout.
52: * @throws TransportSendException if sending the request produces any error.
53: * @since 1.0.0
54: */
55: MS sendSync(@NotNull MQ message, @Nullable Long timeout) throws TransportTimeoutException, TransportSendException;
56:
57: /**
58: * Send a request message to a device without waiting for the response
59: *
60: * @param message The request message to send.
61: * @throws TransportTimeoutException if waiting of the response goes on timeout.
62: * @throws TransportSendException if sending the request produces any error.
63: * @since 1.0.0
64: */
65: void sendAsync(@NotNull MQ message) throws TransportTimeoutException, TransportSendException;
66:
67: //
68: // Utilities
69: //
70:
71: /**
72: * Gets the id of the instance of {@link TransportFacade}
73: *
74: * @return The id of this {@link TransportFacade}
75: * @since 1.0.0
76: */
77: String getClientId();
78:
79: /**
80: * Executes clean operations for this {@link TransportFacade}
81: * <p>
82: * This method must be called by the device layer after being used.
83: *
84: * @since 1.0.0
85: * @deprecated since 1.2.0 this {@code interface} extends {@link AutoCloseable}. Please make use of {@link #close()}
86: */
87: @Deprecated
88: void clean();
89:
90: /**
91: * Executes close operations for this {@link TransportFacade}
92: * <p>
93: * This method MUST be invoked by the user of the {@link TransportFacade}.
94: * Fail to do so will result in resource leak and other bad things!
95: * It is recommended to use Java's try-with-resource.
96: *
97: * @since 1.2.0
98: */
99: @Override
100: void close();
101:
102: /**
103: * Returns the {@code class} of the type of {@link TransportMessage} implementation used by this implementation of the {@link TransportFacade}.
104: * <p>
105: * This is meant to be used while requesting a translator from the device layer to the transport layer.
106: *
107: * @return The {@code class} of the type of {@link TransportMessage} implementation used by this implementation of the {@link TransportFacade}.
108: * @since 1.0.0
109: */
110: Class<MQ> getMessageClass();
111: }