import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
+import java.util.ServiceLoader;
import com.vaadin.Application;
import com.vaadin.event.EventRouter;
import com.vaadin.terminal.DeploymentConfiguration;
import com.vaadin.tools.ReflectTools;
+/**
+ * Point of entry for add-ons for integrating into various aspects of the
+ * framework. One add-on context is initialized for each Vaadin Servlet or
+ * Portlet instance and upon initialization, every {@link AddonContextListener}
+ * that can be found is notified to let it add listeners to the context.
+ * <p>
+ * By default, AddonContextListeners are loaded using {@link ServiceLoader},
+ * which means that the file
+ * META-INF/services/com.vaadin.terminal.gwt.server.AddonContextListener will be
+ * checked for lines containing fully qualified names of classes to use. This
+ * behavior can however be overridden for custom deployment situations (e.g. to
+ * use CDI or OSGi) by overriding
+ * {@link DeploymentConfiguration#getAddonContextListeners()}.
+ *
+ * @author Vaadin Ltd
+ * @version @VERSION@
+ * @since 7.0.0
+ */
public class AddonContext {
private static final Method APPLICATION_STARTED_METHOD = ReflectTools
.findMethod(ApplicationStartedListener.class, "applicationStarted",
private List<AddonContextListener> initedListeners = new ArrayList<AddonContextListener>();
+ /**
+ * Creates a new context using a given deployment configuration. Only the
+ * framework itself should typically create AddonContext methods.
+ *
+ * @param deploymentConfiguration
+ * the deployment configuration for the associated servlet or
+ * portlet.
+ */
public AddonContext(DeploymentConfiguration deploymentConfiguration) {
this.deploymentConfiguration = deploymentConfiguration;
deploymentConfiguration.setAddonContext(this);
}
+ /**
+ * Gets the deployment configuration for this context.
+ *
+ * @return the deployment configuration
+ */
public DeploymentConfiguration getDeploymentConfiguration() {
return deploymentConfiguration;
}
+ /**
+ * Initializes this context, causing all found listeners to be notified.
+ * Listeners are by default found using {@link ServiceLoader}, but the
+ * {@link DeploymentConfiguration} can provide an alternative
+ * implementation.
+ * <p>
+ * This method is not intended to be used by add-ons, but instead by the
+ * part of the framework that created this context object.
+ */
public void init() {
AddonContextEvent event = new AddonContextEvent(this);
Iterator<AddonContextListener> listeners = deploymentConfiguration
}
}
+ /**
+ * Destroys this context, causing all initialized listeners to be invoked.
+ * <p>
+ * This method is not intended to be used by add-ons, but instead by the
+ * part of the framework that created this context object.
+ */
public void destroy() {
AddonContextEvent event = new AddonContextEvent(this);
for (AddonContextListener listener : initedListeners) {
}
}
+ /**
+ * Shorthand for adding a bootstrap listener that will be added to every new
+ * application.
+ *
+ * @see #addApplicationStartedListener(ApplicationStartedListener)
+ * @see Application#addBootstrapListener(BootstrapListener)
+ *
+ * @param listener
+ * the bootstrap listener that should be added to all new
+ * applications.
+ */
public void addBootstrapListener(BootstrapListener listener) {
bootstrapListeners.add(listener);
}
- public void applicationStarted(Application application) {
+ /**
+ * Fires an {@link ApplicationStartedEvent} to all registered listeners.
+ * This method is not intended to be used by add-ons, but instead by the
+ * part of the framework that creates new Application instances.
+ *
+ * @see #addApplicationStartedListener(ApplicationStartedListener)
+ *
+ * @param application
+ * the newly started application
+ */
+ public void fireApplicationStarted(Application application) {
eventRouter.fireEvent(new ApplicationStartedEvent(this, application));
for (BootstrapListener l : bootstrapListeners) {
application.addBootstrapListener(l);
}
}
+ /**
+ * Adds a listener that will be notified any time a new {@link Application}
+ * instance is started or more precisely directly after
+ * {@link Application#init()} has been invoked.
+ *
+ * @param applicationStartListener
+ * the application start listener that should be added
+ */
public void addApplicationStartedListener(
ApplicationStartedListener applicationStartListener) {
eventRouter.addListener(ApplicationStartedEvent.class,
applicationStartListener, APPLICATION_STARTED_METHOD);
}
+ /**
+ * Removes an application start listener.
+ *
+ * @see #addApplicationStartedListener(ApplicationStartedListener)
+ *
+ * @param applicationStartListener
+ * the application start listener to remove
+ */
public void removeApplicationStartedListener(
ApplicationStartedListener applicationStartListener) {
eventRouter.removeListener(ApplicationStartedEvent.class,
import java.util.EventListener;
+/**
+ * Listener that gets notified then the {@link AddonContext} is initialized,
+ * allowing an add-on to add listeners to various parts of the framework. In a
+ * default configuration, add-ons can register their listeners by including a
+ * file named
+ * META-INF/services/com.vaadin.terminal.gwt.server.AddonContextListener
+ * containing the fully qualified class names of classes implementing this
+ * interface.
+ *
+ * @author Vaadin Ltd
+ * @version @VERSION@
+ * @since 7.0.0
+ */
public interface AddonContextListener extends EventListener {
+ /**
+ * Notifies the listener that the add-on context has been created and
+ * initialized. An add-on can use this method to get access to an
+ * {@link AddonContext} object to which listeners can be added.
+ *
+ * @param event
+ * the add-on context event
+ */
public void contextCreated(AddonContextEvent event);
+ /**
+ * Notifies the listener that the add-on context has been closed. An add-on
+ * can use this method to e.g. close resources that have been opened in
+ * {@link #contextCreated(AddonContextEvent)}.
+ *
+ * @param event
+ * the add-on context event
+ */
public void contextDestoryed(AddonContextEvent event);
}
import com.vaadin.Application;
+/**
+ * Event used by
+ * {@link ApplicationStartedListener#applicationStarted(ApplicationStartedEvent)}
+ * .
+ *
+ * @author Vaadin Ltd
+ * @version @VERSION@
+ * @since 7.0.0
+ */
public class ApplicationStartedEvent extends EventObject {
private final Application application;
- public ApplicationStartedEvent(AddonContext context,
- Application application) {
+ /**
+ * Creates a new event.
+ *
+ * @param context
+ * the add-on context that will fire the event
+ * @param application
+ * the application that has been started
+ */
+ public ApplicationStartedEvent(AddonContext context, Application application) {
super(context);
this.application = application;
}
+ /**
+ * Gets the add-on context from which this event originated.
+ *
+ * @return the add-on context that fired the
+ */
public AddonContext getContext() {
return (AddonContext) getSource();
}
+ /**
+ * Gets the newly started Application.
+ *
+ * @return the newly created application
+ */
public Application getApplication() {
return application;
}
projects / vaadin-framework.git / commitdiff