Package de.espirit.firstspirit.agency
Interface ModuleAdminAgent
public interface ModuleAdminAgent
Agent providing administrative methods for maintaining FirstSpirit modules and components.
Example:
Example:
SpecialistsBroker.requireSpecialist(ModuleAdminAgent.TYPE)
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic interface
The module installation/update result containing the installed/upgraded module descriptor and the process log message.static enum
Defines the actions to be performed when a module is updated or uninstalled. -
Field Summary
Modifier and TypeFieldDescriptionstatic final SpecialistType<ModuleAdminAgent>
Agent providing administrative methods for maintaining FirstSpirit server modules. -
Method Summary
Modifier and TypeMethodDescriptioncreateGlobalWebApp
(String globalWebAppId, String contextName, String name) Creates a global web-app.boolean
deployWebApp
(@NotNull WebAppId webAppId) Deploys the given web app to its web-server.boolean
deployWebApps
(@NotNull Iterable<WebAppId> webAppIds) Deploys the given web apps to their corresponding web-servers.@NotNull InputStream
downloadWebApp
(WebAppId webAppId) Download the specified web app as.war
-file.@NotNull Collection<GlobalWebAppId>
Returns all configurable global web-apps.@NotNull Collection<GlobalWebAppId>
getGlobalWebApps
(boolean includeSystem) Returns all configurable global web-apps with the option to include the ones from the system.@NotNull String
getInstalledVersion
(String moduleName) Returns the version of the given module.@NotNull Collection<ModuleDescriptor>
Return descriptors of all installed modules.@NotNull FileSystem<?>
getProjectAppConfig
(String moduleName, String projectAppName, @NotNull Project project) 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 aSecurityException
will be thrown.@NotNull Collection<Project>
getProjectAppUsages
(String moduleName, String projectAppName) Returns ids of all projects using the specified project application.@NotNull FileSystem<?>
getServiceConfig
(@NotNull String serviceName) Provides access to the configuration of a service.@NotNull FileSystem<?>
getWebAppConfig
(String moduleName, String webAppComponent, WebAppId webAppId) Returns the configuration directory of the specified web-app.@NotNull Collection<WebAppId>
getWebAppUsages
(String moduleName, String webAppComponent) Returns all usages of the given web-app component.FileSystem<?>
getWebServerConfiguration
(@NotNull String moduleName, @NotNull String componentName, @NotNull String instanceName) Returns the configuration file system specified by the given web server.@NotNull ModuleAdminAgent.ModuleResult
install
(@NotNull InputStream fsmStream, boolean updateUsages) Deprecated.@NotNull ModuleAdminAgent.ModuleResult
install
(@NotNull InputStream fsmStream, boolean updateUsages, boolean deployWebApps) Deprecated.since 5.2.241104, useinstall(InputStream,UpdateUsagesMode)
instead@NotNull ModuleAdminAgent.ModuleResult
install
(@NotNull InputStream fsmStream, @NotNull ModuleAdminAgent.UpdateUsagesMode updateUsagesMode) Installs or updates the given module.void
installProjectApp
(String moduleName, String projectAppName, @NotNull Project project) Installs or updates a project application to the specified project.void
installWebApp
(String moduleName, String webAppComponent, @NotNull WebAppId webAppId) Installs or updates the given web-app component into the specified web app and deploys the web app to its web-server.void
installWebApp
(String moduleName, String webAppComponent, @NotNull WebAppId webAppId, boolean deploy) Installs or updates the given web-app component into the specified web app and deploys the web app to its web-server, ifdeploy
is set totrue
.boolean
Check if the module with the specified name is currently active.boolean
isAutostart
(String serviceName) Returnstrue
if the given service is automatically started after FirstSpirit server start.boolean
Returnstrue
if the given service is currently running.default boolean
Deprecated, for removal: This API element is subject to removal in a future version.since 5.2.240203 - no replacementvoid
registerWebServer
(@NotNull String moduleName, @NotNull String componentName, @NotNull String instanceName) Registers a new web server with the specified instance name.void
removeGlobalWebApp
(GlobalWebAppId globalWebAppId) Undeploys and destroys the given global web-app.boolean
setAutostart
(String serviceName, boolean autostart) Sets whether the given service should start automatically after FirstSpirit server start.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 replacementvoid
startService
(String serviceName) Starts the service with the givenserviceName
.void
stopService
(String serviceName) Stops the service with the givenserviceName
.boolean
undeployWebApp
(WebAppId webAppId) Undeploys the given web app from its web-server.void
uninstall
(@NotNull String moduleName, @NotNull ModuleAdminAgent.UpdateUsagesMode updateUsagesMode) Uninstalls the module with the given name after performing the specified actions.void
Deprecated.since 5.2.241104, useuninstall(String,UpdateUsagesMode)
insteadvoid
uninstallProjectApp
(String moduleName, String projectAppName, @NotNull Project project) Removes the project application from the specified project.void
uninstallWebApp
(String moduleName, String webAppComponent, WebAppId webAppId) Removes the given web-app component from the specified web app and deploys the web to its web-server.void
unregisterWebServer
(@NotNull String moduleName, @NotNull String componentName, @NotNull String instanceName) Removes the specified web server and deletes its directories from the configuration directory.
-
Field Details
-
TYPE
Agent providing administrative methods for maintaining FirstSpirit server modules. The agent's technical type to be used to request the agent from aSpecialistsBroker
.
-
-
Method Details
-
install
@Deprecated @NotNull @NotNull ModuleAdminAgent.ModuleResult install(@NotNull @NotNull InputStream fsmStream, boolean updateUsages) throws IOException, ModuleException Deprecated.since 5.2.241104, useinstall(InputStream,UpdateUsagesMode)
insteadInstalls or updates the given module. IfupdateUsages
istrue
all project-appand 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 forclosing 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, useinstall(InputStream,UpdateUsagesMode)
insteadInstalls or updates the given module. IfupdateUsages
istrue
all project-appand web-app components will be updated. IfdeployWebApps
istrue
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 forclosing the stream.
- Parameters:
fsmStream
- fsm file stream.updateUsages
-true
to update all project- and web-componentsdeployWebApps
-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=falseIOException
- 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 forclosing 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
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, for removal: This API element is subject to removal in a future version.since 5.2.240203 - no replacementReturns the trusted flag of the given module.- Parameters:
moduleName
- name of the module- Returns:
- current trusted flag.
- Since:
- 5.2.13
-
setTrusted
Deprecated, for removal: This API element is subject to removal in a future version.since 5.2.240203 - no replacementSets whether to trust the codebase of the specified module.- Parameters:
moduleName
- name of the moduletrusted
- new value- Returns:
- old trusted state
- Throws:
SecurityException
- if the current user is not a server admin.- Since:
- 5.2.13
-
uninstall
Deprecated.since 5.2.241104, useuninstall(String,UpdateUsagesMode)
insteadUninstalls the given module. IfremoveUsages
istrue
, all project-app and web-app components will be removed. IfremoveUsages
isfalse
and there still exist any usages, aModuleException
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. IfupdateUsagesMode
isDO_NOTHING
and there still exist any usages, aModuleException
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 aSecurityException
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
Provides access to the configuration of a service. Access is granted if the user is a server admin, otherwise aSecurityException
is thrown.- Parameters:
serviceName
- name of the service to retrieve the configuration for, must not benull
.- 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
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 benull
.componentName
- name of web server component, must not benull
.instanceName
- name of the web server instance to be created, must not benull
.- 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 benull
.componentName
- name of web server component, must not benull
.instanceName
- name of the web server instance to remove, must not benull
.- 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 benull
.componentName
- name of web server component, must not benull
.instanceName
- name of the web server instance, must not benull
.- 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 orif 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, ifdeploy
is set totrue
.- 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 orif it is a project-local web-app and the current user is not a project admin.- Since:
- 5.2.190707
- See Also:
-
downloadWebApp
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 orif it is a project-local web-app and the current user is not a project admin.- Since:
- 5.1.103
-
deployWebApp
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 orif it is a project-local web-app and the current user is not a project admin.- Since:
- 5.2.13
-
deployWebApps
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 orif 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 orif it is a project-local web-app and the current user is not a project admin.- Since:
- 5.2.13
-
undeployWebApp
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 orif it is a project-local web-app and the current user is not a project admin.- Since:
- 5.2.13
-
getWebAppUsages
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 orif it is a project-local web-app and the current user is not a project admin.ModuleException
- Since:
- 5.1.103
- See Also:
-
createGlobalWebApp
Creates a global web-app.
Important: to successfullydeploy
this new web-app, a web-server instancemust be set, usingServerConfiguration
.- 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
Returns all configurable global web-apps.- Returns:
- all configurable global web-apps.
- Since:
- 5.1.103
-
getGlobalWebApps
Returns all configurable global web-apps with the option to include the ones from the system.- Parameters:
includeSystem
- Iftrue
the system apps are included.- Returns:
- The collection of configurable WebApps.
- Since:
- 5.2.2001
-
removeGlobalWebApp
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
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
Return descriptors of all installed modules.- Returns:
- Descriptors of all installed modules.
- Since:
- 5.1.103
-
startService
Starts the service with the givenserviceName
.- 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
Returnstrue
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
Returnstrue
if the given service is currently running.- Parameters:
serviceName
- service to check.- Returns:
true
if the service is running.- Since:
- 5.2.13
-
setAutostart
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
Stops the service with the givenserviceName
.- 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
-
install(InputStream,UpdateUsagesMode)
instead