Re: [mylyn-integrators] AbstractTask vs. RepositoryTaskData in a connect

[Steffen Pingel <steffenp@xxxxxx>]

Hi Tom,

I have added a few notes below. Mylyn 3.0 class names are in [brakets].

On Monday 12 May 2008, Tom Bryan (tombry) wrote:
> Does the class in MyTracker's connector plug-in that extends
> AbstractTask need to carry all of the data that is present in a class
> like TracTicket?
>
> Some background for this question:  I'm reading a thread on
> eclipse.tools.mylyn from October 2007 between Dennis Rietmann and Stefen
> Pingel about the different representations of a task in Trac.
>
> Summarizing something Stefen Pingel said:
> - TracTask: represents the task information in the task list. This is
> kept in memory at all times and contains information needed by Mylyn to
> represent the task in the UI
> - TracTicket: part of a generic API for accessing Trac repositories that
> does not depend on Mylyn.
> - RepositoryTaskData: used for offline editing and offline storage.
>
> Now, for example, say that I have a repository with 50 fields.  Clearly,
> many of those fields will be specific to that repository (for example,
> documenting hardware platform and firmware versions for embedded
> software defects).  I cannot imagine that the Task List UI needs to know
> about those fields.
>
> More specifically, MyTracker has a service for returning a bug.
>
> I use JAXB to generate classes to represent the data returned by the
> service.  That tree of objects roughly corresponds to the TracTicket
> representation.  It's independent from Mylyn, and it contains all of the
> data sent to me by the repository.
>
> Now, I know that I need to put *all* of that data in a
> RepositoryTaskData instance for each task using setAttributeValue and my
> AttributeFactory.  That will permit me to create an editor that shows
> all of these fields.

That is correct. You should store all task fields that are relevant to the 
editor in RepositoryTaskAttribute [TaskAttribute] objects. It is a better 
practice to create attributes and explictly set meta-data and values (Mylyn 
3.0 will require this), e.g.:

  RepositoryTaskAttribute attr 
    = attributeFactory.createAttribute(RepositoryTaskAttribute.SUMMARY);
  attr.setHidden(true);
  attr.setReadOnly(true);
  attr.setValue(value);

Adding to your summary above:

RepositoryTaskData [TaskData] is a hierarchial connector managed data 
structure. It is stored in XML files in the .offline [.tasks] folder. Task 
data is a map of attributes that are identified by unique keys. Each 
attribute has values (list of Strings), options (key-value map of Strings) 
and meta-data (key-value map of Strings). In addition task attributes can be 
nested in Mylyn 3.0.

The format of the data stored in attributes is connector dependent. A mapping 
to Java types is provided through AbstractAttributeFactory [AttributeMapper]. 
This mapping is used for displaying and editing of attribute. In Mylyn 3.0 
each attribute can have a type which is stored in the meta-data by default. 
The type is used by the editor to create a corresponding [AttributeEditor], 
e.g. a date picker for attributes of [TaskAttribute.TYPE_DATE].

> But I also need a MyTrackerTask class that extends AbstractTask so that
> the Task List UI has a representation of the objects, right?  

Yes, Mylyn 2.3 requires connectors to extends AbstractTask. In Mylyn 3.0 task 
objects are entirely managed by the tasks framework and can not be extended 
by connectors. Only an interface [ITask] is exposed that allows updates of 
fields relevant to the connector.

> Are those 
> instances supposed to carry all of these fields, too?  Or are they
> supposed to carry only enough information for the UI?

Instances of AbstractTask [ITask] should have just enough information to 
represent them in the tasks view. It is probably sufficient to simply extend 
AbstractTask and override the few abstract methods without storing additional 
state. This will also make porting to Mylyn 3.0 easier.

> It looks like TracRepositoryConnector.updateTaskFromTicket and
> updateTaskFromTaskData, for example, do not preserve the entire
> valueByKey map of fields from TracTicket or the entire list of
> attributes from RepositoryTaskData.getAttributes (via
> AttributeContainer).  I just want to make sure that I don't lose data or
> hit some horrible Exception because Mylyn didn't have what it needed
> during some user interaction with the Task List UI.

These methods are a one-way mapping from data received from the repository to 
the task list. Mylyn should not make any assumption about the fields updated 
by the connector and the user can always recover from any failures by 
re-synchronizing a task or query. Management of task data and the task list 
externalization is handled separately from these metods and should be robust. 
Please file a bug if you run into scenarios where updates to a task object is 
causing horrible exceptions.

Steffen

-- 
Steffen Pingel - steffenp@xxxxxx - http://steffenpingel.de