Advanced Workspace Tasks

The workspace configuration support used in SDC allows you or your organization to extend the type of configuration that can be distributed via SDC. Out of the box, SDC supports distribution for preferences and project sets, or .psf and .epf files, respectively. If you have other configurations you want to deploy to client workstations, you can use an Eclipse extension point and a custom plugin to provide awareness for other file types by registering a handler for the respective file extension.

To facilitate re-use of existing handlers, SDC leverages the extension point model provided by the Google Workspace Mechanic, which provides a standard way of supporting additional workspace configurations. While SDC leverages the extensibility model, SDC uses its own interface and approach for applying updates; the application of updates can be fully automated and included in the normal SDC package update process.

There are two options for creating custom workspace tasks. The first option is to use the TaskScanner interface. Another option is to create a .class style task.

TaskScanner Interface Tasks

The basic workflow to add support for additional tasks involves:

Creating a new plugin that implements the com.google.eclipse.mechanic.TaskScanner interface.
Registering the extension for your task scanner in your plugin’s plugin.xml.
Creating an update site for your plugin, which can be imported as a Third Party Library via the Admin Console.
Adding your plugin to the various package configurations that handle the additional workspace configuration.
Adding the desired workspace tasks to the one or more packages.
Promoting the package to cause the task to be recognized and run as part of workspace setup.

At a high level, the Google Workspace Mechanic enables you to create a TaskScanner that iterates a list of files provided to it, allowing your TaskScanner to determine which of the tasks it is able to support. The standard model to use involves using the file extension to determine applicable tasks. For each task found, it creates a Task object that encapsulates information about how to invoke the task, or how to check the workspace if the task is applicable to be run (such as a user undoing what the task is supposed to enforce).

SDC automatically detects checksum changes to the tasks managed as part of the delivery package and re-run the appropriate scanners when there are relevant changes. In addition, SDC makes sure that for clean workspaces, all tasks are run on startup that

Class Style Tasks in SDC

SDC supports .class custom tasks for workspace configuration. Task class files are used to extend the MyEclipse product. When added to the package workspace tasks, the class is executed when the package is installed.

Below is an example of a .class style task. To use this example task, build it in a normal Eclipse plug-in project that depends on Genuitec’s version of the workspace mechanic plugins to be able to resolve the Task type. Then, add YourSampleTask.class from the bin/ folder of your project as a workspace task to your package or environmental policy.

// for .class style tasks, the package must ALWAYS be: 
// com.google.eclipse.mechanic.ext 

package com.google.eclipse.mechanic.ext; 
public class YourSampleTask implements Task, Evaluator, RepairAction { 

   private IResourceTaskReference reference; 

   @Override 
   public String getId() { 
      return "com.yourcompany.project.tasktype";
   } 

   @Override 
   public String getTitle() { 
      return "Title of your custom task";
   } 

   @Override 
   public String getDescription() { 
      return "Description of your custom task"; 
   } 

   /** 
    * The evaluate() method determines if this task's conditions have already been met. 
    */ 
   @Override 
   public boolean evaluate() { 
      return true; // true == the task has already been run and nothing else to do 
   } 

   /** 
    * The repair() method performs the task. 
    */ 
   @Override 
   public IStatus repair(IProgressMonitor monitor) { 
      // do the work of your task
   } 

   @Override 
   public Evaluator getEvaluator() { 
      return this; 
   } 

   @Override public RepairAction getRepairAction() { 
      return this; 
   } 

   @Override 
   public IResourceTaskReference getReference() { 
      return reference; 
   } 

   public void setReference(IResourceTaskReference reference) { 
      this.reference = reference; 
   } 

   @Override 
   public int getRepairCost() { 
      return 100; 
   }}

Arbitrary Workspace Task

The workspace task file allows delivering arbitrary files into your workspaces. The file must start with single line of the format #<path> where <path> is a path in the workspace. This task can be used for dropping down extra files into the .metadata/ area for plugins that do not work with standard preferences. Incremental changes are done to the files by replacing the .wrkspc file. The following is a sample file:

#.metadata/.plugins/your.plugin/sample.txt
<Contents to be delivered>

Note: If delivering binary contents, prepend to the file exactly #<path>n and the rest of the binary contents will be delivered to the workspace in a byte-compatible way.

The default behavior as shown above is to apply the specified file to the workspace folder only on update. One of the following flags can be added to change the default behavior. The format is #<flag><path> where <path> is either a path in the workspace or in the installation directory, depending on the flag used. The flags are:

(once|workspace) – applies the file only one time to the workspace.
(once|installdir) – applies the file only one time to the installation folder.
(onupdate|workspace) – applies the file to the workspace with each update.
(onupdate|installdir) – applies the file to the installation folder with each update.

Example:

#(once|workspace).metadata/.plugins/your.plugin/sample.txt
<Contents to be delivered>

Git Projects Workspace Task

The Git projects workspace task lets you define a set of Git repositories with the projects you want to automatically include in your Eclipse package. When your team installs the configured Eclipse package, the Git workspace task clones the specified repositories and adds the specified projects to the user’s workspace.

The Git Task Model
The model used for the Git projects covers the repositories, branches, and projects you want to cover. If the task detects existing repositories, it automatically looks for missing projects to be imported, and helps you manage the ongoing usage of your Git repositories, not just the initial configuration.

