We recommend that those interested in integrating Mylyn email mylyn-dev@eclipse.org regarding for pointers to examples and guidance on upcoming changes. We encourage integrators to take the "better to ask for forgiveness than permission" approach to adding and updating wiki documentation. Committers review all changes and will update them as needed. Evolving the documentation with integrator contributions works well because it ensures that the documentation takes the perspective of newcomers. It also helps committers dedicate more time to responding to requests for improving the corresponding APIs.

Feature configuration

When integrating Mylyn with an existing tool, we recommend creating a new feature that declares a dependency on both the corresponding Mylyn feature and on the plug-ins and features of the tool. The new feature can then be deployed on the integrators' update site, and the update manager will require that the correct version of Mylyn is installed before allowing the new feature. The Mylyn Subversive integration can be used as an example of this.

In order to detect and protect yourself from API misuse, we highly recommend using the Eclipse API Tools.

Deciding on a version

We suggest targeting the Mylyn 3.x stream. So check out the HEAD project set. Note that if you build against the HEAD stream your plug-in will most likely support the last two major releases of Eclipse and the most recent development stream because our APIs generally insulate the connector from the platform internals that we use. But you will want to verify this yourself by building against the oldest supported Eclipse version before you deploy.

The general policy for Mylyn is that the current and previous major release and the latest milestone of Eclipse are supported. For example, as of the Galileo release on June 24th, 2009 Eclipse 3.5 (latest milestone), 3.4 (current release) and 3.3 (previous release) were supported. Accordingly the following Mylyn 3.3 release supported Eclipse 3.6M2, 3.5 and 3.4.

Release policy

The minor qualifier of the version is incremented and the service qualifier is reset, e.g. 3.3.2 -> 3.4.0.

Compatibility with previous releases is documented in the plan. Generally, binary backwards compatibility of API is maintained with preceding major release, additional API is added and internals may change.

Major releases require a plan, release review and New & Noteworthy.

Compatible versions of connectors listed in the discovery portal need to be available on the release date.

Service Releases

Usually released every 3 - 6 weeks.

Only the service qualifier of the version is incremented, e.g. 3.4.0 -> 3.4.1.

Changes are never destabilizing and UI backwards compatibility is maintained with preceding major release.

Binary backwards compatibility of API and internals is maintained with preceding major release.

Retention policy for builds

Integration builds against HEAD are provided on a weekly basis and available from download.eclipse.org. Integration builds are deleted once a release versions of the corresponding stream becomes available. Release versions are listed on the download page. Versions older than one year are archived on a regular basis and download URLs may change from download.eclipse.org to archive.eclipse.org.

Watching API changes

You can watch for API changes by creating a query for all Mylyn bugs tagged [api]. Major API changes will be announced on the mylyn-dev mailing list.

Using Internals

Following the lead of the Eclipse Platform, Mylyn makes a very clear distinction between API and internals, placing the latter in packages in the org.eclipse.mylyn.internal namespace. In order to support experimentation, all internal packages are exported. However, they are marked x-internal:=true, which means that the Eclispe will inform you with warnings when you are using internals.

If you are using internals in your integration, the burden of maintenance is placed entirely on your integration, since the project only guarantees no breakage of internal classes between minor releases, and these are likely to change in future major releases. Some tips for using internals:

Check if there is API that you could use to achieve the same thing.

File a bug report stating that you would like the internals to become API.

Create a test case that exercises the API and/or internals that you use. This is the only way of ensuring that the behavior you are relying on won't change down the road.

Innovating and Experimenting

One of the key challenges with building innovative or experimental tools and solutions is to get the UI friction low enough to get enough people to try it, without investing a lot of of time into the UI work since that can take time away from the core work and evaluation. Some tips:

Decide and communicate whether you want the plug-in to be something that people experiment with, or something that they use for their daily development.

If the plug-in is to be used for daily development, it should have a very low performance footprint. What's most important is that it does not slow down the user's Eclipse when it is not being used, otherwise many users will quickly disable it.

When your plug-in is doing any background work, make sure to have that indicated in the Progress view (via the Jobs API). This will help people trust the tool, since their Eclipse could be getting slowed down by something else.

