001    /**
002     * Copyright 2007 Mike Kroutikov.
003     *
004     * This program is free software; you can redistribute it and/or modify
005     *   it under the terms of the Lesser GNU General Public License as 
006     *   published by the Free Software Foundation; either version 3 of
007     *   the License, or (at your option) any later version.
008     *
009     *   This program is distributed in the hope that it will be useful,
010     *   but WITHOUT ANY WARRANTY; without even the implied warranty of
011     *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
012     *   Lesser GNU General Public License for more details.
013     *
014     *   You should have received a copy of the Lesser GNU General Public License
015     *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
016     */
017    
018    package org.otfeed;
019    
020    import org.otfeed.event.IConnectionStateListener;
021    
022    
023    /**
024     * Defines contract for the connection factory service.
025     * <p/>
026     * This is the central interface of the <code>org.otfeed</code> API. 
027     * It allows one to establish a connection to the
028     * OpenTick server.
029     * <p/>
030     * Implementations must be thread-safe. All implementations provided
031     * by <code>org.otfeed</code> driver are thread-safe.
032     */
033    public interface IConnectionFactory {
034    
035            /**
036             * Please use {@link #connect(OTConnectionSpec, IConnectionStateListener)}
037             * method.
038             */
039            @Deprecated
040            public IConnection connect(IConnectionStateListener listener);
041            
042            /**
043             * Connects to the server. This call does not block, the
044             * connection process is started asynchronously, in
045             * a separate thread (event-dispatching thread).
046             * <p/>
047             * To monitor connection progress, supply <code>listener</code>
048             * parameter.
049             * 
050             * @param spec connection specification. Some implementations may accept
051             *                 null value, which would mean to use some default values
052             *                 for the connection parameters.
053             * @param listener listener to receive connection state events. This parameter
054             *                 may be null, to indicate that there is no interest in monitoring
055             *                 connection status.
056             * 
057             * @return connection.
058             */
059            public IConnection connect(OTConnectionSpec spec, IConnectionStateListener listener);
060    }