svn commit: r1778346 - /uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/LowLevelCAS.java

[sc...@apache.org]

Author: schor
Date: Wed Jan 11 20:21:54 2017
New Revision: 1778346

URL: http://svn.apache.org/viewvc?rev=1778346&view=rev
Log:
no Jira update comments for v3

Modified:
    uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/LowLevelCAS.java

Modified: uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/LowLevelCAS.java
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/LowLevelCAS.java?rev=1778346&r1=1778345&r2=1778346&view=diff
==============================================================================
--- uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/LowLevelCAS.java (original)
+++ uima/uimaj/branches/experiment-v3-jcas/uimaj-core/src/main/java/org/apache/uima/cas/impl/LowLevelCAS.java Wed Jan 11 20:21:54 2017
@@ -240,17 +240,27 @@ public interface LowLevelCAS {
    * Get the low-level reference from an existing FS object. Use this API if you already have a FS
    * object from somewhere, and want to apply low-level APIs to it.
    * 
+   * Has a side effect of adding the FS to the internal table allowing ll_getFSforRef.  
+   * 
+   * Note: This prevents the object from being GC'd, so this use is deprecated.
+   * 
    * @param fsImpl
    *          The FS object for which we want the reference.
    * @return The low-level reference of the FS object parameter.
+   * 
    */
   int ll_getFSRef(FeatureStructure fsImpl);
 
   /**
-   * Return a FS object that corresponds to a low-level reference. Note that this <b>must</b> be a
+   * <p>Return a FS object that corresponds to a low-level reference. Note that this <b>must</b> be a
    * valid reference that has been obtained from the low-level APIs. If the input reference
-   * parameter does not represent a valid reference, the results of this call are undefined.
-   * 
+   * parameter does not represent a valid reference, an exception is thrown.
+   * </p>
+   * <p>In version 3, the map this API uses is not normally populated; it is populated only 
+   * for Feature Structures created using the low-level APIs, and also when 
+   * the ll_getFSRef API (above) is used, or the getAddress
+   * method is called on a Feature Structure
+   * </p>
    * @param fsRef
    *          The FS reference.
    * @param <T> the Java class for the Feature Structure