001/*
002// This software is subject to the terms of the Eclipse Public License v1.0
003// Agreement, available at the following URL:
004// http://www.eclipse.org/legal/epl-v10.html.
005// You must accept the terms of that agreement to use this software.
006//
007// Copyright (C) 2009-2009 Pentaho
008// All Rights Reserved.
009*/
010package mondrian.spi;
011
012import java.sql.Connection;
013import javax.sql.DataSource;
014
015/**
016 * Factory that creates {@link Dialect} objects.
017 *
018 * <p>If you create a class that implements {@link Dialect}, you may optionally
019 * provide a factory by creating a constant field in that class. For
020 * example:</p>
021 *
022 * <pre>
023 * public class MyDialect implements Dialect {
024 *     public static final DialectFactory FACTORY =
025 *         new JdbcDialectFactory(MyDialect.class, null);
026 *
027 *     public MyDialect(Connection connection) {
028 *         ...
029 *     }
030 *
031 *     ...
032 * }</pre>
033 *
034 * <p>(The field must be public, static, final, named "FACTORY", of type
035 * {@link mondrian.spi.DialectFactory} or a subclass, and its value must not be
036 * null.)</p>
037 *
038 * <p>Explicitly providing a factory gives you more control about how dialects
039 * are produced.</p>
040 *
041 * <p>If you do not provide such a field, Mondrian requires that the dialect has
042 * a public constructor that takes a {@link java.sql.Connection} as a parameter,
043 * and automatically creates a factory that calls the class's public
044 * constructor.</p>
045 *
046 * <p>However, an explicit DialectFactory is superior:<ol>
047 * <li>When a dialect cannot handle a given connection, a dialect factory can
048 *     return {@code null}, whereas a dialect's constructor can only throw an
049 *     exception.
050 * <li>A dialect factory can maintain a pool or cache of dialect objects.
051 * </ol>
052 *
053 * <p>If your dialect is a subclass of {@link mondrian.spi.impl.JdbcDialectImpl}
054 * you may wish to use a dialect factory that is a subclass of
055 * {@link mondrian.spi.impl.JdbcDialectFactory}.
056 *
057 * @author jhyde
058 * @since Jan 13, 2009
059 */
060public interface DialectFactory {
061    /**
062     * Creates a Dialect.
063     *
064     * <p>If the dialect cannot handle this connection, returns null.
065     *
066     * @param dataSource JDBC data source
067     * @param connection JDBC connection
068     *
069     * @return dialect for this connection, or null if this factory's dialect
070     * is not appropriate for the connection
071     *
072     * @throws RuntimeException if underlying systems give an error
073     */
074    Dialect createDialect(
075        DataSource dataSource,
076        Connection connection);
077}
078
079// End DialectFactory.java