/**
* The contents of this file are subject to the license and copyright
* detailed in the LICENSE file at the root of the source
* tree and available online at
*
* https://github.com/keeps/roda
*/
package org.roda.core.plugins;
import java.util.List;
import java.util.Map;
import org.roda.core.data.common.RodaConstants.PreservationAgentType;
import org.roda.core.data.common.RodaConstants.PreservationEventType;
import org.roda.core.data.exceptions.InvalidParameterException;
import org.roda.core.data.v2.IsRODAObject;
import org.roda.core.data.v2.LiteOptionalWithCause;
import org.roda.core.data.v2.jobs.PluginParameter;
import org.roda.core.data.v2.jobs.PluginType;
import org.roda.core.data.v2.jobs.Report;
import org.roda.core.index.IndexService;
import org.roda.core.model.ModelService;
import org.roda.core.plugins.orchestrate.JobPluginInfo;
import org.roda.core.storage.StorageService;
/**
* This interface should be implemented by any class that want to be a RODA
* plugin.
*
* @author Luis Faria<lfaria@keep.p>
* @author Hélder Silva <hsilva@keep.pt>
*/
public interface Plugin<T extends IsRODAObject> {
/**
* Returns the name of this {@link Plugin}.
*
* @return a {@link String} with the name of this {@link Plugin}.
*/
public String getName();
/**
* Returns the version of this {@link Plugin}.
*
* @return a <code>String</code> with the version number for this
* {@link Plugin}.
*/
public String getVersion();
/**
* Returns description of this {@link Plugin}.
*
* @return a {@link String} with the description of this {@link Plugin}.
*/
public String getDescription();
/**
* Returns the type of the agent linked to this {@link Plugin}.
*
* @return a {@link PreservationAgentType} with the type of the agent of this
* {@link Plugin}.
*/
public PreservationAgentType getAgentType();
/**
* Returns the type of the execution preservation event linked to this
* {@link Plugin}.
*
* @return a {@link PreservationEventType} with the type of the execution
* event of this {@link Plugin}.
*/
public PreservationEventType getPreservationEventType();
/**
* Returns the description of the execution preservation event linked to this
* {@link Plugin}.
*
* @return a {@link String} with the description of the execution event of
* this {@link Plugin}.
*/
public String getPreservationEventDescription();
/**
* Returns the success message of the execution preservation event linked to
* this {@link Plugin}.
*
* @return a {@link String} with the success message of the execution event of
* this {@link Plugin}.
*/
public String getPreservationEventSuccessMessage();
/**
* Returns the failure message of the execution preservation event linked to
* this {@link Plugin}.
*
* @return a {@link String} with the failure message of the execution event of
* this {@link Plugin}.
*/
public String getPreservationEventFailureMessage();
/**
* Returns the {@link List} of {@link PluginParameter}s necessary to run this
* {@link Plugin}.
*
* @return a {@link List} of {@link PluginParameter} with the parameters.
*/
public List<PluginParameter> getParameters();
/**
* Gets the parameter values inside a {@link Map} with attribute names and
* values.
*
* @return a {@link Map} with the parameters name and value.
*/
public Map<String, String> getParameterValues();
/**
* Sets the parameters returned by a previous call to
* {@link Plugin#getParameters()}.
*
* @param parameters
* a {@link List} of parameters.
*
* @throws InvalidParameterException
*/
public void setParameterValues(Map<String, String> parameters) throws InvalidParameterException;
/**
* Method to return Plugin type (so it can be grouped for different purposes)
*/
public PluginType getType();
/**
* Method to return Plugin categories
*/
public List<String> getCategories();
/**
* Method used by PluginManager to obtain a new instance of a plugin, from the
* current loaded Plugin, to provide to PluginOrchestrator
*/
public Plugin<T> cloneMe();
/**
* Method that validates the parameters provided to the Plugin
*
* FIXME this should be changed to return a report
*/
public boolean areParameterValuesValid();
/*
* "Working methods"
* ___________________________________________________________________________________________________________
*/
/**
* Initializes this {@link Plugin}. This method is called by the
* {@link PluginManager} before any other methods in the plugin.
*
* @throws PluginException
*/
public void init() throws PluginException;
public List<Class<T>> getObjectClasses();
/**
* Method to be invoked by the PluginOrchestrator to inject the job plugin
* info to be used by the plugin
*/
public void injectJobPluginInfo(JobPluginInfo jobPluginInfo);
/**
* Method retrieve job plugin info of a certain class
*/
public <T1 extends JobPluginInfo> T1 getJobPluginInfo(Class<T1> jobPluginInfoClass);
/**
* Method executed by {@link PluginOrchestrator} before splitting the workload
* (if it makes sense) by N workers
*
* @throws PluginException
*/
public Report beforeAllExecute(IndexService index, ModelService model, StorageService storage) throws PluginException;
/**
* Executes the {@link Plugin}.
*
* @return a {@link Report} of the actions performed.
*
* @throws PluginException
*/
public Report execute(IndexService index, ModelService model, StorageService storage,
List<LiteOptionalWithCause> list) throws PluginException;
/**
* Method executed by {@link PluginOrchestrator} after all workers have
* finished their work
*
* @throws PluginException
*/
public Report afterAllExecute(IndexService index, ModelService model, StorageService storage) throws PluginException;
/**
* Stops all {@link Plugin} activity. This is the last method to be called by
* {@link PluginManager} on the {@link Plugin}.
*/
public void shutdown();
}