fixes #3859, documented why some of the methods are deprecated

svn changeset:10371/svn branch:6.2

1 files changed, 29 insertions, 21 deletions

diff --git a/src/com/vaadin/service/ApplicationContext.java b/src/com/vaadin/service/ApplicationContext.java
index 3d2c76c8d0..244e3d1bdf 100644
--- a/src/com/vaadin/service/ApplicationContext.java
+++ b/src/com/vaadin/service/ApplicationContext.java
@@ -11,13 +11,14 @@ import java.util.Collection;
 
 import com.vaadin.Application;
 import com.vaadin.terminal.ApplicationResource;
+import com.vaadin.terminal.gwt.server.AbstractCommunicationManager;
 
 /**
  * <code>ApplicationContext</code> provides information about the running
  * context of the application. Each context is shared by all applications that
  * are open for one user. In a web-environment this corresponds to a
  * HttpSession.
- *
+ * 
  * @author IT Mill Ltd.
  * @version
  * @VERSION@
@@ -27,13 +28,13 @@ public interface ApplicationContext extends Serializable {
 
     /**
      * Returns application context base directory.
-     *
+     * 
      * Typically an application is deployed in a such way that is has an
      * application directory. For web applications this directory is the root
      * directory of the web applications. In some cases applications might not
      * have an application directory (for example web applications running
      * inside a war).
-     *
+     * 
      * @return The application base directory or null if the application has no
      *         base directory.
      */
@@ -41,9 +42,9 @@ public interface ApplicationContext extends Serializable {
 
     /**
      * Returns a collection of all the applications in this context.
-     *
+     * 
      * Each application context contains all active applications for one user.
-     *
+     * 
      * @return A collection containing all the applications in this context.
      */
     public Collection<Application> getApplications();
@@ -52,15 +53,15 @@ public interface ApplicationContext extends Serializable {
      * Adds a transaction listener to this context. The transaction listener is
      * called before and after each each request related to this session except
      * when serving static resources.
-     *
-     *
+     * 
+     * 
      * @see com.vaadin.service.ApplicationContext#addTransactionListener(com.vaadin.service.ApplicationContext.TransactionListener)
      */
     public void addTransactionListener(TransactionListener listener);
 
     /**
      * Removes a transaction listener from this context.
-     *
+     * 
      * @param listener
      *            the listener to be removed.
      * @see TransactionListener
@@ -75,8 +76,10 @@ public interface ApplicationContext extends Serializable {
      * not from a background thread. The return value is null if used outside a
      * suitable request.
      * 
-     * @deprecated this is subject to change/removal from the interface
-     *
+     * @deprecated this method is intended for terminal implementation only and
+     *             is subject to change/removal from the interface (to
+     *             {@link AbstractCommunicationManager})
+     * 
      * @param resource
      * @param urlKey
      *            a key for the resource that can later be extracted from a URL
@@ -88,9 +91,11 @@ public interface ApplicationContext extends Serializable {
 
     /**
      * Tests if a URL is for an application resource (APP/...).
-     *
-     * @deprecated this is subject to change/removal from the interface
-     *
+     * 
+     * @deprecated this method is intended for terminal implementation only and
+     *             is subject to change/removal from the interface (to
+     *             {@link AbstractCommunicationManager})
+     * 
      * @param context
      * @param relativeUri
      * @return
@@ -103,9 +108,12 @@ public interface ApplicationContext extends Serializable {
      * the one that was given to
      * {@link #generateApplicationResourceURL(ApplicationResource, String)} when
      * creating the URL.
-     *
-     * @deprecated this is subject to change/removal from the interface
-     *
+     * 
+     * @deprecated this method is intended for terminal implementation only and
+     *             is subject to change/removal from the interface (to
+     *             {@link AbstractCommunicationManager})
+     * 
+     * 
      * @param context
      * @param relativeUri
      * @return
@@ -116,18 +124,18 @@ public interface ApplicationContext extends Serializable {
     /**
      * Interface for listening to transaction events. Implement this interface
      * to listen to all transactions between the client and the application.
-     *
+     * 
      */
     public interface TransactionListener extends Serializable {
 
         /**
          * Invoked at the beginning of every transaction.
-         *
+         * 
          * The transaction is linked to the context, not the application so if
          * you have multiple applications running in the same context you need
          * to check that the request is associated with the application you are
          * interested in. This can be done looking at the application parameter.
-         *
+         * 
          * @param application
          *            the Application object.
          * @param transactionData
@@ -138,12 +146,12 @@ public interface ApplicationContext extends Serializable {
 
         /**
          * Invoked at the end of every transaction.
-         *
+         * 
          * The transaction is linked to the context, not the application so if
          * you have multiple applications running in the same context you need
          * to check that the request is associated with the application you are
          * interested in. This can be done looking at the application parameter.
-         *
+         * 
          * @param applcation
          *            the Application object.
          * @param transactionData