Design - Configuration synchronization - Alert Notifications

Rationale

Alert notifications are pluggable and their configuration may contain references to other entities within the system - resources, packages, users, roles, etc. Such references re not "standardized" in any manner and each plugin is free to use different "strategy" of putting such references in its configuration objects. This makes the export of alert notifications somewhat problematic because we need a way of matching the referenced entities in the source and target RHQ installations. This matching can't be automatic and a user intervention will be needed to provide it before an import can be performed. On the other we can't afford just discarding the notification types that use such references simply because of the fact that most of them do so and alert template/definition export/import would therefore become useless.

Because alert notifications are pluggable, the plugins will need to be involved in the export and import of the data and therefore the alert sender API will have to change in a backwards incompatible way.

AlertSender API changes

These are the proposed additions to the AlertSender base class:

/**
 * This method returns a set of different entities referenced in the configuration of this alert sender.
 */
public abstract Set<Object> getReferencedEntities();

/**
 * Only the plugin can "know" what kind of entities it can reference and is therefore able to read
 * them from the provided reader.
 * <p>
 * <b>WARNING:</b> this method must not reference any of the configuration instance fields as they will not
 * be initialized at the time this method is called.
 */
public abstract Set<Object> unmarshallReferencedEntities(Reader input);

/**
 * This writes out the set of referenced entities (the same set as would be returned by the {@link #getReferencedEntities()} method) 
 * to the provided writer.
 * <p>
 * <b>WARNING:</b> this method must not reference any of the configuration instance fields as they will not
 * be initialized at the time this method is called.
 */
public abstract void marshallReferencedEntities(Writer output);

/**
 * This will update all the configuration objects to reference the replaced entities instead of the original
 * ones.
 * <p>
 * This method is called during configuration import where the notification is first instantiated with the
 * configuration coming from the origin server (i.e. with most probably incorrect reference ids, etc.). Once
 * the notification is instantiated with this incorrect configuration and the user provides the mapping
 * that maps the original entities to the entities from the local RHQ installation, this method is called 
 * to update the incorrect configuration with the user provided corrections.
 * 
 * @param entityReplacements the keys of this map are objects from {@link #getReferencedEntities()}, the values
 * are replacements provided by the user. If the value is null, the user provided no alternative and the
 * original entity must therefore be removed from the resulting configuration.
 */
public abstract void updateConfigurationWithEntityReplacements(Map<Object, Object> entityReplacements);

Consequences in other parts of RHQ

Providing such facility has quite large consequences:

Import becomes a multi-phase process. Before an export file can be imported, the user must be provided with some means to:
- examine the export file to determine what to import and what to ignore.
- determine the list of referenced entities
- provide the mapping to the corresponding entities in the target installation
- execute the import with these modifications
This multiphase process has to be supported by some kind of API in the CLI
The GUI needs to support the above points