/*
 * RHQ Management Platform
 * Copyright (C) 2005-2010 Red Hat, Inc.
 * All rights reserved.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License, version 2, as
 * published by the Free Software Foundation, and/or the GNU Lesser
 * General Public License, version 2.1, also as published by the Free
 * Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License and the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * and the GNU Lesser General Public License along with this program;
 * if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */

package org.rhq.enterprise.server.resource.disambiguation;

import java.util.EnumSet;

/**
 * Defines a strategy for updating a results list with the disambiguation information.
 * <p>
 * See {@link DefaultDisambiguationUpdateStrategies} for a couple of implemented strategies.
 * 
 * @see DefaultDisambiguationUpdateStrategies
 * 
 * @author Lukas Krejci
 */
public interface DisambiguationUpdateStrategy {

    /**
     * Updates the report using the policy. It is guaranteed that the resource and its parents
     * in the report are already processed using the 
     * {@link ResourceResolution#update(MutableDisambiguationReport.Resource)}
     * method. This method is then called to ensure that the report as a whole conforms to the policy *and* this
     * strategy. This might entail removing some elements from the parent list for example.
     * 
     * @param <T>
     * @param policy
     * @param report
     */
    <T> void update(DisambiguationPolicy policy, MutableDisambiguationReport<T> report);

    /**
     * @return a set of resolutions for which the unique reports need to be repartitioned at the resource level.
     * In another words this forces the disambiguation to continue on up the disambiguation chain even if the 
     * it disambiguates the resuts successfully at the resource level.
     */
    EnumSet<ResourceResolution> resourceLevelRepartitionableResolutions();

    /**
     * @return a set of resolutions for which uniquely disambiguated reports are to be repartitioned further.
     * The resolutions from this set apply on the parents (on any level), unlike the resolutions from {@link #resourceLevelRepartitionableResolutions()}.
     */
    EnumSet<ResourceResolution> alwaysRepartitionableResolutions();

}
