The Java Broker requires a mechanism that allows a preference, which is owned by a Principle,  to be associated with an arbitrary object with the object hierarchy.  An example of a preference could be:

• a query
• a preferred timezone
• a dashboard layout

Preferences will be owned by a Principle.  Preference will have a visibility which will allow the preference to be private, or shared amongst a group.  Preferences will be editable only by the Principle that created it.  The UI will allow an operator to clone a copy of a preference of another which is visible to him, in order that he may change his own copy.

Preferences will be durable and thus survive a Broker restart.

Preferences associated with a VirtualHost or below need to automatically propagate amongst the nodes within a HA group.  As an operator, this means I will be able to create a query against my HA virtualhost and the same query will be available to me no matter where the mastership resides.

Unlike relationships between CO, preferences are loosely associated with model objects.  This means that an operator will be able to remove a queue even if a preference is still associated, belonging to either himself or another Principle. In this case, the preference becomes orphaned and must be deleted as the configured object that referred to it is removed.

Structure of a preference

{
id: <UUID>,
type: <type of the preference - immutable>,
associatedId: <UUID of model object - immutable>,
owner: <Domain prefixed Principle - normally that belonging to a user - immutable>,
visibleTo: [<Domain prefixed Principle - normally that belonging to a group>],
<type specify attributes>
}

Preference Store

Have a PreferenceStore interface rather like DurableConfigurationStore

• open/close
• upgrade
• visit
• create
• update
• delete

API is in terms of PreferencesRecord (analogous to ConfiguredObjectRecords)

AbstractSystemConfig and AbstractVirtualHostNode have a separate preference store.

• The concrete instances of SystemConfig and VirtualHostNode responsible for creating the preference store too.
• For storage mechanism BDB, JDBC, Derby there would be a restriction that the preference store must be co-located with the configuration.
• For storage mechanism JSON the preferences would be stored in a separate file.

Probably need a PreferenceStoreProvider interface.

REST API

REST API would be part of the versioned API.

URLs would be of the form: /api/latest/preferences/

The caller won't know if the preference is stored in the broker or virtualhostnode preference store.

Create

 The following will create a QUERY preference belonging to the currently logged on user, attached to the given UUID.  Internally the Broker must find the associated UUID (which could be anywhere in the Configured Object tree) and then navigate back up the tree to find the first point that is capable of storing preferences.

POST /api/latest/preferences/
{
type: QUERY,
description: 'Acme Hot queues',
associatedId: 75d5d2a4-0573-11e6-b512-3e1d05defe78,
visibleTo: ldap.mycompany.org:operators,
select: 'id,name,queueDepthMessages'
where: 'queueDepthMessages > 1000'
}
 
HTTP/1.1 201 Created
Location: /api/latest/preferences/virtualhostnode?id=81dfeb5c-0573-11e6-b512-3e1d05defe78

Update

The following will update that QUERY preference with the given UUID.  In a similar way to Create, the Broker will need to traverse the tree to find the associated UUID in order to know if the preference is stored at the Broker or Virtualhost level.

PUT /api/latest/preferences/virtualhostnode/?id=81dfeb5c-0573-11e6-b512-3e1d05defe78
{
type: QUERY,
description: 'Acme Hot queues',
associatedId: 75d5d2a4-0573-11e6-b512-3e1d05defe78,
visibleTo: ldap.mycompany.org:operators,
select: 'id,name,queueDepthMessages,oldestMessageAge'
where: 'queueDepthMessages > 750'
}
 
HTTP/1.1 200 Ok

Delete

Similar to UPDATE

Get

Get will return either a single preferences object, or all the preferences belonging to or visible to the authenticated principle.   We might want to consider a type filter.

Open Questions

1. Should a super user be able to view/change the preferences of another user?
2. Should we be able to restrict some preferences to a single instance? For instance it will make sense to have only a single timezone preference associated with a single object for a single user?  Should the backend have a way to enforce that restriction? 
3. Should preferences have metadata?
4. How will metadata map to AMQP Management?