We recommend that those interested in integrating Mylar email firstname.lastname@example.org regarding for pointers to examples and guidance on upcoming changes. We encourage integrators to take the "act now, apologize later" 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.
- 1 Building on Mylar
- 2 Tasks API
- 2.1 Task repository requirements
- 2.2 Integrating with Mylar's Task List vs. using a custom view
- 2.3 Creating connector projects
- 2.4 Implementing core extension points
- 2.5 Implementing UI extension points
- 2.6 Query support
- 2.7 Task editor
- 2.8 Offline data handling
- 2.9 Attachment support
- 2.10 Deployment tips
- 3 Context API
- 4 Team API
- 5 Monitor API
- 6 Headless use
Building on Mylar
Also see: Mylar Porting Guide for porting from Mylar 1.0 to the 2.0 stream.
When integrating Mylar with an existing tool, we recommend creating a new feature that declares a dependency on both the corresponding Mylar 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 Mylar is installed before allowing the new feature. The Subversive can be used as an example of this.
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.
Deciding on a version
We suggest targeting the Mylar 2.0 stream because we will be encouraging all users to update to the milestones and will not be destabilizing. So check out the HEAD project set. The main cost of building against the 2.0 stream is that the APIs will be evolving so you will want to periodically check the Mylar Porting Guide. Note that if you build against the HEAD stream your plug-in will most likely support both Eclipse 3.3 and 3.2 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 3.2 before you deploy.
Watching API changes
If you are developing against the Mylar 2.0 stream, you can watch for breaking API changes by creating a query for all Mylar bugs tagged
[api]. Major API changes will be announced on the mylar-dev mailing list.
Also see: Mylar Porting Guide
A tutorial with screenshots is available here: http://jvliet.blogspot.com/2007/02/creating-mylar-connector-plugin-for.html.
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 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 Mylar 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.mylar.provisional.tasklist). For basic operation you should first implement importing existing tasks from the repository. Therefore you need to implement the methods getRepositoryType, canCreateTaskFromKey and createTaskFromExistingKey. You need to implement a custom task (which should inherit from AbstractRepositoryTask). Use the Trac connector as an example. After creating a stub repository connector, you have to connect to the extension point "org.eclipse.mylar.tasklist.repositories". You can just omit an externalizer specification for now. If your first basic plugins works, you should handle synchronization. Please note that the method for synchronization is called updateOfflineState (AbstractRepositoryConnector) instead of just synchronize(). The next step is to write a TaskExternalizer (extend DelegatingTaskExternalizer and add the declaration to your plugin.xml).
Here are some you should create for your connector:
- MytrackerCorePlugin extends Plugin
- MytrackerRepositoryConnector extends AbstractRepositoryConnector
- MytrackerRepositoryTask extends AbstractRepositoryTask
Tips on adding external library JARs:
- To add external jar, create lib directory in the ...core plugin, place the jar(s) to the lib directory. Then in the plugin MANIFEST.MF, add the lib/...jar(s) to the Bundle-ClassPath property. If you do not do that, you will get ClassNotFoundException even if the jar(s) are in your Eclipse build path.
- Add the same library path to the bin.includes property of build.properties file. Make sure that . (dot) path is also included in both Bundle-ClassPath and bin.includes properties, otherwise you will get ClassNotFoundException when debugging and deploying the connector.
Implementing UI extension points
You have to create following list of Extensions from Plug-in Manifest Editor tab. Create extension
org.eclipse.mylar.tasks.ui.repositories and add:
Create extension org.eclipse.mylar.task.core.templates and add:
- Your connector template(s)
Create extension org.eclipse.mylar.task.ui.editors and add:
Adding Connector Repository specific data
- Note, that repository url has to be unique.
- Create UI for the custom specific data in MyTrackerRepositorySettingPage
- Override/implement createAdditionalControls()
- Pverride/implement updateProperties() to store the data in TaskRepository properties so they can be retrieved and used later
To create new queries, you have to implement the
AbstractRepositoryConnector.performQuery() method. This requires the creation of subclasses for:
To modify default label and description of your implementation of AbstractQueryHit which encapsulates repository task displayed in the query category, you should override methods getIdLabel() and/or getSummary().
Creating a MyTrackerTaskEditor:
- SubmitToRepository() returns Status with task id retrieved in Status.getMessage() in <Connector>RepositoryConnector.createTaskFromExistingKey()
Creating a NewMyTrackerTaskEditor
- Used for creating new tasks, similar to above.
Task Editor Attributes:
- Task Editor uses RepositoryTaskAttribute class to pass repository task attributes between the UI and the connector. Most of the connector
has its own attributes class. The class MyTrackerTaskAttributeFactory (extends AbstractAttributeFactory) method mapCommonAttributeKey() is used to map connector attributes to the RepositoryTaskAttribute attributes.
- implement setupNewBugAttributes() in ...MyTracker and create
RepositoryTaskAttribute a = CodeBeamerClient.makeNewAttribute()
- implement enum ...ReportElement class and define attributes there
- implement attribute mapping in ...TaskAttributeFactory
Offline data handling
MyTrackerTaskDataHandler which should implement
ITaskDataHandler is the interface through which
RepositoryTaskData is communicated between Mylar and your repository.
RepositoryTaskData is Mylar's representation of all the data associated with a repository task, is used by the rich editor, and is cached offline. Behind this interface you will do the marshaling necessary to present your native repository data in
RepositoryTaskData is to be used directly, not extended.
RepositoryOperation (to be deprecated as part of bug#150680)
Defines the valid operations for this particular task (resolve, close, etc.).
Task comments (
TaskComment) are also stored in the
RepositoryTaskData. Each comment should have the following attributes set:
RepositoryAttachment) are also held by the
- 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.
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.
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.
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.
Mylar provides several key features that facilitate working with version control systems.
Change set management
Automatic change set management (see Mylar 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:
<extension point="org.eclipse.mylar.team.changeSets"> <activeChangeSetProvider class="org.eclipse.mylar.internal.team.ccvs.CvsActiveChangeSetProvider"/> </extension>
CvsActiveChangeSetProvider is a subclass of
This will result in Mylar's
org.eclipse.mylar.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.
<extension point="org.eclipse.mylar.team.changeSets"> <contextChangeSetManager class="org.eclipse.mylar.internal.team.ContextActiveChangeSetManager"/> </extension>
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 Mylar's classes. If hard dependency on Mylar 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
Mylar allows contribution of a project link provider which maps from workspace projects to task repositories. ProjectPreferencesLinkProvider is contributed by the org.eclipse.mylar.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.mylar.tasks.ui.projectLinkProviders extension point to register link provider. For example:
<extension point="org.eclipse.mylar.tasks.ui.projectLinkProviders"> <linkProvider class="org.tigris.subversion.subclipse.mylar.SubclipseTaskRepositoryLinkProvider" id="org.tigris.subversion.subclipse.mylar.taskRepositoryLinkProvider" name="Subclipse Link Provider" order="100"> </linkProvider> </extension>
Important attribute is order. Recommended values are:
- 1000 for generic or custom metadata
- 100 for metadata from the version control systems
- 10 for metadata from the project or build management systems
Implementation class should extend org.eclipse.mylar.tasks.ui.AbstractTaskRepositoryLinkProvider and provide at least getTaskRepository() method.
Distributing your extension
We recommend using one of the following options:
- 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
If you would like your update site linked from the Mylar update site please send an email to the mylar-dev mailing list.
- The Using task context to improve programmer productivity paper discusses interaction monitoring and interaction events.
- The How are Java software developers using the Eclipse IDE? article describes a user study done with the monitor.
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
For a user study example checkout:
Note that this project relies on upload scripts that are currently disabled. Send questions about reusing it to mylar-dev.
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.
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. This stream includes additional events that are monitored, such as preference changes.
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.
- Selection: user selection of elements, issued by the Eclipse post-selection mechanism
- Edit: edit events that are created by text selections in the editor
- Command: commands and actions invoked via buttons, menus, and keyboard shortcuts
- Preference: workbench preference changes
- Prediction: elements determined relevant by Active Search
- 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"
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. 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 mylar-dev.
The headless framework bundle available as a separate download. Running it requires J2SE 1.3 and the following plug-ins/JARs:
Tasks API (org.eclipse.mylar.tasks.core)
This API allows generic access to supported bug/task/ticket/issue trackers.
Bugzilla API (org.eclipse.mylar.bugzilla.core) Headless Use
We maintain examples of headless Bugzilla API in test cases. A good way to get started is to run the test case as a JUnit test and work from there:
The provisional Bugzilla API can be used independently of the Eclipse Workbench and Mylar UI facilities as a Java API to Bugzilla. Also see the Mylar Architecture document.
- Mylar dependencies
- Eclipse dependencies (need to be on classpath but the platform doesn't need to be running)
- Apache libs (can be found in the org.eclipse.mylar plugin folder)
BugzillaRepositoryConnector connector = new BugzillaRepositoryConnector(); connector.init(new TaskList()); TaskRepository repository = new TaskRepository(BugzillaCorePlugin.REPOSITORY_KIND, "http://bugzillarepository.com"); repository.setAuthenticationCredentials("userid", "password");
// If site protected by http authentication repository.setHttpAuthenticationCredentials("httpauthuserid", "httpauthpassword");
// Get the report from repository AbstractRepositoryTask task = connector.createTaskFromExistingKey(repository, "2"); // bug number 2
// Access task information System.err.println(task.getSummary()); System.err.println(task.getPriority()); // Access/set report data via common attribute keys: task.getTaskData().getAttributeValue(RepositoryTaskAttribute.USER_ASSIGNED); task.getTaskData().setAttributeValue(RepositoryTaskAttribute.USER_ASSIGNED, "rob"); task.getTaskData().setAttributeValue(RepositoryTaskAttribute.PRIORITY, "P2");
// ...or by Bugzilla keys task.getTaskData().getAttributeValue(BugzillaReportElement.BUG_SEVERITY.getKeyString()); task.getTaskData().setAttributeValue(BugzillaReportElement.BUG_SEVERITY.getKeyString(), "critical");
// Post modified report to repository connector.getTaskDataHandler().postTaskData(repository, task.getTaskData());
- 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.
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().