summaryrefslogtreecommitdiffstats
blob: 8ab36b3746f4d3cb807221b0019ac50f64252d10 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
/***************************************************************************
 * Copyright (c) 2004, 2005, 2006 Eike Stepper, Germany.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 * 
 * Contributors:
 *    Eike Stepper - initial API and implementation
 **************************************************************************/
package org.eclipse.net4j.transport;

import org.eclipse.net4j.util.lifecycle.Singleton;
import org.eclipse.net4j.util.registry.HashMapRegistry;
import org.eclipse.net4j.util.registry.IRegistry;

import org.eclipse.internal.net4j.transport.AbstractConnector;
import org.eclipse.internal.net4j.transport.ChannelImpl;

import java.util.concurrent.ExecutorService;

/**
 * One endpoint of a physical connection of arbitrary nature between two
 * communicating parties. A {@link Connector} encapsulates the process of
 * establishing and closing such connections and has a {@link Type} of
 * {@link Type#CLIENT} or {@link Type#SERVER} with respect to this process. Once
 * a connection is established either party can use its connector to open
 * multiple {@link Channel}s to asynchronously exchange {@link Buffer}s.
 * <p>
 * This interface is <b>not</b> intended to be implemented by clients.
 * Providers of connectors for new physical connection types have to subclass
 * {@link AbstractConnector} (see
 * {@link ChannelImpl#setConnector(AbstractConnector)}.
 * <p>
 * 
 * @author Eike Stepper
 */
public interface Connector
{
  @Singleton(stateful = true)
  public static final IRegistry<Integer, Connector> REGISTRY = new HashMapRegistry();

  public Integer getID();

  public Type getType();

  public boolean isClient();

  public boolean isServer();

  public ConnectorCredentials getCredentials();

  public void setCredentials(ConnectorCredentials credentials);

  public State getState();

  /**
   * Same as <code>{@link #getState()} == {@link State#CONNECTED}</code>.
   * <p>
   */
  public boolean isConnected();

  /**
   * Asynchronous connect. May leave this {@link Connector} in a state where
   * <code>{@link #isConnected()} == false</code>.
   * <p>
   */
  public void connectAsync() throws ConnectorException;

  /**
   * Blocks until <code>{@link #isConnected()} == true</code> or the given
   * timeout expired.
   * <p>
   * 
   * @throws ConnectorException
   */
  public boolean waitForConnection(long timeout) throws ConnectorException;

  /**
   * Synchronous connect. Blocks until <code>{@link #isConnected()} ==
   * true</code>
   * or the given timeout expired.
   * <p>
   */
  public boolean connect(long timeout) throws ConnectorException;

  public ConnectorException disconnect();

  public Channel[] getChannels();

  /**
   * Synchronous request to open a new {@link Channel} with an undefined channel
   * protocol. Since the peer connector can't lookup a {@link ProtocolFactory}
   * without a protocol identifier the {@link BufferHandler} of the peer
   * {@link Channel} can only be provided by external {@link ChannelListener}s.
   * <p>
   * 
   * @see #openChannel(String)
   */
  public Channel openChannel() throws ConnectorException;

  /**
   * Synchronous request to open a new {@link Channel} with a channel protocol
   * defined by a given protocol identifier. The peer connector will lookup a
   * {@link ProtocolFactory} with the protocol identifier, create a
   * {@link BufferHandler} and inject it into the peer {@link Channel}.
   * <p>
   * 
   * @see #openChannel()
   */
  public Channel openChannel(String protocolID) throws ConnectorException;

  public Channel openChannel(String protocolID, Object protocolData) throws ConnectorException;

  /**
   * Returns the {@link IRegistry} of {@link ProtocolFactory}s associated with
   * this connector.
   * <p>
   * 
   * @see #setProtocolFactoryRegistry(IRegistry)
   * @return The registry or <code>null</code>.
   */
  public IRegistry<String, ProtocolFactory> getProtocolFactoryRegistry();

  /**
   * Sets the {@link IRegistry} of {@link ProtocolFactory}s for this connector.
   * <p>
   * 
   * @param protocolFactoryRegistry
   *          The registry or <code>null</code>.
   */
  public void setProtocolFactoryRegistry(IRegistry<String, ProtocolFactory> protocolFactoryRegistry);

  public ExecutorService getReceiveExecutor();

  public void setReceiveExecutor(ExecutorService receiveExecutor);

  public void addStateListener(StateListener listener);

  public void removeStateListener(StateListener listener);

  public void addChannelListener(ChannelListener listener);

  public void removeChannelListener(ChannelListener listener);

  /**
   * @author Eike Stepper
   */
  public enum Type
  {
    CLIENT, SERVER
  }

  /**
   * @author Eike Stepper
   */
  public enum State
  {
    DISCONNECTED, CONNECTING, NEGOTIATING, CONNECTED
  }

  /**
   * @author Eike Stepper
   */
  public interface StateListener
  {
    public void notifyStateChanged(Connector connector, State newState, State oldState);
  }

  /**
   * @author Eike Stepper
   */
  public interface ChannelListener
  {
    public void notifyChannelAboutToOpen(Channel channel);

    public void notifyChannelOpened(Channel channel);

    public void notifyChannelClosing(Channel channel);
  }
}