mirrors/cdt
1
0
Fork 0
mirror of https://github.com/eclipse-cdt/cdt synced 2025-06-08 10:16:03 +02:00
Code Issues Wiki Activity

Bug 472514 - Add plug-in documentation.

Browse source 
The org.eclipse.remote.doc.isv plug-in holds developer's guide.

The API is generated at build time with tychon in the html/reference/api folder.

Change-Id: I9812be3bcf7248f3b3c6330df86c0b862510dd3e
Signed-off-by: Wainer dos Santos Moschetta <wainersm@linux.vnet.ibm.com>
This commit is contained in:
Wainer dos Santos Moschetta 2015-07-13 10:17:20 -03:00
parent 58c1857c15
commit 150b50ab79
18 changed files with 433 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
bundles/org.eclipse.remote.doc.isv/.project Normal file
View file

@ -0,0 +1,22 @@
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>org.eclipse.remote.doc.isv</name>
<comment></comment>
<projects>
</projects>
<buildSpec>
<buildCommand>
<name>org.eclipse.pde.ManifestBuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.pde.SchemaBuilder</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>org.eclipse.pde.PluginNature</nature>
</natures>
</projectDescription>

9
bundles/org.eclipse.remote.doc.isv/META-INF/MANIFEST.MF Normal file
View file

@ -0,0 +1,9 @@
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Eclipse Remote Development documentation plug-in
Bundle-SymbolicName: org.eclipse.remote.doc.isv;singleton:=true
Bundle-Version: 1.0.0.qualifier
Require-Bundle: org.eclipse.remote.console;bundle-version="1.0.0",
org.eclipse.remote.core;bundle-version="2.0.0",
org.eclipse.remote.ui;bundle-version="2.0.0"
Bundle-Vendor: Eclipse PTP

5
bundles/org.eclipse.remote.doc.isv/build.properties Normal file
View file

@ -0,0 +1,5 @@
bin.includes = plugin.xml,\
META-INF/,\
html/,\
toc*.xml,\
css/

17
bundles/org.eclipse.remote.doc.isv/css/style.css Normal file
View file

@ -0,0 +1,17 @@
code {
color: Crimson;
font-family: monaco,consolas,"courier new",monospace;
}
pre {
background-color: lightgrey;
width: auto;
overflow: auto;
padding: 25px;
border: 1px solid navy;
margin: 1em;
}
p {
font: 15px arial, sans-serif;
}

76
bundles/org.eclipse.remote.doc.isv/html/concepts/concepts.html Normal file
View file

