org.apache.vinci.transport

Class VinciClient

java.lang.Object

org.apache.vinci.transport.BaseClient

org.apache.vinci.transport.VinciClient

public class VinciClient
extends BaseClient

Class for conjuring a Vinci service. Adds VNS resolution to BaseClient. Extends BaseClient with static "sendAndReceive" and "rpc" methods for convenient support of one-shot queries.

Field Summary

Fields inherited from class org.apache.vinci.transport.BaseClient

DEFAULT_CONNECT_TIMEOUT, DEFAULT_SOCKET_TIMEOUT

Constructor Summary

Constructors

Constructor and Description
VinciClient() Construct a new client WITHOUT opening a connection, using the VinciFrame factory to create return documents.
VinciClient(String service_name) Construct a new client connected to the requested service, and uses a VinciFrame factory to create the return document type.
VinciClient(String service_name, int connectTimeout) Construct a new client connected to the requested service, and uses a VinciFrame factory to create the return document type.
VinciClient(String service_name, TransportableFactory factory) Constructs a new client connected to the requested service.
VinciClient(String service_name, TransportableFactory factory, int connectTimeout) Constructs a new client connected to the requested service.
VinciClient(String service_name, TransportableFactory factory, VinciContext myContext)
VinciClient(String service_name, TransportableFactory factory, VinciContext myContext, int connectTimeout) Constructs a new client connected to the requested service.
VinciClient(String service_name, VinciContext myContext)
VinciClient(String service_name, VinciContext myContext, int connectTimeout) Constructs a new client connected to the requested service.
VinciClient(TransportableFactory f) Construct a new client WITHOUT opening a connection, using the specified factory to create return documents.

Method Summary

Modifier and Type	Method and Description
VinciContext	getContext() Get the context associated with this client.
int	getInstance() Get the instance number of this service.
int	getLevel() Get the priority level of the service to which this client is connected.
String	getQualifiedServiceName() Get the fully qualified name of this service.
String	getServiceName()
protected boolean	isSocketKeepAliveEnabled() Gets wheter socket keepAlive is enabled.
static void	main(String[] args)
void	open(String service_name) Connects the client to the specified service as delegated by VNS.
protected void	reopen(Exception e)
static VinciFrame	rpc(Transportable in, String service_name) Same as VinciClient.sendAndReceive(Transportable) except for return type.
static VinciFrame	rpc(Transportable in, String service_name, int timeout) Same as VinciClient.sendAndReceive(Transportable, service_name) except it also takes a timeout value.
static VinciFrame	rpc(Transportable in, String service_name, int timeout, int connect_timeout) Same as VinciClient.sendAndReceive(Transportable, service_name) except it also takes socket read and socket connect timeout values.
static Transportable	sendAndReceive(Transportable in, String service_name, TransportableFactory factory) Convenience method for "one-shot"/single-query connections.
static Transportable	sendAndReceive(Transportable in, String service_name, TransportableFactory factory, int socket_timeout) Convenience method for "one-shot"/single-query connections.
static Transportable	sendAndReceive(Transportable in, String service_name, TransportableFactory factory, int socket_timeout, int connect_timeout) Convenience method for "one-shot"/single-query connections.
void	setContext(VinciContext c) Set the VinciContext to be used by this client.

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

close, getHeader, getHost, getPort, getSocket, getSocketTimeout, isOpen, open, open, open, receive, rpc, rpc, rpc, send, sendAndReceive, sendAndReceive, sendAndReceive, sendAndReceive, sendAndReceive, sendAndReceive, sendAndReceive, sendAndReceiveWork, sendAndReceiveWork, setConnectTimeout, setRetry, setSocketTimeout, setTransportableFactory

Methods inherited from class java.lang.Object

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

Constructor Detail

VinciClient

public VinciClient(String service_name)
            throws ServiceDownException,
                   VNSException

Construct a new client connected to the requested service, and uses a VinciFrame factory to create the return document type.

Parameters:

service_name - The name of the service to connect to.

Throws:

ServiceDownException - -

VNSException - -

IllegalStateException - if no VNS_HOST has been specified.

VinciClient

public VinciClient(String service_name,
                   TransportableFactory factory)
            throws ServiceDownException,
                   VNSException

Constructs a new client connected to the requested service. Consults VNS for the proper host and port to connect to. Service names must be properly qualified.

Parameters:

service_name - The name of the service to connect to.

factory - The factory used for creating return documents of desired type.

