1 // Copyright (c) 2009 The Chromium Authors. All rights reserved.

     2 // Use of this source code is governed by a BSD-style license that can be

     3 // found in the LICENSE file.

     4 

     5 package org.chromium.sdk;

     6 

     7 import java.io.IOException;

     8 import java.util.List;

     9 

    10 /**

    11  * An "entry point" of the SDK. A Browser instance is usually constructed once

    12  * per a debugged browser instance.

    13  */

    14 public interface Browser {

    15 

    16   /**

    17    * Establishes the browser connection and checks for the protocol version

    18    * supported by the remote, then creates object that downloads list of tabs.

    19    *

    20    * @return new instance of TabFetcher that must be dismissed after use to control

    21    *         connection use

    22    * @throws IOException if there was a transport layer error

    23    * @throws UnsupportedVersionException if the SDK protocol version is not

    24    *         compatible with that supported by the browser

    25    */

    26   TabFetcher createTabFetcher() throws IOException, UnsupportedVersionException;

    27 

    28 

    29   /**

    30    * Helps to fetch currently opened browser tabs. It also holds open connection to

    31    * browser. After instance was used {@code #dismiss} should be called to release

    32    * connection. {@link TabConnector#isAlreadyAttached()} helps to tell which

    33    * tabs are available for connection.

    34    */

    35   interface TabFetcher {

    36     /**

    37      * Retrieves all browser tabs currently opened. It lists all tabs, including

    38      * those already attached.

    39      *

    40      * @return tabs that can be debugged in the associated Browser instance. An

    41      *         empty list is returned if no tabs are available.

    42      * @throws IOException if there was a transport layer failure

    43      * @throws IllegalStateException if this method is called while another

    44      *         invocation of the same method is in flight, or the Browser instance

    45      *         is not connected

    46      */

    47     List<? extends TabConnector> getTabs() throws IOException, IllegalStateException;

    48 

    49     /**

    50      * Should release connection. If no browser tabs is attached at the moment,

    51      * connection may actually close.

    52      */

    53     void dismiss();

    54   }

    55 

    56   /**

    57    * Tab list item that is fetched from browser. Connector may correspond to a tab,

    58    * which is already attached. Connector is used to attach to tab.

    59    */

    60   interface TabConnector {

    61     /**

    62      * @return tab url that should be shown to user to let him select one tab from list

    63      */

    64     String getUrl();

    65 

    66     /**

    67      * @return true if the tab is already attached at this moment

    68      */

    69     boolean isAlreadyAttached();

    70 

    71     /**

    72      * Attaches to the related tab debugger.

    73      *

    74      * @param listener to report the debug events to

    75      * @return null if operation failed

    76      */

    77     BrowserTab attach(TabDebugEventListener listener) throws IOException;

    78   }

    79 }