[jboss-cvs] JBossCache/src/org/jboss/cache ...

[Manik Surtani]

  User: msurtani
  Date: 07/01/19 10:02:52

  Modified:    src/org/jboss/cache  Cache.java
  Log:
  Improved Javadocs
  
  Revision  Changes    Path
  1.22      +8 -3      JBossCache/src/org/jboss/cache/Cache.java
  
  (In the diff below, changes in quantity of whitespace are not shown.)
  
  Index: Cache.java
  ===================================================================
  RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/Cache.java,v
  retrieving revision 1.21
  retrieving revision 1.22
  diff -u -b -r1.21 -r1.22
  --- Cache.java	19 Jan 2007 14:47:40 -0000	1.21
  +++ Cache.java	19 Jan 2007 15:02:52 -0000	1.22
  @@ -149,15 +149,20 @@
      Object put(Fqn fqn, Object key, Object value);
   
      /**
  -    * Under special operating behavior, associates the value with the specified key for a {@link Node}:
  +    * Under special operating behavior, associates the value with the specified key for a node identified by the Fqn passed in.
       * <ul>
       * <li> Ongoing transactions are suspended before this call, so failures here will not affect any ongoing transactions.</li>
       * <li> Errors and exceptions are 'silent' - logged at a much lower level than normal, and this method does not throw exceptions</li>
       * <li> Lock acquisition timeouts are dropped to 0 to improve performance</li>
       * <li> If pessimistic locking is used, write locks are not obtained here - even though this is a write.  Instead, read locks are used.<li>
       * </ul>
  -    * This method is for caching data that has an external representation in storage,
  -    * where, concurrent modification and transactions are not a consideration.
  +    * This method is for caching data that has an external representation in storage, where, concurrent modification and
  +    * transactions are not a consideration, and failure to put the data in the cache should be treated as a 'suboptimal outcome'
  +    * rather than a 'failing outcome'.
  +    * <p/>
  +    * An example of when this method is useful is when data is read from, for example, a legacy datastore, and is cached before
  +    * returning the data to the caller.  Subsequent calls would prefer to get the data from the cache and if the data doesn't exist
  +    * in the cache, fetch again from the legacy datastore.
       * <p/>
       *
       * @param fqn   <b><i>absolute</i></b> {@link Fqn} to the {@link Node} to be accessed.