1 package com.ericsson.research.trap;
2
3 /*
4 * ##_BEGIN_LICENSE_##
5 * Transport Abstraction Package (trap)
6 * ----------
7 * Copyright (C) 2014 Ericsson AB
8 * ----------
9 * Redistribution and use in source and binary forms, with or without modification,
10 * are permitted provided that the following conditions are met:
11 *
12 * 1. Redistributions of source code must retain the above copyright notice, this
13 * list of conditions and the following disclaimer.
14 *
15 * 2. Redistributions in binary form must reproduce the above copyright notice,
16 * this list of conditions and the following disclaimer in the documentation
17 * and/or other materials provided with the distribution.
18 *
19 * 3. Neither the name of the Ericsson AB nor the names of its contributors
20 * may be used to endorse or promote products derived from this software without
21 * specific prior written permission.
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
24 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
25 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
26 * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
27 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
28 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
30 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
31 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
32 * OF THE POSSIBILITY OF SUCH DAMAGE.
33 * ##_END_LICENSE_##
34 */
35
36
37
38 import com.ericsson.research.trap.delegates.TrapDelegate;
39
40 /**
41 * A TrapClient is a TrapEndpoint capable of opening an outgoing connection, commonly to a TrapListener. It is able to
42 * reconnect transports at will, unlike a ServerTrapEndpoint. Create a TrapClient using
43 * {@link TrapFactory#createClient(String, boolean)} as follows.
44 * <p>
45 *
46 * <pre>
47 * TrapClient c = TrapFactory.createClient("http://trap.server.com/");
48 * c.setDelegate(...)
49 * c.open();
50 * </pre>
51 * <p>
52 * TrapClient should have {@link #setDelegate(TrapDelegate, boolean)} called in order to properly work. The delegate
53 * will handle state changes and incoming messages. It is recommended the delegate is set before open; doing it later
54 * may lose events.
55 *
56 * @author Vladimir Katardjiev
57 * @since 1.0
58 */
59 public interface TrapClient extends TrapEndpoint
60 {
61 /**
62 * Instructs the TrapClient to begin outgoing connection attempts. This will make exactly one attempt to connect on
63 * each available transport. If any connection attempt succeeds, the entire endpoint will move to
64 * {@link TrapState#OPEN}, else it will move to {@link TrapState#ERROR}
65 *
66 * @throws TrapException
67 * If a fatal configuration error prevents the endpoint from opening. Generally this would be no
68 * available/configured transports.
69 */
70 public void open() throws TrapException;
71 }