Skip to main content
Jump to: navigation, search

Difference between revisions of "Mylyn/Integrator Reference"

(Headless APIs)
Line 75: Line 75:
  
 
com.example.HardCodedContextStore must extend org.eclipse.mylar.context.core.AbstractContextStore and implement  getRootDirectory().
 
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 <tt>org.eclipse.mylar.monitor</tt> 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 <tt>InteractionEvent</tt> class used by the monitor encapsulates a user or tool interaction.
 +
 +
The <tt>org.eclipse.mylar.monitor.usage</tt> 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 <tt>org.eclipse.mylar.monitor.usage</tt> 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 <tt>org.eclipse.mylar.monitor.reports</tt> plug-in that 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.

Revision as of 12:53, 23 August 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.

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 for the Bugzilla Connector, via SOAP for the JIRA Connector). The following are required to support task list integration:

  • Tasks must be uniquely identifiable by a per-repository integer or string handle (e.g. repository: https://bugs.eclipse.org/bugs, id 138144)
  • Mechanism for executing a string-based query and returning task IDs (e.g. submit query via SOAP, retrieve matching task IDs)
  • Mechanism for accessing all of the task attributes (e.g. description, priority, comment thread)

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)

The following additional mechanisms enable task authoring:

  • 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)
  • Setting any of the task's attributes (e.g. changing components, reassigning)
  • Adding and retrieving attachments (e.g. adding screenshots)

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

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.

Headless Frameworks & APIs

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 that 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.

Back to the top