Decide carefully on the UI that's needed to enable early adopters to make use of your tool. Eclipse users tend to have a very high expectation of UI polish, and UI work can dominate implementation time. Try to reuse existing UIs as much as possible. When adding new UI, it can help to follow the Eclipse UI guidelines (either the document or by example) since this will make it easier for people to use your tool without needing to read documentation.

Eat your own dogfood as much as possible. If you expect others to be able to use the tool you should be able to use it yourself (as long as you are representative of the target audience). One of the key benefits of consuming what you produce is that it will help you prioritize both the performance and the UI work.

Provide people with a public forum for feedback, since open discussion is important to many of the open source contributors who may try it. If you do not have a forum available you can start a discussion thread on the Mylyn newsgroup.

Capabilities

The plug-in is not distributed. Integrators are encouraged to ship their own capability definitions based on the example extensions linked above (see bug 299599).

Commons API

Since Mylyn 3.0

The Mylyn Commons API provides common facilities that are used by the other Mylyn components. The Commons facilities can be reused without bringing in any other Mylyn dependencies and have very limited set of Eclipse Platform dependencies. Note that some of the Commons components provide tentative API that is identified with a provisional segment in the package name. While the corresponding classes are being used by Mylyn components, we are still seeking integrator input on them and as such they are subject to change, and will move out of the provisional package once their API has been hardened.

Consuming commons plug-ins

The Mylyn update site provides an uncategorized feature that provides all commons plug-ins. This feature is provided for backwards compatibility with the old update manager (see bug 304755). Integrators are encouraged to specify dependencies on a plug-in level in feature.xml files, e.g.:

Documentation

Discovery API

At a high level Mylyn uses the concept of a directory and connector descriptors. The directory is a declarative (XML) resource that exists at a well-known URL, and points to connector descriptors. Connector descriptors describe an installable component, and include branding, description, images, etc. So Connector Discovery first accesses the directory to discover where the connector descriptors can be found, then downloads the descriptors to discover what the installable units are. This design provides a central point of control for updating what is discoverable, and avoids the need to install any plug-ins to have contributions to the discovery UI. It also gives vendors the freedom to update their contributions without involving changes or involvement by committers, providing that their contribution is already listed in the directory. Contributions may also be provided by installed plug-ins if desired.

The discovery listings are stored in file hosted on eclipse.org that has entries of the following form:

Tasks API

Use Cases

Task repository requirements

Mylyn can be extended to any task/bug/issue/story repository or tracker by creating a repository Connector that links Mylyn's task management facilities with the repository. Connection to the task repository is handled by the Connector (e.g. via HTTP/REST for the Bugzilla Connector, via SOAP for the JIRA Connector). The following are required to support task list integration:

Identifying tasks: must be uniquely identifiable by a per-repository integer or string handle (e.g. repository: bugs.eclipse.org/bugs, id 138144). ID must be robust to task renames, moves within components and categories, etc.

Retrieving tasks: mechanism for retrieving the attributes for a task given an ID. Attributes can typically include the description, priority, assignee and comment thread. For example, REST is the mechanism used by the Bugzilla Connector (POST request asks for bug ID, and XML as the return format, example), and SOAP is the mechanism used by the JIRA Connector.

Performing queries: mechanism for executing a string-based query and returning all of the matching task IDs. Preferrably encoded as a URL to allow interoperability with the web UI. For example, the Bugzilla Connector issues a POST request with the query URL, and specifies that the return format should be RDF, example.

The following additional mechanisms enable rich editing:

Retrieving all of the operations possible on a task given login credentials (e.g. ability to reassign, change priority)

Accessing all of the repository attributes (e.g. lists of products, components, versions), example

Setting any of the task's attributes (e.g. changing components, reassigning)

Adding and retrieving attachments (e.g. posting patches, screenshots)

The following are optional:

Notification of changes (e.g. RSS-based notification of an update made via that web UI)

The case may be that most of the attributes for your particular repository are highly customizable and user defined. A connector can be written for this scenario but will require a bit more plumbing. At the very least, you will need to map the id and summary of your repository artifacts to Mylyn task data attributes. These fields are the minimal requirements to give your 'task' representation in the task list. Depending on when you retrieve the set of possible attributes and values, you will likely either store it in your connector specific repository configuration or on a per ticket basis. The latter is supported by Mylyn's generic attribute facility which enables offline support and rich editing for common attribute types. In addition the editor is customizable to handle repository specific types or layouts.

