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:

SpecialistsBroker.requireSpecialist(de.espirit.firstspirit.agency.SpecialistType), SpecialistsBroker.requestSpecialist(de.espirit.firstspirit.agency.SpecialistType)

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ModuleAdminAgent.ModuleResult The module installation/update result containing the installed/upgraded module descriptor and the process log message.

Field Summary

Fields

Modifier and Type	Field and Description
static SpecialistType<ModuleAdminAgent>	TYPE Agent providing administrative methods for maintaining FirstSpirit server modules.

Method Summary

Methods

Modifier and Type	Method and Description
GlobalWebAppId	createGlobalWebApp(String globalWebAppId, String contextName, String description) Creates a global web-app.
InputStream	downloadWebApp(WebAppId webAppId) Download the specified web app as .war-file.
Collection<GlobalWebAppId>	getGlobalWebApps() Returns all global web-apps.
String	getInstalledVersion(String moduleName) Returns the version of the given module.
Collection<ModuleDescriptor>	getModules() Return descriptors of all installed modules.
FileSystem<?>	getProjectAppConfig(String moduleName, String projectAppName, 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 a SecurityException will be thrown.
Collection<Project>	getProjectAppUsages(String moduleName, String projectAppName) Returns all project ids using the specified project application.
Collection<WebAppId>	getWebAppUsages(String moduleName, String webAppComponent) Returns all usages of the given web-app component.
ModuleAdminAgent.ModuleResult	install(InputStream fsmStream, boolean updateUsages) Installs or updates the given module.
void	installProjectApp(String moduleName, String projectAppName, Project project) Installs or updates a project application to the specified project.
void	installWebApp(String moduleName, String webAppComponent, WebAppId webAppId) Installs or updates the given web-app component into the specified web app and deploys the web app to it's web-server.
void	removeGlobalWebApp(GlobalWebAppId globalWebAppId) Undeploys and destroys the given global web-app.
void	startService(String serviceName) Starts the service with the given serviceName.
void	stopService(String serviceName) Stops the service with the given serviceName.
void	uninstall(String moduleName, boolean removeUsages) Uninstalls the given module.
void	uninstallProjectApp(String moduleName, String projectAppName, 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 it's web-server.

Field Detail

TYPE

static final SpecialistType<ModuleAdminAgent> TYPE

Agent providing administrative methods for maintaining FirstSpirit server modules. The agent's technical type to be used to request the agent from a SpecialistsBroker.

Since:

5.1.103

See Also:

SpecialistsBroker.requireSpecialist(de.espirit.firstspirit.agency.SpecialistType), SpecialistsBroker.requestSpecialist(de.espirit.firstspirit.agency.SpecialistType)

Method Detail

install

@NotNull
ModuleAdminAgent.ModuleResult install(InputStream fsmStream,
                                            boolean updateUsages)
                                      throws IOException,
                                             ModuleException

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 (appropriate 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).

Since:

5.1.103

See Also:

uninstall(String, boolean)

uninstall

void uninstall(String moduleName,
             boolean removeUsages)
               throws ModuleException

Uninstalls the given module. If removeUsages is true all project-app and and web-app components will be removed and appropriate web-apps will be deployed. 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.

Since:

5.1.103

See Also:

install(InputStream, boolean)

installProjectApp

void installProjectApp(String moduleName,
                     String projectAppName,
                     @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.

Since:

5.1.103

See Also:

uninstallProjectApp(String, String, Project)

getProjectAppConfig

@NotNull
FileSystem<?> getProjectAppConfig(String moduleName,
                                        String projectAppName,
                                        @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.

Since:

5.1.103

getProjectAppUsages

@NotNull
Collection<Project> getProjectAppUsages(String moduleName,
                                              String projectAppName)

Returns all project ids using the specified project application.

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
                       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.

Since:

5.1.103

See Also:

installProjectApp(String, String, Project)

installWebApp

void installWebApp(String moduleName,
                 String webAppComponent,
                 @NotNull
                 WebAppId webAppId)
                   throws ModuleException

Installs or updates the given web-app component into the specified web app and deploys the web app to it's web-server.

Parameters:

moduleName - name of the module containing the web-app component.

webAppComponent - web-app component name.

webAppId - target web-app.

Throws:

ModuleException

Since:

5.1.103

See Also:

uninstallWebApp(String, String, WebAppId)

downloadWebApp

@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.

Since:

5.1.103

getWebAppUsages

@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.

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 it's web-server.

Parameters:

moduleName - name of the module containing the web-app component.

webAppComponent - web-app component name.

webAppId - target web-app.

Throws:

ModuleException

Since:

5.1.103

See Also:

installWebApp(String, String, WebAppId)

createGlobalWebApp

GlobalWebAppId createGlobalWebApp(String globalWebAppId,
                                String contextName,
                                String description)

Creates a global web-app.

Parameters:

globalWebAppId - new global web-app identifier.

contextName - web-server context where to install the web-app.

description - description for this global web-app, visible in the FirstSpirit ServerManager.

Returns:

web-app identifier.

Since:

5.1.103

See Also:

removeGlobalWebApp(GlobalWebAppId)

getGlobalWebApps

@NotNull
Collection<GlobalWebAppId> getGlobalWebApps()

Returns all global web-apps.

Returns:

all global web-apps.

Since:

5.1.103

removeGlobalWebApp

void removeGlobalWebApp(GlobalWebAppId globalWebAppId)

Undeploys and destroys the given global web-app.

Parameters:

globalWebAppId - global web-app identifier.

Since:

5.1.103

See Also:

createGlobalWebApp(String, String, String)

getInstalledVersion

@Nullable
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

Collection<ModuleDescriptor> getModules()

Return descriptors of all installed modules.

Returns:

Descriptors of all installed module.

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.

Since:

5.1.103

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.

Since:

5.1.103