1 /*
2 * Copyright (C) 2013 4th Line GmbH, Switzerland
3 *
4 * The contents of this file are subject to the terms of either the GNU
5 * Lesser General Public License Version 2 or later ("LGPL") or the
6 * Common Development and Distribution License Version 1 or later
7 * ("CDDL") (collectively, the "License"). You may not use this file
8 * except in compliance with the License. See LICENSE.txt for more
9 * information.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
14 */
15
16 package org.fourthline.cling.transport.spi;
17
18 import org.fourthline.cling.transport.Router;
19 import org.fourthline.cling.model.message.OutgoingDatagramMessage;
20
21 import java.net.InetAddress;
22 import java.net.DatagramPacket;
23
24 /**
25 * Service for receiving (unicast only) and sending UDP datagrams, one per bound IP address.
26 * <p>
27 * This service typically listens on a socket for UDP unicast datagrams, with
28 * an ephemeral port.
29 * </p>
30 * <p>
31 * This listening loop is started with the <code>run()</code> method,
32 * this service is <code>Runnable</code>. Any received datagram is then converted into an
33 * {@link org.fourthline.cling.model.message.IncomingDatagramMessage} and
34 * handled by the
35 * {@link org.fourthline.cling.transport.Router#received(org.fourthline.cling.model.message.IncomingDatagramMessage)}
36 * method. This conversion is the job of the {@link org.fourthline.cling.transport.spi.DatagramProcessor}.
37 * </p>
38 * <p>
39 * Clients of this service use it to send UDP datagrams, either to a unicast
40 * or multicast destination. Any {@link org.fourthline.cling.model.message.OutgoingDatagramMessage} can
41 * be converted and written into a datagram with the {@link org.fourthline.cling.transport.spi.DatagramProcessor}.
42 * </p>
43 * <p>
44 * An implementation has to be thread-safe.
45 * </p>
46 *
47 * @param <C> The type of the service's configuration.
48 *
49 * @author Christian Bauer
50 */
51 public interface DatagramIO<C extends DatagramIOConfiguration> extends Runnable {
52
53 /**
54 * Configures the service and starts any listening sockets.
55 *
56 * @param bindAddress The address to bind any sockets on.
57 * @param router The router which handles received {@link org.fourthline.cling.model.message.IncomingDatagramMessage}s.
58 * @param datagramProcessor Reads and writes datagrams.
59 * @throws InitializationException If the service could not be initialized or started.
60 */
61 public void init(InetAddress bindAddress, Router router, DatagramProcessor datagramProcessor) throws InitializationException;
62
63 /**
64 * Stops the service, closes any listening sockets.
65 */
66 public void stop();
67
68 /**
69 * @return This service's configuration.
70 */
71 public C getConfiguration();
72
73 /**
74 * Sends a datagram after conversion with {@link org.fourthline.cling.transport.spi.DatagramProcessor#write(org.fourthline.cling.model.message.OutgoingDatagramMessage)}.
75 *
76 * @param message The message to send.
77 */
78 public void send(OutgoingDatagramMessage message);
79
80 /**
81 * The actual sending of a UDP datagram.
82 * <p>
83 * Recoverable errors should be logged, if appropriate only with debug level. Any
84 * non-recoverable errors should be thrown as <code>RuntimeException</code>s.
85 * </p>
86 *
87 * @param datagram The UDP datagram to send.
88 */
89 public void send(DatagramPacket datagram);
90 }