Throws:

ServiceDownException - -

VNSException - -

IllegalStateException - if no VNS_HOST has been specified.

VinciClient

public VinciClient(String service_name,
                   TransportableFactory factory,
                   VinciContext myContext)
            throws ServiceDownException,
                   VNSException

Parameters:

service_name - -

factory - -

myContext - -

Throws:

ServiceDownException - -

VNSException - -

IllegalStateException - if no VNS_HOST has been specified.

VinciClient

public VinciClient(String service_name,
                   VinciContext myContext)
            throws ServiceDownException,
                   VNSException

Parameters:

service_name - -

myContext - -

Throws:

ServiceDownException - -

VNSException - -

IllegalStateException - if no VNS_HOST has been specified.

VinciClient

public VinciClient(String service_name,
                   int connectTimeout)
            throws ServiceDownException,
                   VNSException

Construct a new client connected to the requested service, and uses a VinciFrame factory to create the return document type.

Parameters:

service_name - The name of the service to connect to.

connectTimeout - The number of milliseconds that will elapse before a connect attempt fails.

Throws:

ServiceDownException - -

VNSException - -

IllegalStateException - if no VNS_HOST has been specified.

VinciClient

public VinciClient(String service_name,
                   TransportableFactory factory,
                   int connectTimeout)
            throws ServiceDownException,
                   VNSException

Constructs a new client connected to the requested service. Consults VNS for the proper host and port to connect to. Service names must be properly qualified.

Parameters:

service_name - The name of the service to connect to.

factory - The factory used for creating return documents of desired type.

connectTimeout - The number of milliseconds that will elapse before a connect attempt fails.

Throws:

ServiceDownException - -

VNSException - -

IllegalStateException - if no VNS_HOST has been specified.

VinciClient

public VinciClient(String service_name,
                   TransportableFactory factory,
                   VinciContext myContext,
                   int connectTimeout)
            throws ServiceDownException,
                   VNSException

Constructs a new client connected to the requested service.

Parameters:

service_name - -

factory - -

myContext - -

connectTimeout - -

Throws:

ServiceDownException - -

VNSException - -

IllegalStateException - if no VNS_HOST has been specified.

VinciClient

public VinciClient(String service_name,
                   VinciContext myContext,
                   int connectTimeout)
            throws ServiceDownException,
                   VNSException

Constructs a new client connected to the requested service.

Parameters:

service_name - -

myContext - -

connectTimeout - -

Throws:

ServiceDownException - -

VNSException - -

IllegalStateException - if no VNS_HOST has been specified.

VinciClient

public VinciClient()

Construct a new client WITHOUT opening a connection, using the VinciFrame factory to create return documents.

VinciClient

public VinciClient(TransportableFactory f)

Construct a new client WITHOUT opening a connection, using the specified factory to create return documents.

Parameters:

f - -

Method Detail

getLevel

public int getLevel()

Get the priority level of the service to which this client is connected. This method only works after the connection has been opened.

Returns:

-

getInstance

public int getInstance()

Get the instance number of this service. This method only works after the connection has been opened. Services should have "non zero" instance numbers only when more than one instance of the service is running on the same host. The unique instance value allows each instance to be distinguished and uniquely addressed via a fully qualified service name.

Returns:

-

sendAndReceive

public static Transportable sendAndReceive(Transportable in,
                                           String service_name,
                                           TransportableFactory factory)
                                    throws IOException,
                                           ServiceException,
                                           ServiceDownException,
                                           VNSException

Convenience method for "one-shot"/single-query connections. Equivalent of manually creating a new VinciClient(), calling (non-static) sendAndReceive, and then closing the client.

Parameters:

in - -

service_name - -

factory - -

Returns:

-

Throws:

IOException - -

ServiceException - -

ServiceDownException - -

VNSException - -

IllegalStateException - if the VNS host has not been specified.

sendAndReceive

public static Transportable sendAndReceive(Transportable in,
                                           String service_name,
                                           TransportableFactory factory,
                                           int socket_timeout)
                                    throws IOException,
                                           ServiceException

Convenience method for "one-shot"/single-query connections. Equivalent of manually creating a new VinciClient(), calling (non-static) sendAndReceive, and then closing the client.

Parameters:

in - -

service_name - -

factory - -

socket_timeout - -

Returns:

-

Throws:

IOException - -

ServiceException - -

IllegalStateException - if the VNS host has not been specified.

