| /******************************************************************************* |
| * Copyright (c) 2006, 2011 Wind River Systems, Inc. and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * Michael Scharf (Wind River) - initial API and implementation |
| * Martin Oberhuber (Wind River) - fixed copyright headers and beautified |
| * Martin Oberhuber (Wind River) - [261486][api][cleanup] Mark @noimplement interfaces as @noextend |
| * Uwe Stieber (Wind River) - [282996] [terminal][api] Add "hidden" attribute to terminal connector extension point |
| *******************************************************************************/ |
| package org.eclipse.tm.internal.terminal.provisional.api; |
| |
| import java.io.OutputStream; |
| |
| import org.eclipse.core.runtime.IAdaptable; |
| import org.eclipse.tm.internal.terminal.control.ITerminalViewControl; |
| import org.eclipse.tm.internal.terminal.provisional.api.provider.TerminalConnectorImpl; |
| |
| /** |
| * A contributed connection type to manage a single connection. |
| * |
| * Implementations of this class are contributed through the |
| * <code>org.eclipse.tm.terminal.terminalConnectors</code> extension point. This |
| * class gives access to the static markup of a terminal connector extension as |
| * well as providing the lifecycle management for the dynamically loaded |
| * {@link TerminalConnectorImpl} instance, which performs the actual |
| * communications. This pattern allows for lazy initialization, bundle |
| * activation and class loading of the actual {@link TerminalConnectorImpl} |
| * instance. |
| * |
| * Clients can get terminal connector instances from the |
| * {@link TerminalConnectorExtension} class, or from |
| * {@link ITerminalViewControl#getTerminalConnector()} when running inside an |
| * active terminal widget. |
| * |
| * @noimplement This interface is not intended to be implemented by clients. |
| * @noextend This interface is not intended to be extended by clients. |
| * |
| * @author Michael Scharf |
| * <p> |
| * <strong>EXPERIMENTAL</strong>. This class or interface has been added |
| * as part of a work in progress. There is no guarantee that this API |
| * will work or that it will remain the same. Please do not use this API |
| * without consulting with the <a |
| * href="http://www.eclipse.org/tm/">Target Management</a> team. |
| * </p> |
| */ |
| public interface ITerminalConnector extends IAdaptable { |
| /** |
| * @return an ID of this connector. The id from the plugin.xml. |
| * @since org.eclipse.tm.terminal 2.0 |
| */ |
| String getId(); |
| |
| /** |
| * @return <code>null</code> the name (as specified in the plugin.xml) |
| * @since org.eclipse.tm.terminal 2.0 |
| */ |
| String getName(); |
| |
| /** |
| * @return <code>True</code> if the connector is not visible in user |
| * selections. |
| * @since org.eclipse.tm.terminal 3.0.1 |
| */ |
| boolean isHidden(); |
| |
| /** |
| * @return true if the {@link TerminalConnectorImpl} has been initialized. |
| * If there was an initialization error, {@link #getInitializationErrorMessage()} |
| * returns the error message. |
| * @since org.eclipse.tm.terminal 2.0 |
| */ |
| boolean isInitialized(); |
| |
| /** |
| * This method initializes the connector if it is not initialized! |
| * If the connector was initialized successfully, <code>null</code> is |
| * returned. Otherwise an error message describing the problem is returned. |
| * @return <code>null</code> or a localized error message. |
| * @since org.eclipse.tm.terminal 2.0 |
| */ |
| String getInitializationErrorMessage(); |
| |
| /** |
| * Connect using the current state of the settings. |
| * @param control Used to inform the UI about state changes and messages from the connection. |
| */ |
| void connect(ITerminalControl control); |
| |
| /** |
| * Disconnect if connected. Else do nothing. |
| */ |
| void disconnect(); |
| |
| /** |
| * @return true if a local echo is needed. |
| * TODO:Michael Scharf: this should be handed within the connection.... |
| */ |
| boolean isLocalEcho(); |
| |
| /** |
| * Notify the remote site that the size of the terminal has changed. |
| * @param newWidth |
| * @param newHeight |
| */ |
| void setTerminalSize(int newWidth, int newHeight); |
| |
| /** |
| * @return the terminal to remote stream (bytes written to this stream will |
| * be sent to the remote site). For the stream in the other direction (remote to |
| * terminal see {@link ITerminalControl#getRemoteToTerminalOutputStream()} |
| * @since org.eclipse.tm.terminal 2.0 |
| */ |
| OutputStream getTerminalToRemoteStream(); |
| |
| /** |
| * Load the state of this connection. Is typically called before |
| * {@link #connect(ITerminalControl)}. |
| * |
| * @param store a string based data store. Short keys like "foo" can be used to |
| * store the state of the connection. |
| */ |
| void load(ISettingsStore store); |
| |
| /** |
| * When the view or dialog containing the terminal is closed, |
| * the state of the connection is saved into the settings store <code>store</code> |
| * @param store |
| */ |
| void save(ISettingsStore store); |
| |
| /** |
| * FIXME should not have UI related stuff in ITerminalConnector, since |
| * connectors may be totally programmatic and UI-less. Better make the |
| * connector adapt to an interface that controls the UI aspect. |
| * |
| * @return a new page that can be used in a dialog to setup this connection. |
| * The dialog should persist its settings with the |
| * {@link #load(ISettingsStore)} and {@link #save(ISettingsStore)} |
| * methods. |
| */ |
| ISettingsPage makeSettingsPage(); |
| |
| /** |
| * @return A string that represents the settings of the connection. This representation |
| * may be shown in the status line of the terminal view. |
| */ |
| String getSettingsSummary(); |
| |
| } |