Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Mylyn/Integrator Reference"

(Mylar Monitor)
m (Integrating Team Providers)
Line 67: Line 67:
 
= Integrating Team Providers =
 
= Integrating Team Providers =
  
Mylar provides two key features that facilitate working with source repositories, and a reference implementation for CVS is available in the <tt>org.eclipse.mylar.team</tt> plug-in:
+
Mylar provides several key features that facilitate working with version control systems.
 +
 
 
* Automatic change set management (see [[Mylar FAQ#Team Support]])
 
* Automatic change set management (see [[Mylar FAQ#Team Support]])
 
* Automatic commit messages
 
* Automatic commit messages
* ''Open Corresponding Task'' button to allow the user to navigate from commit messages in the ''History'' view to the task (e.g. bug report).
+
* ''Open Corresponding Task'' action to allow the user to navigate from change sets in "Synchronize" view or from ''History'' view to the task (e.g. bug report).
 +
 
 +
Reference implementation of those features for CVS is available in the <tt>org.eclipse.mylar.team</tt> plug-in.
 +
 
 +
To support first two features, the team provider needs to implement the <tt>org.eclipse.mylar.team.providers</tt> extension point.  This involves implementing the <tt>AbstractTeamRepositoryProvider</tt> class by providing a reference to the provider's change set manager, and a mechanism for executing a commit.  Assuming a change set implementation similar to Eclipse CVS, the implementation should be minimal and only require bridging to the provider's change set implementation. 
 +
 
 +
Note that the change set manager must be a subtype of <tt>org.eclipse.team.internal.core.subscribers.ActiveChangeSetManager</tt>.  This means relying on an internal class, so consider voting to make this class API for Eclipse 3.3 ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=116084 bug 116084]).
 +
 
 +
To support for ''Open Corresponding Task'' action in "Synchronize" and "History" view, the team provider should register <tt>IAdapterFactory</tt> that should adapt to <tt>ILinkedTaskInfo</tt>. This way, proprietary artifacts shown in these views won't have hard dependency on Mylar's classes.
 +
 
 +
The <tt>org.eclipse.mylar.internal.team.ccvs.CvsRepositoryProvider</tt> can be used as a reference implementation. There is also known implementation for [http://subclipse.tigris.org/ Subclipse].
 +
 
 +
There are two options to package your plugin:
 +
 
 +
* have a separate plug-in for the Mylar integration and create an optional feature with dependencies on Mylar's features
 +
* make Mylar an optional dependency of your plug-in. This can be done via <tt>Require-Bundle: org.eclipse.mylar.team;resolution:=optional</tt>
  
To integrate, the team provider needs to implement the <tt>org.eclipse.mylar.team.providers</tt> extension point.  This involves implementing the <tt>AbstractTeamRepositoryProvider</tt> class by providing a reference to the provider's change set manager, and a mechanism for executing a commit.  Assuming a change set implementation similar to Eclipse CVS, the implementation should be minimal and only require bridging to the provider's change set implementation.  Note:
+
<!--
* The change set manager must be a subtype of <tt>org.eclipse.team.internal.core.subscribers.ActiveChangeSetManager</tt>.  This means relying on an internal class, so consider voting to make this class API for Eclipse 3.3 ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=116084 bug 116084]).
+
* The <tt>org.eclipse.mylar.internal.team.ccvs.CvsRepositoryProvider</tt> can be used as a reference implementation.
+
* The recommended packaging is either to make a seperate plug-in for the Mylar integration or to make Mylar an optional dependency of your plug-in. This can be done via <tt>Require-Bundle: org.eclipse.mylar.team;resolution:=optional</tt>
+
 
* The Subclipse provider is currently being incubated in the <tt>org.eclipse.mylar.team</tt> plug-in, and can be used as an example of implementing the optional dependency.
 
* The Subclipse provider is currently being incubated in the <tt>org.eclipse.mylar.team</tt> plug-in, and can be used as an example of implementing the optional dependency.
 +
-->
  
 
= Headless Frameworks & APIs =
 
= Headless Frameworks & APIs =

Revision as of 02:19, 5 December 2006


We recommend that those interested in integrating Mylar email mylar-dev@eclipse.org regarding for pointers to examples and guidance on upcoming changes. Also see: Mylar Architecture

Extensibility overview

Following the Eclipse conventions, Mylar will not make any API guarantees until the 1.0 release. However, a driving goal of the Mylar project is to provide a task management and focused UI framework that can be easily extended by any Eclipse SDK and RCP based applications. The Mylar components are loosely coupled by preliminary extension points and APIs, and these will be stabilizing between the 0.5 and 1.0 releases.

Workspace Setup

The recommended workspace setup for integrators is check out the projects to be extended from CVS. Instructions and project sets are available on in the Workspace Setup documentation. If you would like a downloadable distribution that is not available on the download page please submit a bug report.

Creating Connectors

The Tasks API is still maturing, and currently the recommended way to get started with creating a connector is to refer to the implementation of the mylar.jira or mylar.trac connectors. Also refer to the slightly out-of-date Creating Mylar Connectors page (please add new documentation on connectors to this page).

Task repository requirements

Mylar can be extended to any task/bug/issue/story repository or tracker by creating a repository Connector that links Mylar'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)
  • Retrieving a user's saved queries (e.g. searches or filters saved via the web UI)

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

The Mylar 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 changes 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 ..mylar.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 Mylar'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 Mylar'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 to involve one or more disparate bug/task/issue/ticket management views, developers can 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-mylar1/

The other thing to consider is integration with Mylar'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-mylar2

Creating Bridges

Mylar 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.
    • Extension point is: org.eclipse.mylar.context.core.bridges: structureBridge
  • UI Bridges: integrate Mylar facilities, such as the Apply Mylar button, with editors and views.
    • Extension point is: "org.eclipse.mylar.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.mylar.monitor), translate interaction with domain-specific elements (e.g. Java methods) into an interaction history. The context manager (org.eclipse.mylar.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 Mylar 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 Mylar also can not be applied to tool-specific views.

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

Integrating Team Providers

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

  • Automatic change set management (see Mylar FAQ#Team Support)
  • Automatic commit messages
  • Open Corresponding Task action to allow the user to navigate from change sets in "Synchronize" view or from History view to the task (e.g. bug report).

Reference implementation of those features for CVS is available in the org.eclipse.mylar.team plug-in.

To support first two features, the team provider needs to implement the org.eclipse.mylar.team.providers extension point. This involves implementing the AbstractTeamRepositoryProvider class by providing a reference to the provider's change set manager, and a mechanism for executing a commit. Assuming a change set implementation similar to Eclipse CVS, the implementation should be minimal and only require bridging to the provider's change set implementation.

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, so consider voting to make this class API for Eclipse 3.3 (bug 116084).

To support for Open Corresponding Task action in "Synchronize" and "History" view, 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 Mylar's classes.

The org.eclipse.mylar.internal.team.ccvs.CvsRepositoryProvider can be used as a reference implementation. There is also known implementation for Subclipse.

There are two options to package your plugin:

  • have a separate plug-in for the Mylar integration and create an optional feature with dependencies on Mylar's features
  • make Mylar an optional dependency of your plug-in. This can be done via Require-Bundle: org.eclipse.mylar.team;resolution:=optional


Headless Frameworks & APIs

The headless framework is available as a seperate download. Running it requires J2SE 1.3 and the following plug-ins/JARs:

  • org.eclipse.core.runtime
  • org.eclipse.osgi
  • org.eclipse.equinox.common
  • org.eclipse.core.jobs
  • org.eclipse.equinox.registry
  • org.eclipse.equinox.preferences
  • org.eclipse.core.contenttype
  • org.eclipse.core.runtime.compatibility.auth

Tasks Framework (org.eclipse.mylar.tasks.core)

This API allows generic access to supported bug/task/ticket/issue trackers.

Bugzilla API (org.eclipse.mylar.bugzilla.core)

The provisional Bugzilla API can be used independently of the Mylar UI facilities as a Java API to Bugzilla. Also see the Mylar Architecture document.

  • Check out the org.eclipse.mylar.tasks.core and org.eclipse.mylar.bugzilla.core projects as described in the Mylar Contributor Reference
  • Run the org.eclipse.mylar.bugzilla.tests.headless.BugzillaQueryTest unit test as an exmaple of using the API.
  • If a facility you need is not available in bugzilla.core file a bug report. Chances are that it is in bugzilla.ui and can be extracted.
  • Create a plugin depending on: org.eclipse.mylar.bugzilla.core AND org.eclipse.mylar.tasks.core, then:
RepositoryTaskData task = BugzillaServerFacade.getBug(repositoryUrl, userName, password,
 proxySettings, characterEncoding, id);

Which gives you access to: task.getAssignedTo(), task.getDescription(), task.getLabel(), task.getLastModified(), task.getRepositoryKind(), etc.

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

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

In plugin.xml for your plugin:

   <extension point="org.eclipse.mylar.context.core.bridges">
  	  	<contextStore class="com.example.HardCodedContextStore"/>
   </extension>

com.example.HardCodedContextStore must extend org.eclipse.mylar.context.core.AbstractContextStore and implement getRootDirectory().

Mylar Monitor

The Mylar 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.mylar.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.mylar.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.mylar.monitor.usage allow user study plug-ins to use the monitoring facilities. The Usage Monitor manages the size of traces produced by the Mylar 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 Mylar Monitor, the org.eclipse.mylar.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.

InteractionEvent streams

Mylar 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 .mylar/contexts directory. Currently the interaction event kinds included are selection, edit, propagation, prediction.
  • Interaction event logger: the logger in ..mylar.monitor.usage consumes all events and appends them to .mylar/monitor-history.xml if logging is enabled in the Monitor preference page.

Extending InteractionEvent

Interested developers can provide notification of other events by generating their own InteractionEvents, and injected using MylarMonitorPlugin.getDefault().notifyInteractionObserved(InteractionEvent). InteractionEvents are assumed to be immutable and thus their fields are defined as string instances. 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. The Apache Ant project's org.apache.tools.ant.filters.StringInputStream class may be helpful for processing such fields afterwards.

Resources

Also see the How are Java software developers using the Eclipse IDE? article which describes a user study done with the monitor.

Back to the top