@ -0,0 +1,76 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Concepts</title>
<link rel="stylesheet" type="text/css" href="../../css/style.css">
</style>
</head>
<body>
<p>This section describes the main concepts and services implemented by the Eclipse remote framework.</p>
<!--
Concepts
-->
<h1>Concepts</h1>
<p>Some few concepts are needed to understand the framework's services overall. They are described in the next sections.</p>
<h3>Connection type</h3>
<p>An connection type (<code>IRemoteConnectionType</code>) abstracts a remote protocol to host access. As of version 2.0.1, the framework provides the <b>ssh</b> (implemented through JSch framework), <b>Telnet</b> and <b>Local</b> types.</p>
<p>The connection type is obtained from the remote services manager either by passing its scheme ID (Identification) or an URI.</p>
<p>It has the <code>newConnection</code> method where a new connection of this type is created. It also holds the list of all connections already created that belongs to it.</p>
<h3>Remote connection</h3>
<p>The remote connection (<code>IRemoteConnection</code>) interface is used to manage a connection to a single remote host. A connection must be established (open) before any other operations are permitted. All operations carried out on remote host should be evoked from its associated services, which are get with <code>getService</code> method.</p>
<p>Connections are read-only objects. In order to change the attributes of a connection, a working copy (<code>IRemoteConnectionWorkingCopy</code>) must be created. The host attributes getters and setters can also be managed with connection host service (<code>IRemoteConnectionHostService</code>).
<p>Every remote connection belongs to a connection type.</p>
<h3>Remote resource</h3>
<p>The remote resource interface (<code>IRemoteResource</code>) provides an adapter to a remote resource.</p>
<p>As of version 2.0.1, there are two types of remote resources: fully remote and synchronized. This interface provides a common mechanism for accessing resource information from either types.</p>
<h3>Process builder</h3>
<p>The process builder (<code>IRemoteProcessBuilder</code>) provides process operations on the remote host. This interface is intended to be a drop-in replacement for the Java SE <code>ProcessBuilder</code> class. See the <code>java.lang.ProcessBuilder</code> documentation for a description of the methods.</p>
<p>It is obtained from the process service (see <code>IRemoteProcessService</code> below) associated with a connection object that holds access information to the remote host.</p>
<h3>Remote process</h3>
<p>The remote process (<code>IRemoteProcess</code>) represents a process running on the remote host. Use it to manage the process (destroy), get exit status, and input/output/error streams.</p>
<p>Remote process are created using the <code>IRemoteProcessBuilder</code> interface.</p>
<!--
Services
-->
<h1>Services</h1>
<p>The remote services are implemented as OSGi services. There are available non-UI (core) and UI services.</p>
<p>Any given service can be associated with objects of the model (concepts) or nested to another one. In either case, an service instance is obtained by calling the <code>getService</code> method of its object's provider.</p>
<p>The main remote services are detailed in the next sections.</p>
<h3>Services manager</h3>
<p>The services manager (<code>IRemoteServicesManager</code>) interface provides the <b>main entry point</b> for accessing remote services. It can be obtained by calling <code>RemoteServicesUtils.getService(IRemoteServicesManager.class)</code> or using the Plugin's bundle context to access a OSGi service.</p>
<p>It provides access to connection types implemented by the framework and any connection already created.</p>
<h3>File Service</h3>
<p>The file service (<code>IRemoteFileService</code>) provides remote file manipulation operations on a given connection. It is obtained from a remote connection object by calling its <code>getService(IRemoteFileService.class)</code> method.</p>
<p>Using this interface, a path can be translated into an <code>IFileStore</code> object, and then manipulated using any of the normal EFS operations.</p>
<p>Its UI counterpart service (<code>IRemoteUIFileService</code>) comes with dialog widgets to browse files and directories on remote filesystem.
<h3>Process Service</h3>
<p>The process service (<code>IRemoteProcessService</code>) provides services for starting up processes on a remote host. It is obtained from a remote connection object by calling its <code>getService(IRemoteProcessService.class)</code> method.</p>
<p>It is the entry point to get an <code>IRemoteProcessBuilder</code> object, used to spawn processes on the remote host. Environment variables of remote host are accessed using this service too.</p>
<h3>Connection Service</h3>
<p>The UI Connection service (<code>IRemoteUIConnectionService</code>) is used for manipulating connections in the UI, such as adding, editing, and opening connections.</p>
<p>Non-UI connection manipulation should use the <code>IRemoteConnectionType</code> interface (obtained from services manager) and the services related with <code>IRemoteConnection</code> interface.</p>
</body>
</html>

46
bundles/org.eclipse.remote.doc.isv/html/gettingstarted/intro.html Normal file
View file

