Package de.espirit.firstspirit.agency

Interface ModuleAdminAgent

public interface ModuleAdminAgent
Agent providing administrative methods for maintaining FirstSpirit modules and components.
Example:
SpecialistsBroker.requireSpecialist(ModuleAdminAgent.TYPE)
Since:
5.1.103
See Also:

  • Field Details

  • Method Details

    • install

      @Deprecated @NotNull @NotNull ModuleAdminAgent.ModuleResult install(@NotNull @NotNull InputStream fsmStream, boolean updateUsages) throws IOException, ModuleException
      Deprecated.
      since 5.2.241104, use install(InputStream, UpdateUsagesMode) instead
      Installs or updates the given module. If updateUsages is true all project-app and web-app components will be updated and the appropriate web-apps will be deployed.
      Important:
      • If the given fsm couldn't be loaded or activated (e.g. due to an invalid module file), the old version won't be restored!
      • The given fsmStream will be closed, automatically. The caller is not responsible for closing the stream.
      Parameters:
      fsmStream - fsm file stream.
      updateUsages - true to update all project- and web-components (related web-apps will be deployed).
      Returns:
      the module-descriptor of the new or updated module.
      Throws:
      IOException - if any io operation fails.
      ModuleException - if the fsm isn't valid or in case of a circular dependency (e.g. module A needs B, B needs C, C needs A).
      SecurityException - if the current user is not a server admin.
      Since:
      5.1.103
      See Also:

    • install

      @Deprecated @NotNull @NotNull ModuleAdminAgent.ModuleResult install(@NotNull @NotNull InputStream fsmStream, boolean updateUsages, boolean deployWebApps) throws IOException, ModuleException
      Deprecated.
      since 5.2.241104, use install(InputStream, UpdateUsagesMode) instead
      Installs or updates the given module. If updateUsages is true all project-app and web-app components will be updated. If deployWebApps is true all related web-apps be deployed.
      Important:
      • If the given fsm couldn't be loaded or activated (e.g. due to an invalid module file), the old version won't be restored!
      • The given fsmStream will be closed automatically. The caller is not responsible for closing the stream.
      Parameters:
      fsmStream - fsm file stream.
      updateUsages - true to update all project- and web-components
      deployWebApps - true to directly deploy the related web-apps after the install process has finished.
      Returns:
      the module-descriptor of the new or updated module.
      Throws:
      IllegalArgumentException - if deployWebApps=true but updateUsages=false
      IOException - if any io operation fails.
      ModuleException - if the fsm isn't valid or in case of a circular dependency (e.g. module A needs B, B needs C, C needs A).
      SecurityException - if the current user is not a server admin.
      Since:
      5.2.190707
      See Also:

    • install

      @NotNull @NotNull ModuleAdminAgent.ModuleResult install(@NotNull @NotNull InputStream fsmStream, @NotNull @NotNull ModuleAdminAgent.UpdateUsagesMode updateUsagesMode) throws IOException, ModuleException
      Installs or updates the given module.
      Important:
      • If the given fsm couldn't be loaded or activated (e.g. due to an invalid module file), the old version won't be restored!
      • The given fsmStream will be closed automatically. The caller is not responsible for closing the stream.
      Parameters:
      fsmStream - fsm file stream.
      updateUsagesMode - the actions to perform after installing the module.
      Returns:
      the module-descriptor of the new or updated module.
      Throws:
      IOException - if any io operation fails.
      ModuleException - if the fsm isn't valid or in case of a circular dependency (e.g. module A needs B, B needs C, C needs A).
      SecurityException - if the current user is not a server admin.
      Since:
      5.2.241104
      See Also:

    • isActive

      boolean isActive(String moduleName) throws IllegalArgumentException
      Check if the module with the specified name is currently active. A module can only be inactive if it has unresolved dependencies to other modules. This happens if at least one dependent module is not installed.
      Parameters:
      moduleName - name of the module.
      Returns:
      true if the module is active.
      Throws:
      IllegalArgumentException - if the module is not found.
      Since:
      5.2.202

    • isTrusted

      @Deprecated(forRemoval=true) default boolean isTrusted(String moduleName)
      Deprecated, for removal: This API element is subject to removal in a future version.
      since 5.2.240203 - no replacement
      Returns the trusted flag of the given module.
      Parameters:
      moduleName - name of the module
      Returns:
      current trusted flag.
      Since:
      5.2.13

    • setTrusted

      @Deprecated(forRemoval=true) default boolean setTrusted(String moduleName, boolean trusted)
      Deprecated, for removal: This API element is subject to removal in a future version.
      since 5.2.240203 - no replacement
      Sets whether to trust the codebase of the specified module.
      Parameters:
      moduleName - name of the module
      trusted - new value
      Returns:
      old trusted state
      Throws:
      SecurityException - if the current user is not a server admin.
      Since:
      5.2.13

    • uninstall

      @Deprecated void uninstall(String moduleName, boolean removeUsages) throws ModuleException
      Deprecated.
      since 5.2.241104, use uninstall(String, UpdateUsagesMode) instead
      Uninstalls the given module. If removeUsages is true, all project-app and web-app components will be removed. If removeUsages is false and there still exist any usages, a ModuleException will be thrown.
      Parameters:
      moduleName - name of the module which should be uninstalled.
      removeUsages - true to remove all usages.
      Throws:
      ModuleException - if unloading of the given module fails.
      SecurityException - if the current user is not a server admin.
      Since:
      5.1.103
      See Also:

    • uninstall

      void uninstall(@NotNull @NotNull String moduleName, @NotNull @NotNull ModuleAdminAgent.UpdateUsagesMode updateUsagesMode) throws ModuleException
      Uninstalls the module with the given name after performing the specified actions. If updateUsagesMode is DO_NOTHING and there still exist any usages, a ModuleException will be thrown.
      Parameters:
      moduleName - name of the module which should be uninstalled.
      updateUsagesMode - the actions to perform when uninstalling the module.
      Throws:
      ModuleException - if unloading of the given module fails.
      SecurityException - if the current user is not a server admin.
      Since:
      5.2.241104
      See Also:

    • installProjectApp

      void installProjectApp(String moduleName, String projectAppName, @NotNull @NotNull Project project) throws ModuleException
      Installs or updates a project application to the specified project.
      Parameters:
      moduleName - name of the module containing the project application.
      projectAppName - name of the project-app component.
      project - where to install the component.
      Throws:
      ModuleException - if installing the component fails.
      SecurityException - if the current user is not a project administrator.
      Since:
      5.1.103
      See Also:

    • getProjectAppConfig

      @NotNull @NotNull FileSystem<?> getProjectAppConfig(String moduleName, String projectAppName, @NotNull @NotNull Project project) throws SecurityException
      Returns an access to the project-app configuration directory; read-write-access if the user is project admin, read-only-access if the user is project user, otherwise a SecurityException will be thrown.
      Parameters:
      moduleName - name of the module containing the project application.
      projectAppName - name of the project-app component.
      project - project where the app is installed.
      Returns:
      access to the project-app configuration directory.
      Throws:
      SecurityException - if the current user has no project access.
      IllegalArgumentException - if there is no project app installed in the given project matching the given names
      Since:
      5.1.103

    • getServiceConfig

      @NotNull @NotNull FileSystem<?> getServiceConfig(@NotNull @NotNull String serviceName)
      Provides access to the configuration of a service. Access is granted if the user is a server admin, otherwise a SecurityException is thrown.
      Parameters:
      serviceName - name of the service to retrieve the configuration for, must not be null.
      Returns:
      access to the configuration directory of the service.
      Throws:
      SecurityException - if the current user is not a server admin.
      ServiceNotFoundException - if the service could not be found.
      Since:
      5.2.1202

    • getProjectAppUsages

      @NotNull @NotNull Collection<Project> getProjectAppUsages(String moduleName, String projectAppName)
      Returns ids of all projects using the specified project application. The list is limited to projects for which the current user has access permissions.
      Parameters:
      moduleName - name of the module containing the project application.
      projectAppName - name of project-app component.
      Returns:
      list of project ids using the specified project application.
      Since:
      5.1.103

    • uninstallProjectApp

      void uninstallProjectApp(String moduleName, String projectAppName, @NotNull @NotNull Project project) throws ModuleException
      Removes the project application from the specified project.
      Parameters:
      moduleName - name of the module containing the project application.
      projectAppName - name of the project-app component.
      project - target project.
      Throws:
      ModuleException - if uninstalling the project-app fails.
      SecurityException - if the current user is not a project administrator.
      Since:
      5.1.103
      See Also:

    • registerWebServer

      void registerWebServer(@NotNull @NotNull String moduleName, @NotNull @NotNull String componentName, @NotNull @NotNull String instanceName)
      Registers a new web server with the specified instance name. Afterwards, web applications may be deployed to the web server.
      Parameters:
      moduleName - name of module containing the web server component, must not be null.
      componentName - name of web server component, must not be null.
      instanceName - name of the web server instance to be created, must not be null.
      Throws:
      ModuleException - if the module could not be found.
      IllegalStateException - if the module component could not be found.
      ModuleException - if the web server could not be found.
      UncheckedIOException - if an error occurred while copying required files.
      SecurityException - if the current user is not a server admin.
      Since:
      5.2.180901

    • unregisterWebServer

      void unregisterWebServer(@NotNull @NotNull String moduleName, @NotNull @NotNull String componentName, @NotNull @NotNull String instanceName)
      Removes the specified web server and deletes its directories from the configuration directory.
      Parameters:
      moduleName - name of module containing the web server component, must not be null.
      componentName - name of web server component, must not be null.
      instanceName - name of the web server instance to remove, must not be null.
      Throws:
      IllegalStateException - if the web server is still marked as active for at least one web application.
      ModuleException - if the web server or file system could not be found.
      SecurityException - if the current user is not a server admin.
      Since:
      5.2.180901

    • getWebServerConfiguration

      FileSystem<?> getWebServerConfiguration(@NotNull @NotNull String moduleName, @NotNull @NotNull String componentName, @NotNull @NotNull String instanceName)
      Returns the configuration file system specified by the given web server.

      Attention: Please remember to close the FileSystem after usage.

      Parameters:
      moduleName - name of module containing the web server component, must not be null.
      componentName - name of web server component, must not be null.
      instanceName - name of the web server instance, must not be null.
      Returns:
      a file system specified by the given web server or an empty Optional if it's not defined.
      Throws:
      SecurityException - if the current user is not a server admin.
      Since:
      5.2.180901

    • installWebApp

      void installWebApp(String moduleName, String webAppComponent, @NotNull @NotNull WebAppId webAppId) throws ModuleException
      Installs or updates the given web-app component into the specified web app and deploys the web app to its web-server.
      Parameters:
      moduleName - name of the module containing the web-app component.
      webAppComponent - web-app component name.
      webAppId - target web-app.
      Throws:
      ModuleException - if the installation or update failed.
      SecurityException - if the web-app is global and the current user is not a server admin or if it is a project-local web-app and the current user is not a project admin.
      Since:
      5.1.103
      See Also:

    • installWebApp

      void installWebApp(String moduleName, String webAppComponent, @NotNull @NotNull WebAppId webAppId, boolean deploy) throws ModuleException
      Installs or updates the given web-app component into the specified web app and deploys the web app to its web-server, if deploy is set to true.
      Parameters:
      moduleName - name of the module containing the web-app component.
      webAppComponent - web-app component name.
      webAppId - target web-app.
      deploy - whether the related web app should be deployed to its web-server or not
      Throws:
      ModuleException - if the installation or update failed.
      SecurityException - if the web-app is global and the current user is not a server admin or if it is a project-local web-app and the current user is not a project admin.
      Since:
      5.2.190707
      See Also:

    • downloadWebApp

      @NotNull @NotNull InputStream downloadWebApp(WebAppId webAppId) throws IOException
      Download the specified web app as .war-file.
      Parameters:
      webAppId - identifies the web-app to download.
      Returns:
      .war-file
      Throws:
      IOException - if any io related operation fails.
      SecurityException - if the web-app is global and the current user is not a server admin or if it is a project-local web-app and the current user is not a project admin.
      Since:
      5.1.103

    • deployWebApp

      boolean deployWebApp(@NotNull @NotNull WebAppId webAppId)
      Deploys the given web app to its web-server.
      Parameters:
      webAppId - identifies web-app to deploy.
      Returns:
      true if the web-app could be deployed.
      Throws:
      SecurityException - if the web-app is global and the current user is not a server admin or if it is a project-local web-app and the current user is not a project admin.
      Since:
      5.2.13

    • deployWebApps

      boolean deployWebApps(@NotNull @NotNull Iterable<WebAppId> webAppIds)
      Deploys the given web apps to their corresponding web-servers.
      Parameters:
      webAppIds - web-apps to deploy.
      Returns:
      true if all web-apps could be deployed.
      Throws:
      SecurityException - if one (or more) web-app is global and the current user is not a server admin or if one (or more) web-app is project-local and the current user is not a project admin.
      Since:
      5.2.190707

    • getWebAppConfig

      @NotNull @NotNull FileSystem<?> getWebAppConfig(String moduleName, String webAppComponent, WebAppId webAppId)
      Returns the configuration directory of the specified web-app.
      Parameters:
      webAppId - identifies the web-app.
      Returns:
      access to the web-app configuration directory.
      Throws:
      SecurityException - if the web-app is global and the current user is not a server admin or if it is a project-local web-app and the current user is not a project admin.
      Since:
      5.2.13

    • undeployWebApp

      boolean undeployWebApp(WebAppId webAppId)
      Undeploys the given web app from its web-server.
      Parameters:
      webAppId - identifies web-app to undeploy.
      Returns:
      true if the web-app could be undeployed.
      Throws:
      SecurityException - if the web-app is global and the current user is not a server admin or if it is a project-local web-app and the current user is not a project admin.
      Since:
      5.2.13

    • getWebAppUsages

      @NotNull @NotNull Collection<WebAppId> getWebAppUsages(String moduleName, String webAppComponent)
      Returns all usages of the given web-app component.
      Parameters:
      moduleName - name of the module containing the web-app component.
      webAppComponent - web-app component name.
      Returns:
      collection of web-app identifier.
      Throws:
      SecurityException - if a used web-app is project-local and the user does has no access to that project.
      Since:
      5.1.103

    • uninstallWebApp

      void uninstallWebApp(String moduleName, String webAppComponent, WebAppId webAppId) throws ModuleException
      Removes the given web-app component from the specified web app and deploys the web to its web-server.
      Parameters:
      moduleName - name of the module containing the web-app component.
      webAppComponent - web-app component name.
      webAppId - target web-app.
      Throws:
      SecurityException - if the web-app is global and the current user is not a server admin or if it is a project-local web-app and the current user is not a project admin.
      ModuleException
      Since:
      5.1.103
      See Also:

    • createGlobalWebApp

      GlobalWebAppId createGlobalWebApp(String globalWebAppId, String contextName, String name)
      Creates a global web-app.
      Important: to successfully deploy this new web-app, a web-server instance must be set, using ServerConfiguration.
      Parameters:
      globalWebAppId - new global web-app identifier.
      contextName - web-server context where to install the web-app.
      name - name of this global web-app, visible in the FirstSpirit ServerManager.
      Returns:
      web-app identifier.
      Throws:
      SecurityException - if the current user is not a server admin
      Since:
      5.1.103
      See Also:

    • getGlobalWebApps

      @NotNull @NotNull Collection<GlobalWebAppId> getGlobalWebApps()
      Returns all configurable global web-apps.
      Returns:
      all configurable global web-apps.
      Since:
      5.1.103

    • getGlobalWebApps

      @NotNull @NotNull Collection<GlobalWebAppId> getGlobalWebApps(boolean includeSystem)
      Returns all configurable global web-apps with the option to include the ones from the system.
      Parameters:
      includeSystem - If true the system apps are included.
      Returns:
      The collection of configurable WebApps.
      Since:
      5.2.2001

    • removeGlobalWebApp

      void removeGlobalWebApp(GlobalWebAppId globalWebAppId)
      Undeploys and destroys the given global web-app.
      Parameters:
      globalWebAppId - global web-app identifier.
      Throws:
      SecurityException - if the current user is not a server admin
      Since:
      5.1.103
      See Also:

    • getInstalledVersion

      @NotNull @NotNull String getInstalledVersion(String moduleName) throws IllegalArgumentException
      Returns the version of the given module.
      Parameters:
      moduleName - name of module to look for.
      Returns:
      module version.
      Throws:
      IllegalArgumentException - if the module couldn't be found
      Since:
      5.1.103

    • getModules

      @NotNull @NotNull Collection<ModuleDescriptor> getModules()
      Return descriptors of all installed modules.
      Returns:
      Descriptors of all installed modules.
      Since:
      5.1.103

    • startService

      void startService(String serviceName) throws ServiceNotFoundException
      Starts the service with the given serviceName.
      Parameters:
      serviceName - service name
      Throws:
      ServiceNotFoundException - if the specified service couldn't be found.
      SecurityException - if the current user is not a server admin
      Since:
      5.1.103

    • isAutostart

      boolean isAutostart(String serviceName)
      Returns true if the given service is automatically started after FirstSpirit server start.
      Parameters:
      serviceName - service to check.
      Returns:
      true if autostart is enabled
      Since:
      5.2.13

    • isRunning

      boolean isRunning(String serviceName)
      Returns true if the given service is currently running.
      Parameters:
      serviceName - service to check.
      Returns:
      true if the service is running.
      Since:
      5.2.13

    • setAutostart

      boolean setAutostart(String serviceName, boolean autostart)
      Sets whether the given service should start automatically after FirstSpirit server start.
      Parameters:
      serviceName - service to set.
      autostart - flag.
      Returns:
      old autostart value.
      Throws:
      SecurityException - if the current user is not a server admin
      Since:
      5.2.13

    • stopService

      void stopService(String serviceName) throws ServiceNotFoundException
      Stops the service with the given serviceName.
      Parameters:
      serviceName - service name
      Throws:
      ServiceNotFoundException - if the specified service couldn't be found.
      SecurityException - if the current user is not a server admin
      Since:
      5.1.103