Integrating with Mylyn's Task List vs. using a custom view

The Mylyn Task List has a considerable amount of functionality that is related to working with queries and to rich editing. For example, it shows notifications of incoming changes, and indicates when a query synchronization failed. It is also the anchor for managing the offline support, since only the tasks that the user has read are stored offline, only changed tasks are synchronized, and all of this state is maintained in the Task List. Our architecture does provide a loosely-coupled architecture so you can use the TaskList (in ..mylyn.tasks.core) without using any of its UI or having your users install the corresponding view. But for most cases we believe that the better approach is to integrate with Mylyn's Task List rather than providing an separate view. Most developers work with three kinds of tasks:

The issues and tasks that make up their project (i.e. in MKS integrity).

Bug reports and enhancement requests that they watch and create for the other frameworks that they use (e.g. bugs against Eclipse, JEE, Spring).

Personal tasks and todos they need to make for themselves (via Mylyn's Task List).

For this reason a fundamental part of our approach is to give developers a single view for managing all of their tasks, and to make it easy for vendors to customize the content of the Task List and rich editors to meet their needs (e.g. as JIRA does with custom task icon type overlays). There are substantial benefits to providing developers with a single unified task management view, similar to those benefits of providing them with a unified resource management view (i.e., Eclipse's Project Explorer). Rather than bloating the user experience by involving one or more disparate bug/task/issue/ticket management views, developers can provide a single Task List that is seamlessly integrated with Eclipse. For an overview of the benefits refer to the following article: http://www-128.ibm.com/developerworks/java/library/j-mylyn1/

The other thing to consider is integration with Mylyn's automatic context management facilities. Again, this is possible to integrate with a custom view, but the Task List has been streamlined around the interaction needed to make task activation easy. For an overview of task context management refer to this article: http://www-128.ibm.com/developerworks/java/library/j-mylyn2

Creating connector projects

The Trac connector is a good example, because it is a nearly-full featured implementation, but does not contain as much customization as Bugzilla. Start by creating two plug-in projects using the following suggested naming convention:

com.mycompany.mytracker.core: Java API for connecting to the task repository. This project should not make contributions to the Eclipse UI and hence does not need a plugin.xml file.

com.mycompany.mytracker.ui: Eclipse and Mylyn UI for the connector which does make contributions to the UI, so this will need a plugin.xml (created by PDE wizard).

com.mycompany.mytracker.tests: unit tests for both core and UI parts, should have JUnit on its classpath.

Implementing core extension points

Your connector should extend AbstractRepositoryConnector (org.eclipse.mylyn.provisional.tasklist). For basic operation you should first implement importing existing tasks from the repository. Therefore you need to implement the methods getConnectorKind, canCreateTaskFromKey, and getTaskData. Use the Trac connector as an example. If your first basic plugin works, you should handle synchronization by implementing performQuery().

Here are some classes you should create for your connector:

MytrackerCorePlugin extends Plugin

MytrackerRepositoryConnector extends AbstractRepositoryConnector

Tips on adding external library JARs:

The Eclipse Orbit project provides bundles for common Java libraries such as Apache HttpClient that you can use a dependencies in your plug-in.

Implementing UI extension points

You have to create following list of Extensions from Plug-in Manifest Editor tab. Create extension org.eclipse.mylyn.tasks.ui.repositories and add:

MytrackerRepositoryConnector

MytrackerConnectorUi

Create extension org.eclipse.mylyn.task.core.templates and add:

Your connector template(s)

Create extension org.eclipse.mylyn.task.ui.editors and add:

MyTrackerTaskEditorPageFactory

Adding repositories:

Note, that each repository must have a unique url

Create UI to editor settings for your repository in MyTrackerRepositorySettingPage:

Implement createAdditionalControls

Override applyTo to store the data in TaskRepository properties so they can be retrieved and used later. Note, that you must call super.applyTo() when overridding this method.

Query support

To create new queries, you have to implement the AbstractRepositoryConnector.performQuery() method.

MytrackerConnectorUi.getQueryWizard() must return a Wizard instance (or null if queries are not supported)

Return an instance of RepositoryQueryWizard that and a page that extends AbstractRepositoryQueryPage

When the wizard is completed MyTrackerConnector.performQuery in your connector will be triggered. Fetch all matching tasks and call resultCollector.accept(taskData) for each. Implement MyTrackerConnector.hasTaskChaned and MyTrackerConnector.updateTaskFromTaskData to update tasks in the task list from the received query results.

Task editor

What is required to add an editor for my connector?

Each connector must supply an editor for their task type unless they are displaying their task via a web page. A simple yet full featured editor can be made easily:

1) Create a MyTaskEditor class that extends AbstractTaskEditorPage. For an example of how simple the editor code can be see the TracTaskEditorPage.

2) Create a page factory specific to your task type which extends AbstractTaskEditorPageFactory
To continue with the Trac connector as an example see the TracTaskEditorPageFactory

