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.protocol.ICommand;
021    
022    /**
023     * Defines contract for the connection to the OpenTick service.
024     * <p/>
025     * This is the central interface of the API. It allows one to
026     * prepare and submit a request for data.
027     * <p/>
028     * Note that connection is asynchronous, which means that connection/login 
029     * process might still
030     * be in progress by the time user gets object implementing this interface.
031     * But even if so, nothing prevents user from using it: submitted requests
032     * will be queued and sent as soon as connection is established.
033     * <p/>
034     * Implementations must be thread-safe. All implementations 
035     * provided by <code>org.otfeed</code> driver are thread-safe.
036     */
037    public interface IConnection {
038    
039            /**
040             * Closes connection to the server.
041             *
042             * All pending requests will receive onError message.
043             */
044            public void shutdown();
045    
046            /**
047             * Blocks till connection terminates (on error, or as a result of
048             * calling shutdown() method).
049             */
050            public void waitForCompletion();
051    
052            /**
053             * Blocks for the earliest of (i) connection termination, or (ii)
054             * timeout expiration.
055             *
056             * @param millis for how long to block.
057             * @return true if connection has terminated, false if
058             *          timeout has expired.
059             */
060            public boolean waitForCompletion(long millis);
061    
062            /**
063             * Schedules a job for execution in the event-dispatching thread.
064             * All listener methods are called by event-dispatching thread.
065             * To avoid a need to make listener objects thread-safe, programmer
066             * can instead use this method when there is a need to interact
067             * with listener objects from a different thread.
068             *
069             * Note that these jobs will be executed in order they were sumbitted.
070             * Also, these jobs are considered a priority for the event thread.
071             *
072             * @param job a job to be submitted.
073             */
074            public void runInEventThread(Runnable job);
075    
076            /**
077             * Prepares a request. This is the main functionality
078             * of {@link IConnection} interface. It allowas caller to
079             * prepare a request to the OpenTick server.
080             * <p>
081             * Command parameter must be one of the known request 
082             * commands, see {@link org.otfeed.command} package.
083             * 
084             * See also: {@link IRequest}.
085             *
086             * @param command object describing request parameters. 
087             *
088             * @return IRequest handle.
089             */
090            public IRequest prepareRequest(ICommand command);
091    }