From 150b50ab79d7b329774080b559cb7cf2cdccd9cf Mon Sep 17 00:00:00 2001 From: Wainer dos Santos Moschetta Date: Mon, 13 Jul 2015 10:17:20 -0300 Subject: [PATCH] Bug 472514 - Add plug-in documentation. 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 --- bundles/org.eclipse.remote.doc.isv/.project | 22 ++++ .../META-INF/MANIFEST.MF | 9 ++ .../build.properties | 5 + .../org.eclipse.remote.doc.isv/css/style.css | 17 +++ .../html/concepts/concepts.html | 76 ++++++++++++ .../html/gettingstarted/intro.html | 46 +++++++ .../html/samples/examples.html | 112 ++++++++++++++++++ .../org.eclipse.remote.doc.isv/html/toc.html | 20 ++++ bundles/org.eclipse.remote.doc.isv/plugin.xml | 25 ++++ bundles/org.eclipse.remote.doc.isv/pom.xml | 43 +++++++ bundles/org.eclipse.remote.doc.isv/toc.xml | 17 +++ .../tocconcepts.xml | 7 ++ .../tocgettingstarted.xml | 7 ++ .../tocreference.xml | 6 + .../org.eclipse.remote.doc.isv/tocsamples.xml | 7 ++ .../org.eclipse.remote-feature/feature.xml | 7 ++ features/org.eclipse.remote-feature/pom.xml | 5 + releng/org.eclipse.remote.build/pom.xml | 2 + 18 files changed, 433 insertions(+) create mode 100644 bundles/org.eclipse.remote.doc.isv/.project create mode 100644 bundles/org.eclipse.remote.doc.isv/META-INF/MANIFEST.MF create mode 100644 bundles/org.eclipse.remote.doc.isv/build.properties create mode 100644 bundles/org.eclipse.remote.doc.isv/css/style.css create mode 100644 bundles/org.eclipse.remote.doc.isv/html/concepts/concepts.html create mode 100644 bundles/org.eclipse.remote.doc.isv/html/gettingstarted/intro.html create mode 100644 bundles/org.eclipse.remote.doc.isv/html/samples/examples.html create mode 100644 bundles/org.eclipse.remote.doc.isv/html/toc.html create mode 100644 bundles/org.eclipse.remote.doc.isv/plugin.xml create mode 100644 bundles/org.eclipse.remote.doc.isv/pom.xml create mode 100644 bundles/org.eclipse.remote.doc.isv/toc.xml create mode 100644 bundles/org.eclipse.remote.doc.isv/tocconcepts.xml create mode 100644 bundles/org.eclipse.remote.doc.isv/tocgettingstarted.xml create mode 100644 bundles/org.eclipse.remote.doc.isv/tocreference.xml create mode 100644 bundles/org.eclipse.remote.doc.isv/tocsamples.xml diff --git a/bundles/org.eclipse.remote.doc.isv/.project b/bundles/org.eclipse.remote.doc.isv/.project new file mode 100644 index 00000000000..f25b52a6f0c --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/.project @@ -0,0 +1,22 @@ + + + org.eclipse.remote.doc.isv + + + + + + org.eclipse.pde.ManifestBuilder + + + + + org.eclipse.pde.SchemaBuilder + + + + + + org.eclipse.pde.PluginNature + + diff --git a/bundles/org.eclipse.remote.doc.isv/META-INF/MANIFEST.MF b/bundles/org.eclipse.remote.doc.isv/META-INF/MANIFEST.MF new file mode 100644 index 00000000000..205562d3eea --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/META-INF/MANIFEST.MF @@ -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 diff --git a/bundles/org.eclipse.remote.doc.isv/build.properties b/bundles/org.eclipse.remote.doc.isv/build.properties new file mode 100644 index 00000000000..3acfefca581 --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/build.properties @@ -0,0 +1,5 @@ +bin.includes = plugin.xml,\ + META-INF/,\ + html/,\ + toc*.xml,\ + css/ diff --git a/bundles/org.eclipse.remote.doc.isv/css/style.css b/bundles/org.eclipse.remote.doc.isv/css/style.css new file mode 100644 index 00000000000..00cc9fbc494 --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/css/style.css @@ -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; +} \ No newline at end of file diff --git a/bundles/org.eclipse.remote.doc.isv/html/concepts/concepts.html b/bundles/org.eclipse.remote.doc.isv/html/concepts/concepts.html new file mode 100644 index 00000000000..a000aa679f9 --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/html/concepts/concepts.html @@ -0,0 +1,76 @@ + + + + + + Concepts + + + + + +

This section describes the main concepts and services implemented by the Eclipse remote framework.

+ + + +

Concepts

+ +

Some few concepts are needed to understand the framework's services overall. They are described in the next sections.

+ +

Connection type

+

An connection type (IRemoteConnectionType) abstracts a remote protocol to host access. As of version 2.0.1, the framework provides the ssh (implemented through JSch framework), Telnet and Local types.

+

The connection type is obtained from the remote services manager either by passing its scheme ID (Identification) or an URI.

+