@ -0,0 +1,46 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Getting started</title>
<link rel="stylesheet" type="text/css" href="../../css/style.css">
</head>
<body>
<h1>Introduction</h1>
<p>The purpose of remote services API is to provide a programming interface to remote services that is agnostic to the actual remote services implementation. Currently the only implementation supported of SSH protocol uses JSch(Java Secure Channel) project (<a href="http://www.jcraft.com/jsch/">www.jcraft.com/jsch</a>). An implementation for the local system (where Eclipse is run) and Telnet protocol are also provided.</p>
<p>The API is generic enough so that it is possible to use it for all remote or local operations. This is useful for situations where both a remote and local mode should be provided, but the programmer wants to avoid two separate code paths.</p>
<h1>Types of services</h1>
<p>The API is divided into two types of remote services: UI and non-UI.</p>
<p>UI services are for activities such as file browsing that require use of the UI. In particular, it provides a main preference page (under "Remote Development > Remote Connections") which allow connections to be created, edited, removed, opened, and closed. </p>
<p>Non-UI services are purely programmatic, they provides a set of core services for manipulating remote resources. The non-UI services can be used independently of the UI services.</p>
<h1>Remote Services Plugins</h1>
<p>The remote services are divided into two plugins. These plugins should have no dependencies other than the platform.</p>
<ul>
<li>org.eclipse.remote.core - provides non-UI remote services</li>
<li>org.eclipse.remote.ui - provides UI remote services</li>
</ul>
<p>Remote service implementations provide the actual remote functionality using a particular remote protocol. These are supplied as a set of adapter plugins.
<p>As of version 2.0.1, there is currently one implementation of SSH protocol using JSch:</p>
<ul>
<li>org.eclipse.remote.jsch.core</li>
<li>org.eclipse.remote.jsch.ui</li>
</ul>
<p>The Telnet protocol implementation and UI widgets are provided by the plugins:</p>
<ul>
<li>org.eclipse.remote.telnet.core</li>
<li>org.eclipse.remote.telnet.ui</li>
</ul>
<p>These plugins are dependent on the remote services implementations, but are optional for the remote services API. The API will automatically detect the installed plugins.</p>
</body>
</html>

112
bundles/org.eclipse.remote.doc.isv/html/samples/examples.html Normal file
View file