sendAndReceive

public static Transportable sendAndReceive(Transportable in,
                                           String service_name,
                                           TransportableFactory factory,
                                           int socket_timeout,
                                           int connect_timeout)
                                    throws IOException,
                                           ServiceException

Convenience method for "one-shot"/single-query connections. Equivalent of manually creating a new VinciClient(), calling (non-static) sendAndReceive, and then closing the client.

Parameters:

in - -

service_name - -

factory - -

socket_timeout - -

connect_timeout - -

Returns:

-

Throws:

IOException - -

ServiceException - -

IllegalStateException - if the VNS host has not been specified.

getContext

public VinciContext getContext()

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

Returns:

-

setContext

public void setContext(VinciContext c)

Set the VinciContext to be used by this client. Set to null if you wish the global context to be used. You should set the context BEFORE a connection is open (e.g. ater using the no-arg constructor), otherwise the global context parameters will be used to establish the connection before you have a chance to change it.

Parameters:

c - -

getQualifiedServiceName

public String getQualifiedServiceName()

Get the fully qualified name of this service. This method is useful when for whatever reason a connection needs to be re-established with this exact same service instance. This method only works after connection has been established.

Returns:

-

getServiceName

public String getServiceName()

open

public void open(String service_name)
          throws ServiceDownException,
                 VNSException

Connects the client to the specified service as delegated by VNS. Use this open method in conjunction with the no-arg VinciClient constructor.

Parameters:

service_name - The name of the service to connect to.

Throws:

ServiceDownException - Thrown when either (1) VNS is inaccessible or (2) none of the servers registered under serviceName are accessible.

VNSException - Thrown when VNS is accessible but reports an error, which should almost always indicate that the requested service is not registered.

IllegalStateException - if no VNS_HOST has been specified.

reopen

protected void reopen(Exception e)
               throws IOException

Overrides:

reopen in class BaseClient

Parameters:

e - -

Throws:

IOException - -

isSocketKeepAliveEnabled

protected boolean isSocketKeepAliveEnabled()

Gets wheter socket keepAlive is enabled. This overrides the method in BaseClient, and makes this setting configurable through the VinciContext.

Overrides:

isSocketKeepAliveEnabled in class BaseClient

Returns:

whether socket keepAlive is enabled.

rpc

public static VinciFrame rpc(Transportable in,
                             String service_name)
                      throws IOException,
                             ServiceException,
                             ServiceDownException,
                             VNSException

Same as VinciClient.sendAndReceive(Transportable) except for return type. Syntactic sugar method for the case where return result is known to be VinciFrame (eliminates the need for casting in the typical usage case).

Parameters:

in - -

service_name - -

Returns:

A VinciFrame representing the service result.

Throws:

IllegalStateException - if the VNS host has not been specified.

IOException - -

ServiceException - -

ServiceDownException - -

VNSException - -

rpc

public static VinciFrame rpc(Transportable in,
                             String service_name,
                             int timeout)
                      throws IOException,
                             ServiceException,
                             ServiceDownException,
                             VNSException

Same as VinciClient.sendAndReceive(Transportable, service_name) except it also takes a timeout value. WARNING: This method "hides" the BaseClient rpc method with the same signature. The BaseClient method accepts (Transportable, host string, port) whereas this one accepts (Transportable, service_name, timeout). Despite the equivalent signatures, the semantics of these two methods are quite different.

Parameters:

in - -

service_name - -

timeout - -

Returns:

A VinciFrame representing the service result.

Throws:

IOException - -

ServiceException - -

ServiceDownException - -

VNSException - -

rpc

public static VinciFrame rpc(Transportable in,
                             String service_name,
                             int timeout,
                             int connect_timeout)
                      throws IOException,
                             ServiceException,
                             ServiceDownException,
                             VNSException

Same as VinciClient.sendAndReceive(Transportable, service_name) except it also takes socket read and socket connect timeout values. WARNING: This method "hides" the BaseClient rpc method with the same signature. The BaseClient method accepts (Transportable, host string, port) whereas this one accepts (Transportable, service_name, timeout). Despite the equivalent signatures, the semantics of these two methods are quite different.

Parameters:

in - -

service_name - -

timeout - -

connect_timeout - -

Returns:

A VinciFrame representing the service result.

Throws:

IOException - -

ServiceException - -

ServiceDownException - -

VNSException - -

main

public static void main(String[] args)
                 throws Exception

Throws:

Exception