The factory you are building will be used by TaskEditor, a multi page editor), to load your particular editor and display it along with the other pages such as the context page. The TracTaskEditorPageFactory also shows how to return a web page as an editor in order to display the task as a web resource using a BrowserFormPage.

3) Declare your page factory in your plugin.xml using the org.eclipse.mylyn.tasks.ui.editors extension point. Here is the corresponding definition for TracTaskEditorPageFactory which is found in the trac.ui plugin.xml:

Task editor based on AbstractTaskEditorPage class consists of parts (displayed as sections of editor in the UI). Mylyn comes with several existing parts (subclasses of AbstractTaskEditorPart): TaskEditorAttributePart, TaskEditorCommentPart, ... Each part is responsible for showing and editing of subset of task.

TaskEditorAttributePart will display all "visible" task attributes it finds. If attribute is read-only, it is displayed in non-editable widget. Here is sample code which creates attribute be used by TaskEditorAttributePart:

attrType can be one of TaskAttribute.TYPE_* constants, or your custom constant. Type determines widget (subclasses of AbstractAttributeEditor) to be created. You can have custom editors too (in this case you'll need to use custom AttributeEditorFactory, and return it from your AbstractTaskEditorPage subclass).

isVisible determines whether TaskEditorAttributePart should display this attribute or not. Invisible attributes are useful for storing data in a task which you don't want to present to user, or which you want to present in some other way (or in other part)

readOnly -- determines if user can edit this attribute via UI.

Displaying comments with TaskEditorCommentPart

The task editor part created by TaskEditorCommentPart can be used to display a list comments associated with a task. This part is included by default in your task editor page by the behavior defined in AbstractTaskEditorPage. Upon initialization, it selects a subset of the current task's attributes for display as comments based on its own criteria.

The easiest way to create attributes that it will select is to use the TaskCommentMapper class. Here is an example of how you might add comment attributes to a TaskData object. These attributes will automatically be displayed by the task comment editor part.

publicvoid updateTaskDataWithComments(
TaskRepository taskRepository,
TaskData taskData,
YourNativeTask nativeTask // a representation of a task in the database you're connecting to{// Initialize a counter, since you want to number each task, since the editor part likes to display// them with numbers.int count =0;// Loop through the comments in your native database.for(YourNativeComment nativeComment : nativeTask.getComments()){
TaskCommentMapper mapper =new TaskCommentMapper();// Create a new one each time, to be safe.// Set properties and text associated with this comment.
mapper.setAuthor(taskRepository.createPerson(nativeComment.getTaskCreator().getName()));
mapper.setCreationDate(nativeComment.getCreationDate());
mapper.setText(nativeComment.getBodyText());
mapper.setNumber(count);// Create, in the task data object, a new attribute that will hold this comment.
TaskAttribute attribute = taskData.getRoot().createAttribute(TaskAttribute.PREFIX_COMMENT+ count);// Ask the mapper to copy the properties and text into the new attribute.
mapper.applyTo(attribute);
count++;}}

Offline data handling

Mylyn's offline data handling supports a number of features including: incoming/outgoing notification, rich offline editing, instant open of issues. All of these capabilities can be extended to your connector through implementation of a few interfaces. In general, the bulk of the information related to a task (i.e. long description, comments, and various attributes) are held in another class, TaskData. The framework manages the TaskData on behalf of the connectors. For offline support to work, each connector is responsible for retrieving and sending task data to and from the remote repository. Lightweight ITask objects which are updated from TaskData hold the information necessary for display in Mylyn's task list but little more.

To add offline support for your connector:

Extend AbstractTaskDataHandler (i.e. MyConnectorTaskDataHandler) - the interface through which TaskData is sent to (and received from) your repository. Behind this interface you will do the marshaling necessary to present your native repository data in RepositoryTaskData form.

