org.gcube.data.tmf.api
Interface SourceLifecycle

All Superinterfaces:

Serializable

All Known Implementing Classes:

LifecycleAdapter

public interface SourceLifecycle
extends Serializable

A set of callbacks made by the service to the plugin at key points in the lifecycle of a Source, i.e. when the plugin needs to start, stop, refine, or resume its management of the corresponding data source.

Plugins are expected to associate sources with implementations of this interface, before the SourceBinder returns the bound sources to the service. When they need to implement only a subset of the callbacks, they can conveniently subclass the LifecycleAdapter.

Author:

Fabio Simeoni

See Also:

Source.lifecycle(), SourceBinder, LifecycleAdapter

Method Summary

void	init() Tells the plugin to start managing the data source.
void	reconfigure(Element request) Gives the plugin a client request with which it can refine its management of the data source.
void	resume() Tells the plugin to resume its management of the data source.
void	stop() Tells the plugin to stop its management of the data source until further notice.
void	terminate() Tells the plugin to stop its management of the data source for good.

Method Detail

init

void init()
          throws Exception

Tells the plugin to start managing the data source.

This occurs during the binding the data source, immediately after the SourceBinder has returned the corresponding Source to the service.

Plugins may implement this method to initialise the state of the Source and schedule any operation that relates to the management of the data source.

If this method fails, the binding between the plugin and the data source also fails.

Throws:

Exception - if the operation cannot be completed

See Also:

SourceBinder.bind(Element)

reconfigure

void reconfigure(Element request)
                 throws org.gcube.common.clients.exceptions.InvalidRequestException,
                        Exception

Gives the plugin a client request with which it can refine its management of the data source.

This occurs during the binding of a data source, when the SourceBinder returns to the service a Source with the same identifier as the Source associated with this instance. This indicates that the plugin is already managing the corresponding data source and that the client request should be used to re-configure the existing Source rather than initialise the new one.

Plugins may implement this method to refine the state of a Source or to change otherwise its management of the corresponding data source.

If this method fails, the client request fails and the plugin retains its current management regime for the data source.

Throws:

org.gcube.common.clients.exceptions.InvalidRequestException - if the client request is incompatible with the current management regime of the data source.

Exception - if the operation cannot be completed for any other reason

See Also:

SourceBinder.bind(Element)

resume

void resume()
            throws Exception

Tells the plugin to resume its management of the data source.

This occurs when the service is restoring its state from persistent storage after a restart of the container.

Plugins may implement this method to restart scheduled operations which relate to the management of the data source.

If this method fails, all subsequent client requests about the data source fail.

Throws:

Exception - if the operation cannot be completed

stop

void stop()

Tells the plugin to stop its management of the data source until further notice.

This may occur when the container is shutting down, or when the service is serialising its state to persistence storage so as to conserve memory resources.

Plugins may implement this method to gracefully stop any operation that relates to the management of the data source.

terminate

void terminate()

Tells the plugin to stop its management of the data source for good.

This occurs when clients indicate that access to the data source is no longer needed.

Plugins may implement this method to terminate any scheduled operation that relates to the management of the data source, or to perform any other relevant form of state cleanup.