Class PluginsApi

java.lang.Object
com.erudika.para.server.rest.PluginsApi
@RestController @RequestMapping(value="/v1/_plugins", produces="application/json") public final class PluginsApi extends Object
REST endpoints for inspecting and installing Para plugins.

Plugins are thin JARs published to Maven Central, each carrying a manifest of its runtime dependencies. This controller lets an admin UI list what is available, preview what an install would fetch, install it, and remove it.

A restart is required after installing or removing a plugin, because the plugin classloader is built once during startup and cached. Selecting a different plugin via configuration also requires a restart, matching the requires restart tag on those config properties.

Author:
Alex Bogdanovski [[email protected]]

  • Constructor Summary

    Constructors
    Constructor
    Description
    PluginsApi()
    No-args constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    org.springframework.http.ResponseEntity<?>
    install(String artifactId, Map<String,Object> request)
    Downloads a plugin and all of its dependencies into the plugin folder.
    org.springframework.http.ResponseEntity<Map<String,Object>>
    installed()
    Lists every JAR in the plugin folder, including plugins outside the official catalogue such as third-party or locally built ones.
    org.springframework.http.ResponseEntity<Map<String,Object>>
    list()
    Lists the official plugins with their type, whether each is installed, and whether it is the one currently selected by configuration.
    org.springframework.http.ResponseEntity<?>
    preview(String artifactId)
    Reports what installing a plugin would download, without touching the plugin folder.
    org.springframework.http.ResponseEntity<?>
    uninstall(String artifactId, String version)
    Removes a plugin JAR from the plugin folder.

    Methods inherited from class Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • PluginsApi

      public PluginsApi()
      No-args constructor.

  • Method Details

    • list

      @GetMapping public org.springframework.http.ResponseEntity<Map<String,Object>> list()
      Lists the official plugins with their type, whether each is installed, and whether it is the one currently selected by configuration.
      Returns:
      a map keyed by Maven artifactId

    • installed

      @GetMapping("/installed") public org.springframework.http.ResponseEntity<Map<String,Object>> installed()
      Lists every JAR in the plugin folder, including plugins outside the official catalogue such as third-party or locally built ones.
      Returns:
      a sorted list of file names

    • preview

      @GetMapping("/{artifactId}/preview") public org.springframework.http.ResponseEntity<?> preview(@PathVariable String artifactId)
      Reports what installing a plugin would download, without touching the plugin folder.

      Resolution happens in a temporary directory that is deleted afterwards, so an admin UI can show real numbers behind a confirmation prompt.

      Parameters:
      artifactId - the Maven artifactId of the plugin
      Returns:
      the plugin's declared dependencies and the total download size

    • install

      @PostMapping("/{artifactId}/install") public org.springframework.http.ResponseEntity<?> install(@PathVariable String artifactId, @RequestBody(required=false) Map<String,Object> request)
      Downloads a plugin and all of its dependencies into the plugin folder.

      Every artifact is checksum-verified before it is written. Para must be restarted before the plugin can be loaded.

      Parameters:
      artifactId - the Maven artifactId of the plugin
      request - optional JSON body with a version field
      Returns:
      a summary of the installation

    • uninstall

      @DeleteMapping("/{artifactId}/{version}") public org.springframework.http.ResponseEntity<?> uninstall(@PathVariable String artifactId, @PathVariable String version)
      Removes a plugin JAR from the plugin folder.

      Only the plugin JAR is deleted. Its dependencies stay, because plugins routinely share them and a dependency JAR carries no record of which plugin wanted it.

      Parameters:
      artifactId - the Maven artifactId of the plugin
      version - the installed version
      Returns:
      an empty body on success