org.apache.vinci.transport
Class VinciServer

java.lang.Object
  org.apache.vinci.transport.BaseServer
      org.apache.vinci.transport.VinciServer

public class VinciServer
extends BaseServer

"Standard" service container for a VinciServable. This extends BaseServer with functions allowing port negotiation via interaction with VNS. It also provides rudimentary support for service control and monitoring by responding to vinci:SHUTDOWN and vinci:PING. Note that this server class directs requests to a single VinciServable. For many applications it may be desirable to have one server accept requests that get delegated to multiple services, not just a single service. For such applications consider using the MultiplexedServer. You can also implement a VinciServable that implements its own sub-service delegation scheme.

Constructor Summary

VinciServer(java.lang.String service_name, java.lang.String host_name, VinciServable servable)
Create a new server.

VinciServer(java.lang.String service_name, java.lang.String host_name, VinciServable servable, int myPriority)

VinciServer(java.lang.String service_name, java.lang.String host_name, VinciServable servable, int myPriority, int myInstance)
Create a new server.

VinciServer(java.lang.String service_name, VinciServable servable)
Create a new server that reports the current machine's IP address as the host.

VinciServer(java.lang.String service_name, VinciServable servable, int myPriority)

VinciServer(java.lang.String service_name, VinciServable servable, int myPriority, int myInstance)

VinciServer(VinciServable servable)
servable != null

Method Summary

static Transportable	createShutdownCommand(java.lang.String shutdown_message) Factory method for creating a shutdown message.
VinciContext	getContext() Get the context associated with this server.
java.lang.String	getHostName()
int	getInstance()
protected int	getPort()
int	getPriority()
protected java.lang.Runnable	getRunnable(java.net.Socket client) Get a runnable object to run within a pooled thread that will handle the request.
java.lang.String	getServiceName()
int	getServingPort() After invoking serve() or startServing(), this method can be used to determine the port which was negotiated with VNS on which to serve requests.
void	serve() Serve requests until a clean shutdown is triggered.
void	setContext(VinciContext c) Set the VinciContext to be used by this server.
boolean	shutdown(java.lang.String shutdown_message) This method is called by the server when a remote shutdown request is received.
void	startServing() Start a new thread that will serve requests until a clean shutdown is triggered.

Methods inherited from class org.apache.vinci.transport.BaseServer

cleanExit, createServerSocket, eval, getServable, getServerSocket, handleRequest, handleRequests, makeTransportable, serve, setSocketTimeout, setThreadPoolSize, shutdownServing, startServing

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VinciServer

public VinciServer(java.lang.String service_name,
                   java.lang.String host_name,
                   VinciServable servable)

Create a new server. If an incorrect hostname is provided, this server will not be reachable.

Parameters:

host_name - The DNS hostname of the machine running this server.

VinciServer

public VinciServer(java.lang.String service_name,
                   VinciServable servable)
            throws java.net.UnknownHostException

Create a new server that reports the current machine's IP address as the host. This should not be used for DHCP-based hosts since IP address can change.

Throws:

java.net.UnknownHostException - If there is an error determining machine IP address.

VinciServer

public VinciServer(java.lang.String service_name,
                   java.lang.String host_name,
                   VinciServable servable,
                   int myPriority,
                   int myInstance)

Create a new server.

VinciServer

public VinciServer(java.lang.String service_name,
                   java.lang.String host_name,
                   VinciServable servable,
                   int myPriority)

VinciServer

public VinciServer(java.lang.String service_name,
                   VinciServable servable,
                   int myPriority)
            throws java.net.UnknownHostException

Throws:

java.net.UnknownHostException

VinciServer

public VinciServer(java.lang.String service_name,
                   VinciServable servable,
                   int myPriority,
                   int myInstance)
            throws java.net.UnknownHostException

Throws:

java.net.UnknownHostException

VinciServer

public VinciServer(VinciServable servable)

servable != null

Method Detail

getContext

public VinciContext getContext()

Get the context associated with this server. By default clients use the global Vinci context, though this can be overridden.

getPriority

public int getPriority()

getServiceName

public java.lang.String getServiceName()

getInstance

public int getInstance()

getHostName

public java.lang.String getHostName()

getServingPort

public int getServingPort()

After invoking serve() or startServing(), this method can be used to determine the port which was negotiated with VNS on which to serve requests.

Since:

2.0.15

setContext

public void setContext(VinciContext c)

Set the VinciContext to be used by this server. Set to null if you wish the global context to be used.

serve

public void serve()
           throws ServiceDownException,
                  VNSException,
                  java.io.IOException

Serve requests until a clean shutdown is triggered. Note that all three exceptions thrown by this method are IOExceptions so a single IOException catch phrase is sufficient unless it is important to determine the particular failure.

Throws:

ServiceDownException - Thrown if there was a failure to contact VNS for port negotiation.

VNSException - Typically thrown if VNS does not recognize the service provided by this server.

java.io.IOException - Thrown if there was some problem with the server socket.

java.lang.IllegalStateException - if VNS host is not specified.

startServing

public void startServing()
                  throws ServiceDownException,
                         VNSException,
                         java.io.IOException

Start a new thread that will serve requests until a clean shutdown is triggered. Note that all three exceptions thrown by this method are IOExceptions so a single IOException catch phrase is sufficient unless it is important to determine the particular failure. If this method returns without throwing an exception then the port has been determined and a new thread has been launched.

Throws:

ServiceDownException - Thrown if there was a failure to contact VNS for port negotiation.

VNSException - Typically thrown if VNS does not recognize the service provided by this server.

java.io.IOException - Thrown if there was some problem with the server socket.

java.lang.IllegalStateException - if VNS host is not specified.

Since:

2.0.15

getRunnable

protected java.lang.Runnable getRunnable(java.net.Socket client)

Description copied from class: BaseServer

Get a runnable object to run within a pooled thread that will handle the request.

Overrides:

getRunnable in class BaseServer

createShutdownCommand

public static Transportable createShutdownCommand(java.lang.String shutdown_message)

Factory method for creating a shutdown message. Send the returned object to any server, and if it is programmed to respond to shutdown, it will do so.

Parameters:

shutdown_message - Should be used to pass a message explaining the shutdown, or in the future it may also include authentication information for password-protected shutdown.

shutdown

public boolean shutdown(java.lang.String shutdown_message)

This method is called by the server when a remote shutdown request is received. In general if you want to stop the server call shutdownServing() -- this method should have probably been declared "protected". You can override this method if you want the shutdown message to be ignored in certain cases.

getPort

protected int getPort()
               throws ServiceDownException,
                      VNSException

Throws:

java.lang.IllegalStateException - if VNS host isn't specified.

ServiceDownException

VNSException