View Javadoc
1   package com.atlassian.plugin.factories;
2   
3   import com.atlassian.plugin.ModuleDescriptor;
4   import com.atlassian.plugin.ModuleDescriptorFactory;
5   import com.atlassian.plugin.Plugin;
6   import com.atlassian.plugin.PluginArtifact;
7   import com.atlassian.plugin.PluginParseException;
8   import org.dom4j.Element;
9   
10  /**
11   * Creates the plugin artifact and deploys it into the appropriate plugin management system
12   *
13   * @since 2.0.0
14   */
15  public interface PluginFactory {
16      /**
17       * Determines if this factory can handle this artifact.
18       *
19       * @param pluginArtifact The artifact to test
20       * @return The plugin key, null if it cannot load the plugin
21       * @throws com.atlassian.plugin.PluginParseException If there are exceptions parsing the plugin configuration when
22       *                                                   the deployer should have been able to deploy the plugin
23       */
24      String canCreate(PluginArtifact pluginArtifact) throws PluginParseException;
25  
26      /**
27       * Deploys the plugin artifact by instantiating the plugin and configuring it. Should only be called if the respective
28       * {@link #canCreate(PluginArtifact)} call returned the plugin key
29       *
30       * @param pluginArtifact          the plugin artifact to deploy
31       * @param moduleDescriptorFactory the factory for the module descriptors
32       * @return the plugin loaded from the plugin artifact, or an UnloadablePlugin instance if loading fails.
33       * @throws com.atlassian.plugin.PluginParseException if the plugin could not be parsed
34       * @since 2.2.0
35       */
36      Plugin create(PluginArtifact pluginArtifact, ModuleDescriptorFactory moduleDescriptorFactory) throws PluginParseException;
37  
38      /**
39       * If this factory is capable of loading a plugin of the type passed, attempt to create a module descriptor. Add that
40       * module descriptor to the plugin.
41       * <p>
42       * If capable, always return a ModuleDescriptor, even if it indicates a failure case. Caller is responsible for
43       * handling exceptional {@link com.atlassian.plugin.ModuleDescriptor}.
44       * <p>
45       * Implementors should use <code>(plugin instanceof &lt;plugin-class&gt;)</code> to determine their capability;
46       * subclasses of implementors should override this if special handling is required.
47       *
48       * @param plugin                  that the module will be a member of
49       * @param module                  to create
50       * @param moduleDescriptorFactory basic factory, may be overridden
51       * @return null plugin was not created by this PluginFactory
52       * @since 4.0.0
53       */
54      ModuleDescriptor<?> createModule(Plugin plugin, Element module, ModuleDescriptorFactory moduleDescriptorFactory);
55  }