net.openwings.install
Interface Installer

public interface Installer

This interface is the main interface for an Openwings Installer.

Through this interface components may be added, removed, and queried. Information about component is queried through configuration files, called policies.

It is expected that one installation service will run per platform. To achieve a cluster or context based installation the programmatic access to the service can be used.

Method Summary

void	addInstallListener(InstallListener installListener) This method is used to add an installation listener.
void	addVoter(Voter voter) This method is used to add a voter to vote on removal of components.
InstallableComponentDescriptor[]	getComponents() This method returns an array of ComponentDescriptor for all components installed on the system.
InstallableComponentDescriptor	installComponent(java.net.URL component, boolean overwrite) This method is used to add a Component to a platform.
InstallableComponentDescriptor	installComponent(java.net.URL component, boolean overwrite, boolean runImmediately, boolean serve) This method is used to add a Component to a platform.
void	removeInstallListener(InstallListener installListener) This method is used to remove an installation listener.
void	removeVoter(Voter voter) This method is used to remove a voter.
boolean	uninstallComponent(InstallableComponentDescriptor installableComponentDescriptor, boolean force) This method is used to remove a Component from a platform.

Method Detail

installComponent

public InstallableComponentDescriptor installComponent(java.net.URL component,
                                                       boolean overwrite)
                                                throws InstallException,
                                                       java.rmi.RemoteException

This method is used to add a Component to a platform.

A URL is passed in that points to the installation jar file for the component. If the component is successfully installed, a component identifier will be returned assuming the component is on the local platform. Note that a component identifier from different installers for the same URL may not be equal.

This method is expected to authenticate, install, and resolve dependencies and policies for the component. The component will at least be authenticated and installed after this call successfully completes. The component may not be resolved. This means that its policies may not have been finalized or components that it depends on to run may have not been found. Components should not be run until they have been resolved.

Parameters:

component - url is used to identify the component jar file to be installed.

overwrite - indicates whether the component should be installed if an identical component already has been installed.

Returns:

an InstallableComponentDescriptor if the component is successfully installed.

Throws:

InstallException - is returned if the component cannot be installed for some reason. This can be for security reasons or space reasons.

java.rmi.RemoteException - for communication errors

installComponent

public InstallableComponentDescriptor installComponent(java.net.URL component,
                                                       boolean overwrite,
                                                       boolean runImmediately,
                                                       boolean serve)
                                                throws InstallException,
                                                       java.rmi.RemoteException

This method is used to add a Component to a platform. This variant allows the runImmediatelyHint and serveHint fields of the InstallableComponentDescriptor contained in the component image.

A URL is passed in that points to the installation jar file for the component. If the component is successfully installed, a component identifier will be returned assuming the component is on the local platform. Note that a component identifier from different installers for the same URL may not be equal.

This method is expected to authenticate, install, and resolve dependencies and policies for the component. The component will at least be authenticated and installed after this call successfully completes. The component may not be resolved. This means that its policies may not have been finalized or components that it depends on to run may have not been found. Components should not be run until they have been resolved.

Parameters:

component - url is used to identify the component jar file to be installed.

overwrite - indicates whether the component should be installed if an identical component already has been installed.

runImmediately - allows the user to explicitly request whether the component should be run immediately upon install, instead of relying upon the runImmediatelyHint in the InstallableComponentDescriptor in the component image.

serve - allows the user to explicitly request whether the component should be served for potential installation to other platforms, instead of relying upon the serveHint in the InstallableComponentDescriptor in the component image.

Returns:

an InstallableComponentDescriptor if the component is successfully installed.

Throws:

InstallException - is returned if the component cannot be installed for some reason. This can be for security reasons or space reasons.

java.rmi.RemoteException - for communication errors

uninstallComponent

public boolean uninstallComponent(InstallableComponentDescriptor installableComponentDescriptor,
                                  boolean force)
                           throws InstallException,
                                  java.rmi.RemoteException

This method is used to remove a Component from a platform.

If the component is currently not installed the routine will return without an exception. If the component is unable to be removed (due to running instances of the component or other running components that depend on it), it will be marked for removal. The force option will attempt to remove the component even if running instances or dependencies exist. The force option should be used sparingly as it can cause reduction in system availability.

Parameters:

force - component removal

Returns:

true if the component existed (provided for debugging purposes only).

Throws:

java.rmi.RemoteException - for communication errors

InstallException - is returned if the component cannot be uninstalled for some reason. This can be for security reasons.

getComponents

public InstallableComponentDescriptor[] getComponents()
                                               throws java.rmi.RemoteException

This method returns an array of ComponentDescriptor for all components installed on the system.

Returns:

array of InstallableComponentDescriptors.

Throws:

java.rmi.RemoteException - for communication errors

addInstallListener

public void addInstallListener(InstallListener installListener)
                        throws java.rmi.RemoteException

This method is used to add an installation listener.

Parameters:

installListener - is the callback for installation events. If this Interface is being invoked remotely, it is expected to be distributed (i.e. remote).

Throws:

java.rmi.RemoteException - for communication errors

removeInstallListener

public void removeInstallListener(InstallListener installListener)
                           throws java.rmi.RemoteException

This method is used to remove an installation listener.

Parameters:

installListener - the callback for installation events

Throws:

java.rmi.RemoteException - for communication errors

addVoter

public void addVoter(Voter voter)
              throws java.rmi.RemoteException

This method is used to add a voter to vote on removal of components. The voter interface allows process containers or some other component to say whether or not the component can be removed safely (i.e. it is not running).

Parameters:

voter - the callback for voting events.

Throws:

java.rmi.RemoteException - for communication errors

removeVoter

public void removeVoter(Voter voter)
                 throws java.rmi.RemoteException

This method is used to remove a voter. The voter identifies the voter that will be removed.

Parameters:

voter - callback object previously passed to addVoter

Throws:

java.rmi.RemoteException - for communication errors