It has the newConnection method where a new connection of this type is created. It also holds the list of all connections already created that belongs to it.

+ +

Remote connection

+

The remote connection (IRemoteConnection) 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 getService method.

+

Connections are read-only objects. In order to change the attributes of a connection, a working copy (IRemoteConnectionWorkingCopy) must be created. The host attributes getters and setters can also be managed with connection host service (IRemoteConnectionHostService). + +

Every remote connection belongs to a connection type.

+ + +

Remote resource

+

The remote resource interface (IRemoteResource) provides an adapter to a remote resource.

+

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.

+ +

Process builder

+

The process builder (IRemoteProcessBuilder) provides process operations on the remote host. This interface is intended to be a drop-in replacement for the Java SE ProcessBuilder class. See the java.lang.ProcessBuilder documentation for a description of the methods.

+

It is obtained from the process service (see IRemoteProcessService below) associated with a connection object that holds access information to the remote host.

+ +

Remote process

+

The remote process (IRemoteProcess) represents a process running on the remote host. Use it to manage the process (destroy), get exit status, and input/output/error streams.

+

Remote process are created using the IRemoteProcessBuilder interface.

+ + + +

Services

+ +

The remote services are implemented as OSGi services. There are available non-UI (core) and UI services.

+ +

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 getService method of its object's provider.

+ +

The main remote services are detailed in the next sections.

+ +

Services manager

+

The services manager (IRemoteServicesManager) interface provides the main entry point for accessing remote services. It can be obtained by calling RemoteServicesUtils.getService(IRemoteServicesManager.class) or using the Plugin's bundle context to access a OSGi service.

+

It provides access to connection types implemented by the framework and any connection already created.

+ +

File Service

+

The file service (IRemoteFileService) provides remote file manipulation operations on a given connection. It is obtained from a remote connection object by calling its getService(IRemoteFileService.class) method.

+ +

Using this interface, a path can be translated into an IFileStore object, and then manipulated using any of the normal EFS operations.

+

Its UI counterpart service (IRemoteUIFileService) comes with dialog widgets to browse files and directories on remote filesystem. + +

Process Service

+

The process service (IRemoteProcessService) provides services for starting up processes on a remote host. It is obtained from a remote connection object by calling its getService(IRemoteProcessService.class) method.

+

It is the entry point to get an IRemoteProcessBuilder object, used to spawn processes on the remote host. Environment variables of remote host are accessed using this service too.

+ +

Connection Service

+

The UI Connection service (IRemoteUIConnectionService) is used for manipulating connections in the UI, such as adding, editing, and opening connections.

+

Non-UI connection manipulation should use the IRemoteConnectionType interface (obtained from services manager) and the services related with IRemoteConnection interface.

+ + diff --git a/bundles/org.eclipse.remote.doc.isv/html/gettingstarted/intro.html b/bundles/org.eclipse.remote.doc.isv/html/gettingstarted/intro.html new file mode 100644 index 00000000000..ea7b1499cf8 --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/html/gettingstarted/intro.html @@ -0,0 +1,46 @@ + + + + + + Getting started + + + + +

Introduction

+

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 (www.jcraft.com/jsch). An implementation for the local system (where Eclipse is run) and Telnet protocol are also provided.

+

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.

+ +

Types of services

+

The API is divided into two types of remote services: UI and non-UI.

+

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.

+

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.

+ +

Remote Services Plugins

+ +

The remote services are divided into two plugins. These plugins should have no dependencies other than the platform.

+ + +

Remote service implementations provide the actual remote functionality using a particular remote protocol. These are supplied as a set of adapter plugins. + +

As of version 2.0.1, there is currently one implementation of SSH protocol using JSch:

+ + + +

The Telnet protocol implementation and UI widgets are provided by the plugins:

+ + +

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.

+ + + \ No newline at end of file diff --git a/bundles/org.eclipse.remote.doc.isv/html/samples/examples.html b/bundles/org.eclipse.remote.doc.isv/html/samples/examples.html new file mode 100644 index 00000000000..955358e4309 --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/html/samples/examples.html @@ -0,0 +1,112 @@ + + + + + + Samples + + + + +

Usage examples

+

This section shows usage examples for using the Eclipse Remote API.

+ +

The services manager can be obtained using RemoteServicesUtils (since 2.0.1) helper:

+ +

+IRemoteServicesManager servicesManager = RemoteServicesUtils.getService(IRemoteServicesManager.class);
+
+ +

An alternative is to use the bundle's context to get the service reference:

+ +

+BundleContext context = plugin.getBundle().getBundleContext();
+ServiceReference ref = context.getServiceReference(IRemoteServicesManager.class);
+IRemoteServicesManager servicesManager = context.getService(ref);
+
+ +

Once with services manager object, you obtain a connection type by its scheme ID or any URI to the remote host, as in:

+

+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);
+
+ +

The Telnet connection type can not be obtained by URI, instead you must use its ID: +


+IRemoteConnectionType connType;
+connType = servicesManager.getConnectionType("org.eclipse.remote.telnet.core.connectionType");
+
+ +

The remote connection is obtained from connection type object by either name or an URI. For example: +


