com.marklogic.xcc.spi

Interface ConnectionProvider

public interface ConnectionProvider

This interface defines a provider of Sockets for a ContentSource. Policies such as load balancing or failover can be implemented by supplying a custom ConnectionProvider.

Method Summary

Modifier and Type	Method and Description
void	closeExpired(long currTime) Close expired resource in the provider pool.
java.lang.String	getHostName() Return the host name of the connection provider
int	getPort() Return the port of the connection provider
ServerConnection	obtainConnection(Session session, Request request, java.util.logging.Logger logger) Provide a ServerConnection) that is open and ready to communicate with the server.
void	returnConnection(ServerConnection connection, java.util.logging.Logger logger) Return a ServerConnection object (obtained from a previous call to obtainConnection(com.marklogic.xcc.Session,com.marklogic.xcc.Request,java.util.logging.Logger) ) to the provider, possibly to be pooled and re-used.
ConnectionErrorAction	returnErrorConnection(ServerConnection connection, java.lang.Throwable exception, java.util.logging.Logger logger) Return a connection that experienced an error.
void	shutdown(java.util.logging.Logger logger) Tell the provider to shutdown and release any resources being used.

Method Detail

obtainConnection

ServerConnection obtainConnection(Session session,
                                  Request request,
                                  java.util.logging.Logger logger)
                           throws java.io.IOException

Provide a ServerConnection) that is open and ready to communicate with the server.

Note: The signature of this method changed in the 4.0 release to add the Request parameter. Code ported from earlier XCC releases will need to be modified to add the new parameter.

Parameters:

session - The Session requesting a connection.

request - The Request that is about to be submitted on the connection.

logger - A Logger instance to use. @return An open, ready to use ServerConnection object.

Returns:

An initialized ServerConnection instance.

Throws:

java.io.IOException - If an underlying connection cannot be created.

returnConnection

void returnConnection(ServerConnection connection,
                      java.util.logging.Logger logger)

Return a ServerConnection object (obtained from a previous call to obtainConnection(com.marklogic.xcc.Session,com.marklogic.xcc.Request,java.util.logging.Logger) ) to the provider, possibly to be pooled and re-used. If the connection has a non-zero timeout value set (ServerConnection.setTimeoutMillis(long)), that value will inform the provider to discard the object after that amount of time has elapsed.

Parameters:

connection - A previously obtained ServerConnection instance.

logger - A Logger instance to use.

returnErrorConnection

ConnectionErrorAction returnErrorConnection(ServerConnection connection,
                                            java.lang.Throwable exception,
                                            java.util.logging.Logger logger)

Return a connection that experienced an error. The provider will indicate the action the client should take.

Parameters:

connection - A previously obtained ServerConnection instance.

exception - The (possibly null) exception that occurred. The provider may wish to decide which action to recommend depending on the type of exception.

logger - A Logger instance to use.

Returns:

An instance of ConnectionErrorAction instance that advises the client which action to take.

shutdown

void shutdown(java.util.logging.Logger logger)

Tell the provider to shutdown and release any resources being used. It's possible this method may never be called.

Parameters:

logger - A Logger instance to use.

closeExpired

void closeExpired(long currTime)

Close expired resource in the provider pool.

Parameters:

currTime - Current time to use for expired status check.

getPort

int getPort()

Return the port of the connection provider

Returns:

port number

getHostName

java.lang.String getHostName()

Return the host name of the connection provider

Returns:

the string of host name