Implement MyRepositoryConnector.updateTaskFromTaskData() - this is where you populate ITask object with information from the TaskData

Optionally extend TaskAttributeFactory (i.e. MyConnectorAttributeFactory) - this class does the work of mapping your repository's native attribute ids to ids understood by Mylyn (along with a few other utility functions) (see BugzillaAttributeFactory as an example)

Related classes:

TaskCommentMapper for managing comments on TaskData

TaskAttachmentMapper for managing attachments on TaskData

TaskOperation for creating actions that operate on TaskData

Accessing the Task List (Mylyn 2.x)

Get the Task List:

TaskList taskList = TasksUiPlugin.getTaskListManager().getTaskList();

Retrieve all categories:

Set<AbstractTaskCategory> categories = taskList.getCategories();

Retrieve all queries:

Set<AbstractRepositoryQuery> queries = taskList.getQueries();

Call getChildren() on these returned types to get all AbstractTask objects contained within.

Deployment tips (Eclipse 3.3 and earlier)

Use Plug-in Editor to open META-INF/MANIFEST.MF

From Overview page click on Export Wizard and generate .jar for both core and ui plugin.

You have to generate the plugin jars with appropriate Eclipse version, for example check out your connector plugins for Eclipse 3.2.1 and generate 3.2 version of connector plugins, then checkout your connector plugins for Eclipse 3.3 and generate 3.3 version of connector plugins.

Exit Eclipse copy the jars into eclipse/plugins directory and start eclipse with -clean option the first time

Open Task Repositories view and try to add new repository with your connector

If you do not see your connector, check Error Logs view for any errors

Note, that generating valid version of the plugins can be frustrating experience. Be patient and explore Error Logs view if your connector does not appear in the Task Repositories view Add Task Repository dialog.

Here are few things to check if your connector fails to appear in the Add Task Repository dialog (usually the error is ClassNotFound exception):

Make sure you have . (dot) in the bin.includes, source.includes of your build.properties file of both connector plugins

Make sure you have . (dot) in the Bundle-ClassPath property of the META-INF/MANIFEST.MF file of both connector plugins

Check the generated .jar files with unzip tool (7-Zip and others) to make sure that your libraries and classes are present in the jar

Do not rely on Eclipse Plugin Manifest Editor, check the both build.properties and META-INF/MANIFEST.MF in Text Editor

Start Eclipse with -clean option the first time after you deploy your connector.

Duplicate Detectors

Mylyn provides an extension point that allows contributors to create duplicate detectors. Each duplicate detector can use its own algorithm to determine if any similar bugs exist in the bug repository. Duplicate detection can happen in one of two ways:

Client-side: detectors that can rely entirely on the task repository's search facilities to issue a query that returns a set of potentially relevant tasks, then do client-side analysis of the contents of the results. For example, a Java stack trace detector can search for all tasks that refer to a type name, and then use heuristics to identify and rank the most relevant ones (e.g. based on where it appears in the stack trace).

Server-side: some detectors require access to the all of the task data in the repository and are best implemented server-side. For example, a natural language matcher that checks every comment would be too cumbersome and could require too much network traffic to implement client-side. Such detectors can be integrated with Mylyn via a web service API.

Refer to org.eclipse.mylyn.internal.tasks.ui.search.StackTraceDuplicateDetector can be used as a reference implementation.

When you create a duplicate detector, you need to specify the extension in the plugin.xml file. Below is the entry from the
org.eclipse.mylyn.tasks.ui plugin.xml file, as an example:

The class attribute of the detector extension is required and must be a subclass of org.eclipse.mylyn.tasks.core.AbstractDuplicateDetector. The name is also required and must be a string. The name attribute will be displayed on the New Repository Task editor, so make sure it is short but descriptive. There is also an optional kind attribute - this attribute allows you to specify what kind of repository your duplicate detector works with. If you leave the kind attribute blank, your duplicate detector may be displayed in the duplicate detector list for every repository (i.e., users could choose to use your detector regardless of the type of repository that they are using)

The default behaviour is for every task editor page that uses TaskEditorDescriptionPart to display all of the duplicate detectors that are available.

Specify the extension (as shown above) in the plugin.xml file in the same plugin as your duplicate detector class and your subclass of SearchHitCollector.