@ -0,0 +1,112 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Samples</title>
<link rel="stylesheet" type="text/css" href="../../css/style.css">
</head>
<body>
<h1>Usage examples</h1>
<p>This section shows usage examples for using the Eclipse Remote API.</p>
<p>The services manager can be obtained using <code>RemoteServicesUtils</code> (since 2.0.1) helper:</p>
<pre><code class="snippet">
IRemoteServicesManager servicesManager = RemoteServicesUtils.getService(IRemoteServicesManager.class);
</code></pre>
<p>An alternative is to use the bundle's context to get the service reference:</p>
<pre><code class="snippet">
BundleContext context = plugin.getBundle().getBundleContext();
ServiceReference<T> ref = context.getServiceReference(IRemoteServicesManager.class);
IRemoteServicesManager servicesManager = context.getService(ref);
</code></pre>
<p>Once with services manager object, you obtain a connection type by its scheme ID or any URI to the remote host, as in:</p>
<pre><code class="snippet">
IRemoteConnectionType connType;
// Get connection type by Scheme ID
connType = servicesManager.getConnectionType("ssh");
// Get connection type by URI
URI uri = URI.create("ssh://MyConnection/path/to/file");
connType = servicesManager.getConnectionType(uri);
</code></pre>
<p>The Telnet connection type can not be obtained by URI, instead you must use its ID:
<pre><code class="snippet">
IRemoteConnectionType connType;
connType = servicesManager.getConnectionType("org.eclipse.remote.telnet.core.connectionType");
</code></pre>
<p>The remote connection is obtained from connection type object by either name or an URI. For example:
<pre><code class="snippet">
IRemoteConnection connection;
// Get connection by URI
URI uri = URI.create("ssh://MyConnection/path/to/file");
connection = connType.getConnection(uri);
// Get connection by name
connection = connType.getConnection("MyConnection");
</code></pre>
<p>If the connection does not exist, it can be created with a connection type (<code>IRemoteConnectionType</code>) instance. Use the connection type object to delete it as well:
<pre><code class="snippet">
IRemoteConnectionWorkingCopy rcwc; // Writable connection working copy
rcwc = connType.newConnection(connectionName); // Create connection of connection type
IRemoteConnectionHostService hostServices; // Fill connection information through host service
hostServices = rcwc.getService(IRemoteConnectionHostService.class); // Obtain the service from working copy instance
hostServices.setHostname(address);
hostServices.setUsername(username);
hostServices.setUsePassword(true);
hostServices.setPassword(passwd);
IRemoteConnection connection = rcwc.save(); // Finally save the working copy, then get the connection (read-only) object
connType.removeConnection(connection); // Remove connection and all resources associated with it
</code></pre>
<p>Connections can be opened or closed programmatically. Some operations requires the connection opened:</p>
<pre><code class="snippet">
connection.open(monitor); // Open the connection but allow the user to cancel the progress monitor
connection.close(); // Now close it
</code></pre>
<p>The file service is obtained from a connection object. Remote resources can be manipulated with <code>IFileStore</code>:</p>
<pre><code class="snippet">
IRemoteFileService fileService = connection.getService(IRemoteFileService.class);
// The remote connection does not need to be open to get the resource
IFileStore fs = fileService.getResource("/path/to/resource");
// But the remote connection need to be open to operate on the resource
if (fs.fetchInfo().exists()) {
System.out.println("It exists!");
}
</code></pre>
<p>In the other hand, the UI file service is obtained from a connection type rather than the connection. The reason is that it allows user to select the connection in a list. It is also possible to set the connection:</p>
<pre><code class="snippet">
IRemoteUIFileService uiFileService = conn.getConnectionType().getService(IRemoteUIFileService.class);
uiFileService.setConnection(connection); // Set default connection (optional)
uiFileService.showConnections(true); // Also show list of available connections
// The return value is the path of the directory selected on the remote system
String path = uiFileService.browseDirectory(shell, "Browse /home", "/home", IRemoteUIConstants.NONE);
</code></pre>
<p>Use a connection object to get its associated process service (<code>IRemoteProcessService</code>). Then obtain a process builder (<code>IRemoteProcessBuilder</code>), so that commands can be executed on remote host:</p>
<pre><code class="snippet">
IRemoteProcessService ps = connection.getService(IRemoteProcessService.class);
IRemoteProcessBuilder pb = ps.getProcessBuilder("/bin/ls", "-l");
IRemoteProcess process = pb.start();
// Use IRemoteProcess to manage the process. Alternatively, use an adaptor to java.lang.Process
Process process2 = new RemoteProcessAdapter(process);
</code></pre>
<p>Use the <code>IRemoteResource</code> adapter to get a location URI of the project (<code>IProject</code>):
<pre><code class="snippet">
IRemoteResource resource = (IRemoteResource)project.getAdapter(IRemoteResource.class);
URI projectLocation = resource.getActiveLocationURI(); // Get URI to active location
</code></pre>
</body>
</html>

20
bundles/org.eclipse.remote.doc.isv/html/toc.html Normal file
View file

@ -0,0 +1,20 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Remote Developer's Guide</title>
</head>
<body>
<h1>Eclipse Remote Developer's Guide</h1>
<p>This is the guide of the eclipse remote development framework as of provided by <i>org.eclipse.remote</i> project.</p>
<h3>Table of Contents</h3>
<ul style="list-style-type:none">
<li><a href="gettingstarted/intro.html">Getting Started</a></li>
<li><a href="concepts/concepts.html">Concepts</a></li>
<li><a href="samples/examples.html">Usage Examples</a></li>
<li><a href="reference/api/index.html">Reference</a></li>
</ul>
</body>
</html>

25
bundles/org.eclipse.remote.doc.isv/plugin.xml Normal file
View file

@ -0,0 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
<extension
point="org.eclipse.help.toc">
<toc
file="toc.xml"
primary="true">
</toc>
<toc
file="tocconcepts.xml">
</toc>
<toc
file="tocgettingstarted.xml">
</toc>
<toc
file="tocreference.xml">
</toc>
<toc
file="tocsamples.xml">
</toc>
</extension>
</plugin>

