org.eclipse.persistence.sessions.Connector Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of eclipselink Show documentation

EclipseLink build based upon Git transaction f2b9fc5

There is a newer version: 5.0.0-B03

/*
 * Copyright (c) 1998, 2020 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0,
 * or the Eclipse Distribution License v. 1.0 which is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
 */

// Contributors:
//     Oracle - initial API and implementation from Oracle TopLink
package org.eclipse.persistence.sessions;

import java.util.*;
import java.sql.*;
import java.io.*;

/**
 * Purpose:
 * Define an interface for supplying TopLink with a Connection to
 * a JDBC database.
 * 
 * Description:
 * This interface defines the methods to be implemented that allow TopLink to
 * acquire a Connection to a JDBC database. There are only 2
 * methods that need to be implemented:
 * 

 * java.sql.Connection connect(java.util.Properties properties)

 * void toString(java.io.PrintWriter writer)
 * 
 * Once these methods have been implemented, an instance of the new
 * Connector can be  passed
 * to a JDBCLogin at startup. For example:
 * 
 * session.getLogin().setConnector(new FooConnector());

 * session.login();
 * 
 *
 * @see DatabaseLogin
 * @author Big Country
 * @since TOPLink/Java 2.1
 */
public interface Connector extends Serializable, Cloneable {

    /**
     * INTERNAL:
     * Must be cloneable.
     */
    Object clone();

    /**
     * INTERNAL:
     * Connect with the specified properties and return the Connection.
     * The properties are driver-specific; but usually contain the "user"
     * and "password". Additional
     * properties can be built by using JDBCLogin.setProperty(String propertyName,
     * Object propertyValue).
     * @return java.sql.Connection
     */
    Connection connect(Properties properties, Session session);

    /**
     * INTERNAL:
     * Print something useful on the log. This information will be displayed
     * on the EclipseLink log (by default System.out) at login.
     * See the other implementations of this method for examples.
     */
    void toString(PrintWriter writer);

    /**
     * INTERNAL:
     * Provide the details of my connection information. This is primarily for JMX runtime services.
     * @return java.lang.String
     */
    String getConnectionDetails();
}