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

    All Methods Instance Methods Abstract Methods
    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

Copyright © 2025 MarkLogic Corporation. All Rights Reserved.

Complete online documentation for MarkLogic Server, XQuery and related components may be found at developer.marklogic.com