43
bundles/org.eclipse.remote.doc.isv/pom.xml Normal file
View file

@ -0,0 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.eclipse.remote</groupId>
<artifactId>remote-parent</artifactId>
<version>1.1.1-SNAPSHOT</version>
<relativePath>../../releng/org.eclipse.remote.build/pom.xml</relativePath>
</parent>
<artifactId>org.eclipse.remote.doc.isv</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>eclipse-plugin</packaging>
<build>
<plugins>
<plugin>
<groupId>org.eclipse.tycho.extras</groupId>
<artifactId>tycho-document-bundle-plugin</artifactId>
<version>${tycho-extras-version}</version>
<configuration>
<outputDirectory>${basedir}/html/reference/api</outputDirectory>
<!-- TODO: bump tycho-extras version. Excludes option requires >= 0.23
<javadocOptions>
<excludes>
<exclude>org.eclipse.remote.internal.*</exclude>
</excludes>
</javadocOptions>
-->
</configuration>
<executions>
<execution>
<id>javadoc</id>
<goals>
<goal>javadoc</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>

17
bundles/org.eclipse.remote.doc.isv/toc.xml Normal file
View file

@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Eclipse Remote Developer's Guide" topic="html/toc.html">
<topic label="Getting Started">
<anchor id="gettingstarted"/>
</topic>
<topic label="Concepts">
<anchor id="concepts"/>
</topic>
<topic label="Reference">
<anchor id="reference"/>
</topic>
<topic label="Samples">
<anchor id="samples"/>
</topic>
</toc>

7
bundles/org.eclipse.remote.doc.isv/tocconcepts.xml Normal file
View file

@ -0,0 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Concepts" link_to="toc.xml#concepts">
<topic label="Concepts" href="html/concepts/concepts.html">
</topic>
</toc>

7
bundles/org.eclipse.remote.doc.isv/tocgettingstarted.xml Normal file
View file

@ -0,0 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Getting Started" link_to="toc.xml#gettingstarted">
<topic label="Getting Started" href="html/gettingstarted/intro.html">
</topic>
</toc>

6
bundles/org.eclipse.remote.doc.isv/tocreference.xml Normal file
View file

@ -0,0 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Reference" link_to="toc.xml#reference">
<topic label="API Reference" href="html/reference/api/index.html" />
</toc>

7
bundles/org.eclipse.remote.doc.isv/tocsamples.xml Normal file
View file

@ -0,0 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Samples" link_to="toc.xml#samples">
<topic label="Samples" href="html/samples/examples.html">
</topic>
</toc>

7
features/org.eclipse.remote-feature/feature.xml
View file

@ -47,6 +47,13 @@
version="0.0.0"
unpack="false"/>
<plugin
id="org.eclipse.remote.doc.isv"
download-size="0"
install-size="0"
version="0.0.0"
unpack="false"/>
<plugin
id="org.eclipse.remote.jsch.core"
download-size="0"

5
features/org.eclipse.remote-feature/pom.xml
View file

@ -15,6 +15,11 @@
<plugin>
<groupId>org.eclipse.tycho.extras</groupId>
<artifactId>tycho-source-feature-plugin</artifactId>
<configuration>
<excludes>
<plugin id="org.eclipse.remote.doc.isv"/>
</excludes>
</configuration>
<executions>
<execution>
<id>source-feature</id>

2
releng/org.eclipse.remote.build/pom.xml
View file

@ -61,6 +61,8 @@
<module>../../bundles/org.eclipse.remote.telnet.core</module>
<module>../../bundles/org.eclipse.remote.telnet.ui</module>
<module>../../features/org.eclipse.remote.telnet-feature</module>
<!-- Documentation -->
<module>../../bundles/org.eclipse.remote.doc.isv</module>
</modules>
<repositories>