# 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