Adding presentations to the Task List view

Mylyn provides an extension point to contribute custom presentations for the Task List view. Contributed presentations will appear in the drop down list on the Task List toolbar. Each presentation must specify a means of creating a content provider for a particular instance of the TaskListView, as specified by the AbstractTaskListPresentation, a subtype of which must be provided.

Content provider implementation should be a subclass of the AbstractTaskListContentProvider or one of its subclasses.

Context API

Mylyn provides a task-focused interface for Eclipse, which affects the way that view filtering, expansion and decoration work. This boils down to viewers and editors showing only the structural information relevant to a task (e.g. Bugzilla report) instead of all of the underlying information available in the corresponding content provider(s).

The following resources provide an overview of the facilities and their impact on viewers and a summary is provided below.

The following task-focused interface mechanisms affect views and viewers:

Filtering: uninteresting elements are filtered from the view by an InterestFilter which is applied when the view is focused. Applying the interest filter causes all other viewer filters to be removed, since the InterestFilter hides all elements by default. Filtering requires the view to be lazily refreshed based on task context model changes in addition to content changes.

Expansion and linking: focused viewers always have their nodes expanded by default and are always linked to the editor, since they are much less likely to show a scrollbar.

Decoration: all focused viewers use a lightweight platform decorator to indicate interest level (e.g. gray is uninteresting and bold font is a very interesting element).

Ranking: sort order can be changed to bring the most interesting elements to the top (e.g. in a table viewer or a content assist list)

Editor management: open editors are automatically matched to the task context (e.g. all closed when a task is deactivated, all restored when reactivated, if an element decays in interest the editor auto closes).

Perspective management: perspectives are automatically associated with tasks and activated when tasks are switched.

Bridges

Mylyn relies on Bridges to integrate the context model with the structure and UI features of domain-specific tools. There are two kinds of bridges:

Structure Bridge: maps domain-specific elements and relationships to the generic handleIdentifiers understood by the structure model.

UI Bridges: integrate Mylyn facilities, such as the Focus on Active Task button, with editors and views.

Extension point is: "org.eclipse.mylyn.context.ui.bridges: uiBridge

The core set of Bridges supports the Eclipse SDK:

Resources (i.e. files and folders)

Java and JUnit

PDE and Ant XML editing

How it works: Generic workbench UI monitoring facilities (org.eclipse.mylyn.monitor), translate interaction with domain-specific elements (e.g. Java methods) into an interaction history. The context manager (org.eclipse.mylyn.context.core) relies on a structure bridge to create a context model from these elements and from the relations between the elements. The structure bridge is also used by the Focused UI facilities to map elements that show in views and editors to the context model, in order to determine their interest rank. This ranking is then used for filtering and folding elements.

Resource Bridge

The generic ResourceStructureBridge provides a basic level of interoperability with other tools that use files (e.g. .php, .cpp), and enables Mylyn filtering to work for generic views that shows those files (i.e. the Project Explorer, Navigator) and any corresponding markers (i.e. the Problems and Tasks views). This is only the most basic context model integration, and does not offer the benefits of a specialized structure bridge, such as making declarations part of the context and providing Active Search facilities. Without a bridge Mylyn also can not be applied to tool-specific views.

To extend Mylyn to other kinds of structure and tools create a new structure bridge and model it on the one in org.eclipse.mylyn.java.

Excluding Elements

If an element should not participate in the task context, but can be interacted with by the user, the AbstractContextStructureBridge.getHandleIdentifier(Object) method should return null for the element. For example, in the case of Java null could be returned for implicitly uninteresting elements such as import statements.

Excluding Resources

Resource patterns can be excluded manually by the user via the Mylyn -> Resources preference page. To add defaults to this page use the following extension point:

If the contributing bundle is not guaranteed to be activated on task activation it may also be necessary to implement a context startup extension to ensure correct enablement of the focus action.

Processing interaction

The context model is a transformation of an interaction history. The only way to change or affect the model is to issue InteractionEvents. For an example of how to translate interaction with UI facilities such as views and editors, see:

AbstractUserInterctionMonitor

JavaEditingMonitor

Direct manipulation

The model can be mainpulated directly by issuing special kinds of InteractionEvents. For an example see:

AbstractInterestManipulationAction and subclasses.

Team API

