Javadocs for #9273

7 files changed, 184 insertions, 5 deletions

diff --git a/server/src/com/vaadin/terminal/gwt/server/AbstractApplicationPortlet.java b/server/src/com/vaadin/terminal/gwt/server/AbstractApplicationPortlet.java
index 40958e2868..17986f7f53 100644
--- a/server/src/com/vaadin/terminal/gwt/server/AbstractApplicationPortlet.java
+++ b/server/src/com/vaadin/terminal/gwt/server/AbstractApplicationPortlet.java
@@ -801,7 +801,7 @@ public abstract class AbstractApplicationPortlet extends GenericPortlet
             application.start(new ApplicationStartEvent(null,
                     getDeploymentConfiguration().getInitParameters(), context,
                     isProductionMode()));
-            addonContext.applicationStarted(application);
+            addonContext.fireApplicationStarted(application);
         }
     }
 
diff --git a/server/src/com/vaadin/terminal/gwt/server/AbstractApplicationServlet.java b/server/src/com/vaadin/terminal/gwt/server/AbstractApplicationServlet.java
index 6a6a00843c..d3adbeaf19 100644
--- a/server/src/com/vaadin/terminal/gwt/server/AbstractApplicationServlet.java
+++ b/server/src/com/vaadin/terminal/gwt/server/AbstractApplicationServlet.java
@@ -901,7 +901,7 @@ public abstract class AbstractApplicationServlet extends HttpServlet implements
             application.start(new ApplicationStartEvent(applicationUrl,
                     getDeploymentConfiguration().getInitParameters(),
                     webApplicationContext, isProductionMode()));
-            addonContext.applicationStarted(application);
+            addonContext.fireApplicationStarted(application);
         }
     }
 
diff --git a/server/src/com/vaadin/terminal/gwt/server/AddonContext.java b/server/src/com/vaadin/terminal/gwt/server/AddonContext.java
index 41e9046e22..66918c7e5a 100644
--- a/server/src/com/vaadin/terminal/gwt/server/AddonContext.java
+++ b/server/src/com/vaadin/terminal/gwt/server/AddonContext.java
@@ -8,12 +8,31 @@ import java.lang.reflect.Method;
 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",
@@ -27,15 +46,37 @@ public class AddonContext {
 
     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
@@ -47,6 +88,12 @@ public class AddonContext {
         }
     }
 
+    /**
+     * 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) {
@@ -54,23 +101,60 @@ public class AddonContext {
         }
     }
 
+    /**
+     * 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,
diff --git a/server/src/com/vaadin/terminal/gwt/server/AddonContextEvent.java b/server/src/com/vaadin/terminal/gwt/server/AddonContextEvent.java
index 33f681499f..ea97153afe 100644
--- a/server/src/com/vaadin/terminal/gwt/server/AddonContextEvent.java
+++ b/server/src/com/vaadin/terminal/gwt/server/AddonContextEvent.java
@@ -6,12 +6,32 @@ package com.vaadin.terminal.gwt.server;
 
 import java.util.EventObject;
 
+/**
+ * Event used when an {@link AddonContext} is created and destroyed.
+ * 
+ * @see AddonContextListener
+ * 
+ * @author Vaadin Ltd
+ * @version @VERSION@
+ * @since 7.0.0
+ */
 public class AddonContextEvent extends EventObject {
 
+    /**
+     * Creates a new event for the given add-on context.
+     * 
+     * @param source
+     *            the add-on context that created the event
+     */
     public AddonContextEvent(AddonContext source) {
         super(source);
     }
 
+    /**
+     * Gets the add-on context that created this event.
+     * 
+     * @return the add-on context that created this event.
+     */
     public AddonContext getAddonContext() {
         return (AddonContext) getSource();
     }
diff --git a/server/src/com/vaadin/terminal/gwt/server/AddonContextListener.java b/server/src/com/vaadin/terminal/gwt/server/AddonContextListener.java
index 93e7df4ede..5cc82b9994 100644
--- a/server/src/com/vaadin/terminal/gwt/server/AddonContextListener.java
+++ b/server/src/com/vaadin/terminal/gwt/server/AddonContextListener.java
@@ -6,8 +6,37 @@ package com.vaadin.terminal.gwt.server;
 
 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);
 }
diff --git a/server/src/com/vaadin/terminal/gwt/server/ApplicationStartedEvent.java b/server/src/com/vaadin/terminal/gwt/server/ApplicationStartedEvent.java
index 339b88222e..24193adc5d 100644
--- a/server/src/com/vaadin/terminal/gwt/server/ApplicationStartedEvent.java
+++ b/server/src/com/vaadin/terminal/gwt/server/ApplicationStartedEvent.java
@@ -8,19 +8,45 @@ import java.util.EventObject;
 
 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;
     }
diff --git a/server/src/com/vaadin/terminal/gwt/server/ApplicationStartedListener.java b/server/src/com/vaadin/terminal/gwt/server/ApplicationStartedListener.java
index 87884a0fda..07e22a90de 100644
--- a/server/src/com/vaadin/terminal/gwt/server/ApplicationStartedListener.java
+++ b/server/src/com/vaadin/terminal/gwt/server/ApplicationStartedListener.java
@@ -6,6 +6,26 @@ package com.vaadin.terminal.gwt.server;
 
 import java.util.EventListener;
 
+import com.vaadin.Application;
+
+/**
+ * Listener that gets notified when a new {@link Application} has been started.
+ * Add-ons can use this listener to automatically integrate with API tied to the
+ * Application API.
+ * 
+ * @see AddonContext#addApplicationStartedListener(ApplicationStartedListener)
+ * 
+ * @author Vaadin Ltd
+ * @version @VERSION@
+ * @since 7.0.0
+ */
 public interface ApplicationStartedListener extends EventListener {
+    /**
+     * Tells the listener that an application has been started (meaning that
+     * {@link Application#init()} has been invoked.
+     * 
+     * @param event
+     *            details about the event
+     */
     public void applicationStarted(ApplicationStartedEvent event);
 }