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 33 package com.jme3.network; 34 35 import 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 */ 44 public 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
