entity/.../activities endpoint minor API change for background tasks

[Alex Heneveld <al...@cloudsoftcorp.com>]

Hi All-

In [1], @tbouron and I add an "includeBackground" query parameter to the 
`/activities/xxxx/children` endpoint.  This is useful as you can see 
which tasks were "submitted by" the given task, even if they aren't 
explicit sub-tasks.  Typically these are less interesting eg message 
delivery, resolving config, etc -- but sometimes they are useful to 
see.  IE "opt-in" semantics feels right, which is what we have added.  
(Previously this API endpoint didn't even offer it as an option.  NB it 
still restricts to those running on the current entity, for efficiency 
reasons, so if you want to see tasks crossing entity boundaries in the 
UI they *must* be done as subtasks, ie to a DynamicSequentialTask rather 
than a BasicTask.)

It is inconsistent however with `/entities/xxxx/activities`  which 
includes *all* tasks running at an entity.  Most of the time, at least 
in the UI, we are interested in the _top level_ tasks, IE those which 
either are not submitted by a task (eg effector), or those which are 
submitted by a task in a different entity (cross-entity tasks).  
Currently however we get all the tasks submitted by any such tasks, 
recursively, subtasks and background tasks, etc, as long as they are 
running on the entity.  (Filtering this is how we populate background 
tasks above!)

I think we should change this, either:

(1) change `/entities/xxxx/activities` to return top-level tasks only, 
unless `?includeBackground=true` is specified in which case it will 
return all tasks on the entity (eg previous behaviour)

(2) leave `/entities/xxxx/activities` as is, but allow 
`?topLevelOnly=true` to filter out those submitted by tasks on the 
current entity

I think (1) is more intuitive (extra parameter to get extra less 
commonly wanted info) and in line with the `/entities/xxx/activities` 
endpoint.  However it changes the REST API.  I think it is acceptable as 
most places right now the behaviour of (1) causes "bugs" in a UI -- eg 
seeing lots of blank tasks since bg tasks often don't have a name.  But 
if we want to be strict then (2) is the way to go.

Thoughts?

Best
Alex




[1] https://github.com/apache/brooklyn-server/pull/559