RE: [mylyn-integrators] AbstractTask vs. RepositoryTaskData in aconnecto

["Tom Bryan (tombry)" <tombry@xxxxxxxxx>]

Steffen Pingel wrote on Tuesday, May 13, 2008 3:48 AM:

> > 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 explicitly set meta-data
> and values (Mylyn 3.0 will require this), e.g.:

Thanks for the tip.  I'd like to make migration to Mylyn 3.0 as painless
as possible.

> RepositoryTaskData [TaskData] is a hierarchical 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.

Got it.  It would be great if the Mylyn Integrator Guide could give
examples of the type of information that you intended to store in
various parts of the design.  

I'm not sure why I'd need options on attributes.  

The only "metadata" that I can think of is constant for a given
attribute (data type, max. length, range of possible values, required
format, etc.).  Is that the kind of information that you're expecting to
be used for meta-data?

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

OK.  Thanks.  I'm not using an AttributeMapper, yet, but it's good to
know where it fits in the design.

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

OK.  So, if I need to return some representation of all of the data from
a SOAP client, for example, I shouldn't try to stuff it all into my
AbstractTask subclass?  That is, I might have separate classes for my
task for the following cases:

ClientTask - a representation of the task used by my web service client
that is tied to a specific web service

TransferTask - a representation of all of the task attributes that I can
use to move that data between a web service client class and other task
classes (TransferTask would be client neutral in the case that my
connector has multiple different clients so that ITrackerClient can
declare a consistent API.)

MyAbstractTaskSubclass - a representation of just the task attributes
needed for the Task List UI

RepositoryTaskData - a representation of all of the task information as
a mapping of attributes, used for offline editing and persistence


I was trying to get rid of TransferTask, but that actually looks
difficult to do.  The web service client needs to return *something*,
but ClientTask may be too tied to the web service itself, the
AbstractTask subclass won't necessarily carry all of the data, and I
don't see anyone returning RepositoryTaskData instances directly from
their web service client code.  Perhaps the cleanest thing is to create
that TransferTask class.

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

Hm...I feel like I'm missing something here.

> Management of task data and the task list externalization is handled
> separately from these methods and should be robust. Please file a bug
> if you run into scenarios where updates to a task object is causing
> horrible exceptions. 

I'll file a bug even if I encounter a pleasant exception.  ;-)

I still feel like I don't quite understand some piece of what Mylyn is
doing as it pushes task data around (among repository, Task List, its
own offline cache, and the rich editor).  When I figure out what that
piece is/was, I'll let you know and maybe add it to the wiki.

-- 
Tom Bryan <tombry@xxxxxxxxx>
Cisco Systems