Mylyn provides several key features that facilitate working with version control systems.

Change set management

Automatic change set management (see Mylyn User Guide#Team Support) creates change sets for tasks on the user's behalf, and enables automatic commit messages. There are two ways to implement this support.

Relying on the Platform/Team ActiveChangeSetManager

This is the way that the current CVS and SVN providers do it, and involves providing the following extension point as shown with this example of how it works for CVS:

Where the CvsActiveChangeSetProvider is a subclass of AbstractActiveChangeSetProvider.

This will result in Mylyn's org.eclipse.mylyn.internal.team.ContextActiveChangeSetManager bridging between the Platform/Team change sets and the task context model.

Note that the change set manager must be a subtype of org.eclipse.team.internal.core.subscribers.ActiveChangeSetManager. 'This means relying on an internal class, and as such is not guaranteed to be backwards compatible. Consider voting to make this class API for Eclipse 3.3 (bug 116084).

Re-implementing change set management

It is possible to provide an alternate change set bridge in order to avoid extending the internal class as above, or if a different change set management mechanism is used. Do this via the contextChangeSetManager extension point, and as an example implementation you can use ContextActiveChangeSetManager which provides the bridging for the Platform/Team change sets described above.

Mapping from comments to tasks

The Open Corresponding Task action allows the user to navigate from change sets in "Synchronize" view or from History view to the task (e.g. bug report).

To support for Open Corresponding Task action in "Synchronize" and "History" views, the team provider should register IAdapterFactory that should adapt to ILinkedTaskInfo. This way, proprietary artifacts shown in these views won't have hard dependency on Mylyn's classes. If hard dependency on Mylyn classes is acceptable, you can also make your artifacts implement IAdaptable interface and directly adapt to ILinkedTaskInfo.

This factory should return adapter as quick as possible to not slow down the UI because adapter will be queried and created for nearly every popup menu.

Mapping from projects to Task Repositories

Mylyn allows contribution of a project link provider which maps from workspace projects to task repositories. ProjectPreferencesLinkProvider is contributed by the org.eclipse.mylyn.tasks.ui plugin and stores the required information in the project settings. Custom link providers can use metadata from other sources, such as version control system (i.e. Subversion properties) or Maven POM. Use org.eclipse.mylyn.tasks.ui.projectLinkProviders extension point to register link provider. For example:

Examples

The UI Usage Report wizard can be used as an example of how to report on usage activity. The main class for this is currently UsageSummaryReportEditorPart and the project of interest is org.eclipse.mylyn.monitor.usage

Note that this project relies on upload scripts that are currently disabled. Send questions about reusing it to mylyn-dev.

Overview

The Mylyn Monitor is a separately installable component that collects information about a user’s activity in Eclipse. Clients of the monitor include the Context UI, which transforms interaction into a degree-of-interest model, and user study plug-ins, which can report on Eclipse usage trends. The org.eclipse.mylyn.monitor plug-in is structured to accept listeners to different Eclipse events, currently including preference changes, perspective changes, window events, selections, commands invoked through menus or key bindings and URLs viewed through the embedded Eclipse browser. The InteractionEvent class used by the monitor encapsulates a user or tool interaction.

The org.eclipse.mylyn.monitor.usage plug-in supports the transparent capture of these events into a local file and the upload of these events to an http server. The uploading mechanism includes functionality to track anonymous IDs for users, to obfuscate the handles of targets of selections and other such user data that may be collected, and to prompt the user to view and send the log to an http server. The Monitor also detects and reports in the trace when there has been a period of inactivity with Eclipse. Extension points in org.eclipse.mylyn.monitor.usage allow user study plug-ins to use the monitoring facilities. The Usage Monitor manages the size of traces produced by the Mylyn Monitor through compression, using a zipped format that significantly reduces the size of the files. The repetitiveness of user activity typically yields compression ratios over 95%, with a month of typical full-time programming activity resulting in an approximately 1MB zip.

To help with the analysis of traces collected with the Mylyn Monitor, the org.eclipse.mylyn.monitor.reports plug-in provides infrastructure for collecting and summarizing data across one or more traces. This reporting package provides an API to process records for a user across one or more trace files in a chronological order.

Interaction events

Streams

Mylyn currently has two consumers of the user's interaction event streams issued by the monitor:

Task Context model: all events that contribute to the degree-of-interest of elements are consumed, and externalized to zipped XML files in the .metadata/.mylyn/contexts directory. Currently the interaction event kinds included are selection, edit, propagation, prediction.

Interaction event logger: the logger in ..mylyn.monitor.usage consumes all events and appends them to .metadata/.mylyn/monitor-history.xml if logging is enabled in the Monitor preference page. This stream includes additional events that are monitored, such as preference changes.

Attributes

Note that if events are collapsed (i.e. multiple events are combined into a single one) the EndDate and Interest fields capture the aggregate information. These fields should not be used otherwise, since interaction events should be considered immutable and should not directly represent interest.

Kind: determines the type of interaction that took place (see listing below)

OriginId: the UI affordance that the event was issued from

StructureKind: the content type of the elementbeing interacted with

StructureHandle: a unique identifier for the element being interacted with

Navigation: an identifier for the kind of relation that corrsponds to the navigation to this element

StartDate: time stamp for the occurence of the event

EndDate: if an aggregate event, time stamp of the last occurrence

Delta: additional information relevant to interaction monitoring

Interest: if an aggregate event, amount of interest of all contained events (note: may be removed since interest should not be stored on events)

Event Kinds

Depending on which stream you are using, the interaction events may contain non user-initiated interactions such as interest propagations. In general, selection, edit and command events are the ones that initiate from the user, while propagation and prediction events originate from a tool.

NOTE: refer to the InteractionEvent Javadoc for the most up-to-date documentation of kinds.

Propagation: elements determined to be structurally related, such as the parent chain in a containment hierarchy

Manipulation: direct manipulation of interest via "Mark as Landmark" and "Mark Less Interesting"

Attention: interaction with a task, used for the meta-context

Extensibility

Interested developers can provide notification of other events by generating their own InteractionEvents, and injected using MonitorUiPlugin.getDefault().notifyInteractionObserved(InteractionEvent). InteractionEvents are assumed to be immutable and thus their fields are defined as string instances. The "delta" field can be used for adding additional information to an event. As loggers of InteractionEvents are to be content-agnostic and transparently encode and decode these fields, more complicated information may be provided as an XML-encoded string in the delta field. The Apache Ant project's org.apache.tools.ant.filters.StringInputStream class may be helpful for processing such fields afterwards.

Uploading interaction histories

The current code relies on CGI scripts that are not CVS, but that are deprecated and will be replaced by Servlets. If you would like a copy of the CGI scripts please email mylyn-dev.

Headless and standalone use

The tasks core API in org.eclipse.mylyn.tasks.core allows generic access to supported bug/task/ticket/issue trackers. In order to connect to a specific repository a connector implementation that supports the tasks core API is required.

Bugzilla API

The Bugzilla connector core implementation is available in org.eclipse.mylyn.bugzilla.core. The provisional Bugzilla API can be used independently of the Eclipse Workbench and Mylyn UI facilities as a Java API to Bugzilla. Also see the Mylyn Architecture document.

A good way to get started is to run the test case as a JUnit test and work from org.eclipse.mylyn.bugzilla.tests/src/org.eclipse.mylyn.bugzilla.tests.headless.

Mylyn dependencies

org.eclipse.mylyn.bugzilla.core

org.eclipse.mylyn.commons.core

org.eclipse.mylyn.commons.net

org.eclipse.mylyn.tasks.core

Eclipse dependencies (need to be on classpath but the platform does not need to be running)

Quick Example

Save the team project set, and then use File > Import > Team Project Set in Eclipse to import the source code. Use username "anonymous" and an empty password.

Use File > Export > Runnable JAR file to create a jar file. Select Bugzilla Example as the launch configuration and enter a filename for the export destination. The export wizard will automatically package all required dependencies based on a Run configuration into a single JAR file that can be run without Eclipse.

The wizard may display an error JAR creation failed. See details for additional information. and lists compile warnings and duplicate entries in the details section. These warnings can be ignored and will not affect running the JAR file as a standalone application.

You can invoke the standalone example by running java -jar example.jar.

Context API (org.eclipse.mylyn.context.core)

When Mylyn is running within the full eclipse platform, the org.eclipse.mylyn.tasks.ui plugin specifies where the contexts should be stored. When running without the org.eclipse.mylyn.tasks.ui plugin, you must specify this location yourself.