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.model.message.StreamRequestMessage;
19 import org.fourthline.cling.model.message.StreamResponseMessage;
20
21 /**
22 * Service for sending TCP (HTTP) stream request messages.
23 *
24 * <p>
25 * An implementation has to be thread-safe.
26 * Its constructor may throw {@link org.fourthline.cling.transport.spi.InitializationException}.
27 * </p>
28 *
29 * @param <C> The type of the service's configuration.
30 *
31 * @author Christian Bauer
32 */
33 public interface StreamClient<C extends StreamClientConfiguration> {
34
35 /**
36 * Sends the given request via TCP (HTTP) and returns the response.
37 *
38 * <p>
39 * This method must implement expiration of timed out requests using the
40 * {@link StreamClientConfiguration} settings. When a request expires, a
41 * <code>null</code> response will be returned.
42 * </p>
43 * <p>
44 * This method will always try to complete execution without throwing an exception. It will
45 * return <code>null</code> if an error occurs, and optionally log any exception messages.
46 * </p>
47 * <p>
48 * The rules for logging are:
49 * </p>
50 * <ul>
51 * <li>If the caller interrupts the calling thread, log at <code>FINE</code>.</li>
52 * <li>If the request expires because the timeout has been reached, log at <code>INFO</code> level.</li>
53 * <li>If another error occurs, log at <code>WARNING</code> level</li>
54 * </ul>
55 * <p>
56 * This method <strong>is required</strong> to add a <code>Host</code> HTTP header to the
57 * outgoing HTTP request, even if the given
58 * {@link org.fourthline.cling.model.message.StreamRequestMessage} does not contain such a header.
59 * </p>
60 * <p>
61 * This method will add the <code>User-Agent</code> HTTP header to the outgoing HTTP request if
62 * the given message did not already contain such a header. You can set this default value in your
63 * {@link StreamClientConfiguration}.
64 * </p>
65 *
66 * @param message The message to send.
67 * @return The response or <code>null</code> if no response has been received or an error occurred.
68 * @throws InterruptedException if you interrupt the calling thread.
69 */
70 public StreamResponseMessage sendRequest(StreamRequestMessage message) throws InterruptedException;
71
72 /**
73 * Stops the service, closes any connection pools etc.
74 */
75 public void stop();
76
77 /**
78 * @return This service's configuration.
79 */
80 public C getConfiguration();
81
82 }