The following is an example .git task file that includes two different repositories.

<git>
   <repository name="main project" uri="ssh://myHost:7022/home/my/repository">
       <!-- Credentials can be provided for defaults if appropriate -->
       <credentials mode="BOTH"/>
       <!-- All or some branches can be configured -->
       <remote-branches>
          <remote-branch remote="origin" reference="refs/heads/master"  
            clone-submodules="true" />
       </remote-branches>
       <local-branches>
          <local-branch name="master" based-on="refs/heads/master" active="true" />
       </local-branches>
       <!-- You can either opt-in or opt-out of projects in a repository -->
       <import-all-projects>
          <exclude>                
             <project name="first.project.to.exclude"/>
             <project name="second.project.to.exclude"/>
          </exclude>
      </import-all-projects>
   </repository>

   <repository name="org.eclipse.epp.mpc"
       uri="git://git.eclipse.org/gitroot/mpc/org.eclipse.epp.mpc">
      <credentials mode="NONE" />
      <remote-branches>
          <remote-branch remote="origin" reference="refs/heads/maintenance_1_1_x"
            clone-submodules="true" />
      </remote-branches>
      <local-branches>
          <local-branch name="maintenance_1_1_x" based-on="refs/heads/maintenance_1_1_x"
            active="true" />
      </local-branches>
      <import-projects>
          <project name="org.eclipse.epp.mpc.core"/>
      </import-projects>
   </repository>
</git>

Use the Git Task with SDC

Create a task file containing the definition of Git repositories and projects you want automatically configured in your Eclipse package(s). This task file should have a .git extension.
Add the task file to your package(s) in the Workspace Configuration section of the Configuration tab.
Commit and promote the package.
Install the package.
Configure repository locations and/or supply credentials when prompted.

The following image gives an idea of how the repositories are currently configured when presented to the user. Credentials can be configured and paths tailored. This allows users to quickly set up the configuration for their system.

git_import_settings_page
Git import settings page

Creating the Git Task File (.git)
You can use any text editor to create your Git task file. If your editor supports XML validation and content assist, you can configure it to use the sample XML Schema Definition (xsd) to help you author your task files. To leverage code assist, you can start with an XML file extension and just change the extension to .git when you are ready to use it with SDC. Alternatively, you can set up your editor to recognize .git files as XML.

Target Platform Workspace Task

By using the Target Platform workspace task, you can provision target platforms in your packages so that teams can work off of unified target platforms in addition to unified tool stacks.

From either Eclipse.org or another source, download one or more target platforms you would like to use. You can use profiles or just directories of bundles to define your target platform. You could even use SDC to provision a package and use that as your target platform. Zip up your target platform in preparation for the next step. Be sure to keep track of the paths to the profile contents in the zip file. You will use them in step 3. Example target platforms are Eclipse Classic 3.6 or Eclipse for Java 3.5 from Eclipse.org, or a set of plugins that your company ships (or a combination of the two).
In SDC, import your downloaded target platform as a binary third-party update site. Make sure to supply a zip for each operating system/architecture you want to support. If you’re using downloads from Eclipse.org, you don’t have to unzip the downloads; just supply them as-is. Also, take note of the name of the third-party library you specify because you will use it in step 3.
Copy and edit one of the example .targetplatform files. You’ll notice from the examples that there are many options you can specify for a target platform. Some of them are:

– The name of the target platform. This extension requires unique names. If you specify more than one platform with the same name, you will get non-deterministic results. This is the name attribute on the target-platform tag.

– The source of the bundles that comprise the target platform. You can specify:

bundles-from-profile: This directive has three options you must specify. (1) third-party-library-title: The name you gave your binary third party library when imported it in step 2. (2) home: The relative path from the root of your zip file that designates the root of the profile. (3) configuration: The relative path from the root of your zip file that designates the configuration directory that is commonly under the home directory

bundles-from-directory: This directive has two options you must specify. (1) third-party-library-title: The name you gave your binary third party library when imported it in step 2. (2) path: The relative path from the root of your zip file that designates the folder that contains the bundles.

– Whether or not the target should be set as the default target for the workspace. You should set this on only one target-platform. The tag is<default-target /> and it belongs inside the <target-platform> tag.

– The applicable operating system, architecture, and windowing system for the target platform. Note that you can use the same third-party binary update site to service multiple platform combinations. These are attributes of the target-platform tag named os, arch, and wsrespectively.

– Whether the specified platform should be based on the running platform. This will give you different target platforms based on the Eclipse you are running, but this mimics what Eclipse does out of the box. The tag is <based-on-running-platform/>, and like the <default-target/> tag, it belongs inside the <target-platform> tag.

– Specific bundle IDs and versions to include, include optionally, or include implicitly.

Note: Eclipse 3.8 and 4.2 ignore the optional inclusion rules. See the examples.targetplatform file for syntax. These settings are advanced and usually aren’t needed for common usage.
On your package’s Software tab, add the binary third-party libraries you added in step 2.
Add your .targetplatform file as a workspace task on the package’s Configuration tab.
Commit & promote your package.

After installation, your users will see a configuration phase. They can then select Window>Preferences from the menu, expand Plug-in Development, and select Target Platform to verify that the target platforms were installed and correctly configured.

Errors that occur during the application of the target platform settings are written to the <workspace>/.metadata/.log file.