1/*
2 * Copyright (c) 2011 jMonkeyEngine
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are
7 * met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 *   notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 *   notice, this list of conditions and the following disclaimer in the
14 *   documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
17 *   may be used to endorse or promote products derived from this software
18 *   without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
27 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
28 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
29 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32
33package com.jme3.network;
34
35import java.util.Collection;
36
37/**
38 *  Represents a host that can send and receive messages to
39 *  a set of remote client connections.
40 *
41 *  @version   $Revision: 8938 $
42 *  @author    Paul Speed
43 */
44public interface Server
45{
46    /**
47     *  Returns the 'game name' for this server.  This should match the
48     *  'game name' set on connecting clients or they will be turned away.
49     */
50    public String getGameName();
51
52    /**
53     *  Returns the game-specific version of this server used for detecting
54     *  mismatched clients.
55     */
56    public int getVersion();
57
58    /**
59     *  Sends the specified message to all connected clients.
60     */
61    public void broadcast( Message message );
62
63    /**
64     *  Sends the specified message to all connected clients that match
65     *  the filter.  If no filter is specified then this is the same as
66     *  calling broadcast(message) and the message will be delivered to
67     *  all connections.
68     *  <p>Examples:</p>
69     *  <pre>
70     *    // Broadcast to connections: conn1, conn2, and conn3
71     *    server.broadcast( Filters.in( conn1, conn2, conn3 ), message );
72     *
73     *    // Broadcast to all connections exception source
74     *    server.broadcast( Filters.notEqualTo( source ), message );
75     *  </pre>
76     */
77    public void broadcast( Filter<? super HostedConnection> filter, Message message );
78
79    /**
80     *  Sends the specified message over the specified alternate channel to all connected
81     *  clients that match the filter.  If no filter is specified then this is the same as
82     *  calling broadcast(message) and the message will be delivered to
83     *  all connections.
84     *  <p>Examples:</p>
85     *  <pre>
86     *    // Broadcast to connections: conn1, conn2, and conn3
87     *    server.broadcast( Filters.in( conn1, conn2, conn3 ), message );
88     *
89     *    // Broadcast to all connections exception source
90     *    server.broadcast( Filters.notEqualTo( source ), message );
91     *  </pre>
92     */
93    public void broadcast( int channel, Filter<? super HostedConnection> filter, Message message );
94
95    /**
96     *  Start the server so that it will began accepting new connections
97     *  and processing messages.
98     */
99    public void start();
100
101    /**
102     *  Adds an alternate channel to the server, using the specified port.  This is an
103     *  entirely separate connection where messages are sent and received in parallel
104     *  to the two primary default channels.  All channels must be added before the connection
105     *  is started.
106     *  Returns the ID of the created channel for use when specifying the channel in send or
107     *  broadcast calls.  The ID is returned entirely out of convenience since the IDs
108     *  are predictably incremented.  The first channel is 0, second is 1, and so on.
109     */
110    public int addChannel( int port );
111
112    /**
113     *  Returns true if the server has been started.
114     */
115    public boolean isRunning();
116
117    /**
118     *  Closes all client connections, stops and running processing threads, and
119     *  closes the host connection.
120     */
121    public void close();
122
123    /**
124     *  Retrieves a hosted connection by ID.
125     */
126    public HostedConnection getConnection( int id );
127
128    /**
129     *  Retrieves a read-only collection of all currently connected connections.
130     */
131    public Collection<HostedConnection> getConnections();
132
133    /**
134     *  Returns true if the server has active connections at the time of this
135     *  call.
136     */
137    public boolean hasConnections();
138
139    /**
140     *  Adds a listener that will be notified when new hosted connections
141     *  arrive.
142     */
143    public void addConnectionListener( ConnectionListener listener );
144
145    /**
146     *  Removes a previously registered connection listener.
147     */
148    public void removeConnectionListener( ConnectionListener listener );
149
150    /**
151     *  Adds a listener that will be notified when any message or object
152     *  is received from one of the clients.
153     *
154     *  <p>Note about MessageListener multithreading: on the server, message events may
155     *  be delivered by more than one thread depending on the server
156     *  implementation used.  Listener implementations should treat their
157     *  shared data structures accordingly and set them up for multithreaded
158     *  access.  The only threading guarantee is that for a single
159     *  HostedConnection, there will only ever be one thread at a time
160     *  and the messages will always be delivered to that connection in the
161     *  order that they were delivered.  This is the only restriction placed
162     *  upon server message dispatch pool implementations.</p>
163     */
164    public void addMessageListener( MessageListener<? super HostedConnection> listener );
165
166    /**
167     *  Adds a listener that will be notified when messages of the specified
168     *  types are received from one of the clients.
169     */
170    public void addMessageListener( MessageListener<? super HostedConnection> listener, Class... classes );
171
172    /**
173     *  Removes a previously registered wildcard listener.  This does
174     *  not remove this listener from any type-specific registrations.
175     */
176    public void removeMessageListener( MessageListener<? super HostedConnection> listener );
177
178    /**
179     *  Removes a previously registered type-specific listener from
180     *  the specified types.
181     */
182    public void removeMessageListener( MessageListener<? super HostedConnection> listener, Class... classes );
183
184
185}
186
187