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
      Checks 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. If the given module is not installed on the server, returns an empty list.
      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. If the given module is not installed on the server, returns an empty list.
      Parameters:
      moduleName - name of the module containing the web-app component.
      webAppComponent - web-app component name.
      Returns:
      collection of web-app identifiers.
      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