+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");
+
+ +

If the connection does not exist, it can be created with a connection type (IRemoteConnectionType) instance. Use the connection type object to delete it as well: + +


+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
+
+ +

Connections can be opened or closed programmatically. Some operations requires the connection opened:

+

+connection.open(monitor); // Open the connection but allow the user to cancel the progress monitor
+connection.close(); // Now close it
+
+ +

The file service is obtained from a connection object. Remote resources can be manipulated with IFileStore:

+

+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!");
+}
+
+ +

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:

+

+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);
+
+ +

Use a connection object to get its associated process service (IRemoteProcessService). Then obtain a process builder (IRemoteProcessBuilder), so that commands can be executed on remote host:

+

+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);
+
+ +

Use the IRemoteResource adapter to get a location URI of the project (IProject): +


+IRemoteResource resource = (IRemoteResource)project.getAdapter(IRemoteResource.class);
+URI projectLocation = resource.getActiveLocationURI(); // Get URI to active location
+
+ + + \ No newline at end of file diff --git a/bundles/org.eclipse.remote.doc.isv/html/toc.html b/bundles/org.eclipse.remote.doc.isv/html/toc.html new file mode 100644 index 00000000000..e589c3134ee --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/html/toc.html @@ -0,0 +1,20 @@ + + + + + + Remote Developer's Guide + + + +

Eclipse Remote Developer's Guide

+

This is the guide of the eclipse remote development framework as of provided by org.eclipse.remote project.

+

Table of Contents

+ + + diff --git a/bundles/org.eclipse.remote.doc.isv/plugin.xml b/bundles/org.eclipse.remote.doc.isv/plugin.xml new file mode 100644 index 00000000000..1f77cc97a9c --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/plugin.xml @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + + + + + diff --git a/bundles/org.eclipse.remote.doc.isv/pom.xml b/bundles/org.eclipse.remote.doc.isv/pom.xml new file mode 100644 index 00000000000..f636457b8bd --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/pom.xml @@ -0,0 +1,43 @@ + + + 4.0.0 + + + org.eclipse.remote + remote-parent + 1.1.1-SNAPSHOT + ../../releng/org.eclipse.remote.build/pom.xml + + + org.eclipse.remote.doc.isv + 1.0.0-SNAPSHOT + eclipse-plugin + + + + org.eclipse.tycho.extras + tycho-document-bundle-plugin + ${tycho-extras-version} + + ${basedir}/html/reference/api + + + + + javadoc + + javadoc + + + + + + + diff --git a/bundles/org.eclipse.remote.doc.isv/toc.xml b/bundles/org.eclipse.remote.doc.isv/toc.xml new file mode 100644 index 00000000000..4a099b6a2a2 --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/toc.xml @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + diff --git a/bundles/org.eclipse.remote.doc.isv/tocconcepts.xml b/bundles/org.eclipse.remote.doc.isv/tocconcepts.xml new file mode 100644 index 00000000000..eb382cbaf3a --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/tocconcepts.xml @@ -0,0 +1,7 @@ + + + + + + + diff --git a/bundles/org.eclipse.remote.doc.isv/tocgettingstarted.xml b/bundles/org.eclipse.remote.doc.isv/tocgettingstarted.xml new file mode 100644 index 00000000000..fb12307e209 --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/tocgettingstarted.xml @@ -0,0 +1,7 @@ + + + + + + + diff --git a/bundles/org.eclipse.remote.doc.isv/tocreference.xml b/bundles/org.eclipse.remote.doc.isv/tocreference.xml new file mode 100644 index 00000000000..e9dc3b6853f --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/tocreference.xml @@ -0,0 +1,6 @@ + + + + + + diff --git a/bundles/org.eclipse.remote.doc.isv/tocsamples.xml b/bundles/org.eclipse.remote.doc.isv/tocsamples.xml new file mode 100644 index 00000000000..542cbc72678 --- /dev/null +++ b/bundles/org.eclipse.remote.doc.isv/tocsamples.xml @@ -0,0 +1,7 @@ + + + + + + + diff --git a/features/org.eclipse.remote-feature/feature.xml b/features/org.eclipse.remote-feature/feature.xml index 7deb6810a3a..761f1bc3bf4 100644 --- a/features/org.eclipse.remote-feature/feature.xml +++ b/features/org.eclipse.remote-feature/feature.xml @@ -47,6 +47,13 @@ version="0.0.0" unpack="false"/> + + org.eclipse.tycho.extras tycho-source-feature-plugin + + + + + source-feature diff --git a/releng/org.eclipse.remote.build/pom.xml b/releng/org.eclipse.remote.build/pom.xml index 079ed8e802e..12d3aad295e 100644 --- a/releng/org.eclipse.remote.build/pom.xml +++ b/releng/org.eclipse.remote.build/pom.xml @@ -61,6 +61,8 @@ ../../bundles/org.eclipse.remote.telnet.core ../../bundles/org.eclipse.remote.telnet.ui ../../features/org.eclipse.remote.telnet-feature + + ../../bundles/org.eclipse.remote.doc.isv