amip.api.highlevel
Class Server

java.lang.Object
  extended by amip.api.highlevel.Server

public class Server
extends java.lang.Object

Server class operates the server on your side. Server is required when you want to receive events and messages from AMIP. Server opens a socket on the specified address and listens for AMIP connections. This class also provides access to the EventListenerManager. Only one instance of Server can be created. To get the Server instance, use getInstance() method. Once you have it, you need to start the server. Server must be stopped when you exit your application.


Method Summary
static int findFreeLocalPort()
          The same as findFreePort(), but looks for free port only on the local address.
static int findFreelPort(java.lang.String iface)
          Searches for the free port in range on the specified interface.
static int findFreePort()
          Helper method to find a free port for the server.
 java.lang.String getBindAddress()
           
 EventListenerManager getEventListenersManager()
          Provides access to EventListenerManager useful when you need to receive events from AMIP.
 java.lang.String getExternalAddress()
          This method returns an external address of the server, which equals to bindAddress by default or null if bindAddress is "0.0.0.0" and externalAddress was not explicitly set.
static Server getInstance()
          Gets the Server instance, this is the only way to get the Server object.
 int getPort()
           
 boolean isStarted()
           
 void setBindAddress(java.lang.String bindAddress)
           
 void setExternalAddress(java.lang.String externalAddress)
          You only need to set it if you start your server on all the addresses available on your machine.
 void setPort(int port)
           
 void start()
          Starts the server on 127.0.0.1:60334 or another address and port previously specified by setBindAddress and setPort methods.
 void start(java.lang.String bindAddress, int port)
          Starts the server on the specified bindAddress and port. bindAddress must be a valid network address, use 127.0.0.1 to start server on the localhost.
 void stop()
          Stops the server, you must stop it before your application is terminated.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

start

public void start(java.lang.String bindAddress,
                  int port)
           throws ServerStartupFailedException
Starts the server on the specified bindAddress and port. bindAddress must be a valid network address, use 127.0.0.1 to start server on the localhost. If you expect connections from the AMIP installed on another machine, you have to either start server on the external address which is visible by that machine or start it on all the addresses your machine has by specifying "0.0.0.0" as a bindAddress. If you start server on all the addresses, you must specify the external address using the setExternalAddress(java.lang.String) method, this address is passed to AMIP so that it knows where it should connect.

Parameters:
bindAddress - valid IP address of your machine, or 127.0.0.1 if AMIP is on the same machine, or 0.0.0.0 if you want to listen on all addresses.
port - port to start the server on, use one of the ports which is free or get one using the findFreePort method.
Throws:
ServerStartupFailedException - if server was not started, usually it happens if this port is already taken by another application or specified IP address is invalid.

start

public void start()
           throws ServerStartupFailedException
Starts the server on 127.0.0.1:60334 or another address and port previously specified by setBindAddress and setPort methods.

Throws:
ServerStartupFailedException - if the server cannot be started (usually when port is already in use or specified inerface doesn't exist).

stop

public void stop()
Stops the server, you must stop it before your application is terminated.


getInstance

public static Server getInstance()
Gets the Server instance, this is the only way to get the Server object.

Returns:
instance of the Server.

getEventListenersManager

public EventListenerManager getEventListenersManager()
Provides access to EventListenerManager useful when you need to receive events from AMIP.

Returns:
EventListenerManager instance.

getBindAddress

public java.lang.String getBindAddress()

setBindAddress

public void setBindAddress(java.lang.String bindAddress)

getPort

public int getPort()

setPort

public void setPort(int port)

isStarted

public boolean isStarted()

getExternalAddress

public java.lang.String getExternalAddress()
This method returns an external address of the server, which equals to bindAddress by default or null if bindAddress is "0.0.0.0" and externalAddress was not explicitly set.

Returns:
external server IP address or null if server is listening on all addresses and externalAddress was not explicitly set.

setExternalAddress

public void setExternalAddress(java.lang.String externalAddress)
You only need to set it if you start your server on all the addresses available on your machine.

Parameters:
externalAddress - machine external address.

findFreePort

public static int findFreePort()
Helper method to find a free port for the server. The port is considered free only if it's possible to bind to this port using each of the available network interfaces.

Returns:
free port or -1 if no free port was found within certain limits.

findFreeLocalPort

public static int findFreeLocalPort()
The same as findFreePort(), but looks for free port only on the local address.

Returns:
free port or -1 if not found

findFreelPort

public static int findFreelPort(java.lang.String iface)
Searches for the free port in range on the specified interface.

Parameters:
iface - network interface IP address in a string form
Returns:
free port or -1 if not found