com.marklogic.xcc.spi.ConnectionProvider Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of marklogic-xcc Show documentation
MarkLogic XML Contentbase Connector for Java (XCC/J)
There is a newer version: 11.3.0
/*
 * Copyright 2003-2019 MarkLogic Corporation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.marklogic.xcc.spi;

import java.io.IOException;
import java.util.logging.Logger;

import com.marklogic.xcc.Request;
import com.marklogic.xcc.Session;

/**
 * This interface defines a provider of Sockets for a {@link com.marklogic.xcc.ContentSource}.
 * Policies such as load balancing or failover can be implemented by supplying a custom
 * ConnectionProvider.
 */
public interface ConnectionProvider {
    /**
     * 
     * Provide a {@link 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
     * {@link com.marklogic.xcc.Request} parameter. Code ported from earlier XCC releases will need
     * to be modified to add the new parameter.
     * 
     * 
     * @param session
     *            The {@link com.marklogic.xcc.Session} requesting a connection.
     * @param request
     *            The {@link com.marklogic.xcc.Request} that is about to be submitted on the
     *            connection.
     * @param logger
     *            A {@link java.util.logging.Logger} instance to use. @return An open, ready to use
     *            {@link ServerConnection} object.
     * @throws java.io.IOException
     *             If an underlying connection cannot be created.
     * @return An initialized {@link com.marklogic.xcc.spi.ServerConnection} instance.
     */
    ServerConnection obtainConnection(Session session, Request request, Logger logger) throws IOException;

    /**
     * Return a {@link ServerConnection} object (obtained from a previous call to
     * {@link #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 ({@link com.marklogic.xcc.spi.ServerConnection#setTimeoutMillis(long)}),
     * that value will inform the provider to discard the object after that amount of time has
     * elapsed.
     * 
     * @param connection
     *            A previously obtained {@link ServerConnection} instance.
     * @param logger
     *            A {@link Logger} instance to use.
     */
    void returnConnection(ServerConnection connection, Logger logger);

    /**
     * Return a connection that experienced an error. The provider will indicate the action the
     * client should take.
     * 
     * @param connection
     *            A previously obtained {@link ServerConnection} instance.
     * @param exception
     *            The (possibly null) exception that occurred. The provider may wish to decide which
     *            action to recommend depending on the type of exception.
     * @param logger
     *            A {@link Logger} instance to use.
     * @return An instance of {@link ConnectionErrorAction} instance that advises the client which
     *         action to take.
     */
    ConnectionErrorAction returnErrorConnection(ServerConnection connection, Throwable exception, Logger logger);

    /**
     * Tell the provider to shutdown and release any resources being used. It's possible this method
     * may never be called.
     * 
     * @param logger
     *            A {@link Logger} instance to use.
     */
    void shutdown(Logger logger);
    
    /**
     * Close expired resource in the provider pool.
     * 
     * @param currTime Current time to use for expired status check.
     */
    void closeExpired(long currTime);

    /**
     * Return the port of the connection provider
     * 
     * @return port number
     */
    int getPort();

    /**
     * Return the host name of the connection provider
     * 
     * @return the string of host name
     */
    String getHostName();
}