Line data    Source code

       1             : // Copyright (C) 2014 The Android Open Source Project
       2             : //
       3             : // Licensed under the Apache License, Version 2.0 (the "License");
       4             : // you may not use this file except in compliance with the License.
       5             : // You may obtain a copy of the License at
       6             : //
       7             : // http://www.apache.org/licenses/LICENSE-2.0
       8             : //
       9             : // Unless required by applicable law or agreed to in writing, software
      10             : // distributed under the License is distributed on an "AS IS" BASIS,
      11             : // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      12             : // See the License for the specific language governing permissions and
      13             : // limitations under the License.
      14             : 
      15             : package com.google.gerrit.server.plugins;
      16             : 
      17             : import com.google.gerrit.extensions.annotations.ExtensionPoint;
      18             : import com.google.gerrit.server.PluginUser;
      19             : import com.google.gerrit.server.config.GerritRuntime;
      20             : import java.nio.file.Path;
      21             : import org.eclipse.jgit.internal.storage.file.FileSnapshot;
      22             : 
      23             : /**
      24             :  * Provider of one Server plugin from one external file
      25             :  *
      26             :  * <p>Allows to load one plugin from one external file or one directory by declaring the ability to
      27             :  * handle it.
      28             :  *
      29             :  * <p>In order to load multiple files into a single plugin, group them into a directory tree and
      30             :  * then load the directory root as a single plugin.
      31             :  */
      32             : @ExtensionPoint
      33             : public interface ServerPluginProvider {
      34             : 
      35             :   /** Descriptor of the Plugin that ServerPluginProvider has to load. */
      36             :   class PluginDescription {
      37             :     public final PluginUser user;
      38             :     public final String canonicalUrl;
      39             :     public final Path dataDir;
      40             :     final GerritRuntime gerritRuntime;
      41             : 
      42             :     /**
      43             :      * Creates a new PluginDescription for ServerPluginProvider.
      44             :      *
      45             :      * @param user Gerrit user for interacting with plugins
      46             :      * @param canonicalUrl plugin root Web URL
      47             :      * @param dataDir directory for plugin data
      48             :      * @param gerritRuntime current Gerrit runtime (daemon, batch, ...)
      49             :      */
      50             :     public PluginDescription(
      51           1 :         PluginUser user, String canonicalUrl, Path dataDir, GerritRuntime gerritRuntime) {
      52           1 :       this.user = user;
      53           1 :       this.canonicalUrl = canonicalUrl;
      54           1 :       this.dataDir = dataDir;
      55           1 :       this.gerritRuntime = gerritRuntime;
      56           1 :     }
      57             :   }
      58             : 
      59             :   /**
      60             :    * Declares the availability to manage an external file or directory
      61             :    *
      62             :    * @param srcPath the external file or directory
      63             :    * @return true if file or directory can be loaded into a Server Plugin
      64             :    */
      65             :   boolean handles(Path srcPath);
      66             : 
      67             :   /**
      68             :    * Returns the plugin name of an external file or directory
      69             :    *
      70             :    * <p>Should be called only if {@link #handles(Path) handles(srcFile)} returns true and thus
      71             :    * srcFile is a supported plugin format. An IllegalArgumentException is thrown otherwise as
      72             :    * srcFile is not a valid file format for extracting its plugin name.
      73             :    *
      74             :    * @param srcPath external file or directory
      75             :    * @return plugin name
      76             :    */
      77             :   String getPluginName(Path srcPath);
      78             : 
      79             :   /**
      80             :    * Loads an external file or directory into a Server plugin.
      81             :    *
      82             :    * <p>Should be called only if {@link #handles(Path) handles(srcFile)} returns true and thus
      83             :    * srcFile is a supported plugin format. An IllegalArgumentException is thrown otherwise as
      84             :    * srcFile is not a valid file format for extracting its plugin name.
      85             :    *
      86             :    * @param srcPath external file or directory
      87             :    * @param snapshot snapshot of the external file
      88             :    * @param pluginDescriptor descriptor of the ServerPlugin to load
      89             :    * @throws InvalidPluginException if plugin is supposed to be handled but cannot be loaded for any
      90             :    *     other reason
      91             :    */
      92             :   ServerPlugin get(Path srcPath, FileSnapshot snapshot, PluginDescription pluginDescriptor)
      93             :       throws InvalidPluginException;
      94             : 
      95             :   /**
      96             :    * Returns the plugin name of this provider.
      97             :    *
      98             :    * <p>Allows to identify which plugin provided the current ServerPluginProvider by returning the
      99             :    * plugin name. Helpful for troubleshooting plugin loading problems.
     100             :    *
     101             :    * @return plugin name of this provider
     102             :    */
     103             :   String getProviderPluginName();
     104             : }