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

[Vladmir Blagojevic]

  User: vblagojevic
  Date: 06/09/01 14:46:43

  Modified:    src/org/jboss/cache/loader  CacheLoader.java
  Log:
  updated javadoc for loadState/storeState methods
  
  Revision  Changes    Path
  1.8       +56 -16    JBossCache/src/org/jboss/cache/loader/CacheLoader.java
  
  (In the diff below, changes in quantity of whitespace are not shown.)
  
  Index: CacheLoader.java
  ===================================================================
  RCS file: /cvsroot/jboss/JBossCache/src/org/jboss/cache/loader/CacheLoader.java,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -b -r1.7 -r1.8
  --- CacheLoader.java	31 Aug 2006 14:56:45 -0000	1.7
  +++ CacheLoader.java	1 Sep 2006 18:46:43 -0000	1.8
  @@ -181,40 +181,68 @@
   
       /**
       * Fetches the entire state for this cache from secondary storage (disk, database)
  -    * and writes it to a provided OutputStream. This is for initialization of a new
  -    * cache from a remote cache. The new cache would then call
  -    *{@link #storeEntireState(ObjectInputStream)}
  +    * and writes it to a provided ObjectOutputStream. State written to the provided 
  +    * ObjectOutputStream parameter is used for initialization of a new TreeCache instance. 
  +    * When the state gets transferred to the new cache instance its cacheloader calls
  +    * {@link #storeEntireState(ObjectInputStream)}
       *
  -    * @param os OutputStream to write state
  +    * <p>
  +    * Implementations of this method should not catch any exception or close the 
  +    * given ObjectOutputStream parameter. In order to ensure cacheloader interoperability 
  +    * contents of the cache are written to the ObjectOutputStream as a sequence of 
  +    * NodeData objects.
  +    * 
  +    * @see NodeData
  +    *
  +    * @param os ObjectOutputStream to write state
       */
       void loadEntireState(ObjectOutputStream os) throws Exception;
   
       /**
  -    * Stores the state in secondary storage by reading it from the give InputStream. 
  -    * Overwrites whatever is currently in storage.
       *
  -    * @param is InputStream to read state 
  +    * Stores the entire state for this cache by reading it from a provided ObjectInputStream. 
  +    * The state was provided to this cache by calling {@link #loadEntireState(ObjectOutputStream)}} 
  +    * on some other cache instance. State currently in storage gets overwritten.
  +    * <p>
  +    * Implementations of this method should not catch any exception or close the 
  +    * given ObjectInputStream parameter. In order to ensure cacheloader interoperability 
  +    * contents of the cache are read from the ObjectInputStream as a sequence of 
  +    * NodeData objects.
  +    *  
  +    * 
  +    * @see NodeData    
  +    * @param is ObjectInputStream to read state 
       * 
       */
       void storeEntireState(ObjectInputStream is) throws Exception;
   
       /**
  -    * Fetch a portion of the state for this cache from secondary storage
  -    * (disk, database) and write it to a provided OutputStream.
  -    * This is for activation of a portion of new cache from a remote cache.
  -    * The new cache would then call {@link #storeState(Fqn, ObjectInputStream)}.
  +    * Fetches a portion of the state for this cache from secondary storage (disk, database)
  +    * and writes it to a provided ObjectOutputStream. State written to the provided 
  +    * ObjectOutputStream parameter is used for activation of a portion of a new TreeCache instance. 
  +    * When the state gets transferred to the new cache instance its cacheloader calls
  +    * {@link #storeState(Fqn, ObjectInputStream)}.
  +    *
  +    * <p>
  +    * Implementations of this method should not catch any exception or close the 
  +    * given ObjectOutputStream parameter. In order to ensure cacheloader interoperability 
  +    * contents of the cache are written to the ObjectOutputStream as a sequence of 
  +    * NodeData objects.
  +    *     
  +    * 
       *
       * @param subtree Fqn naming the root (i.e. highest level parent) node of
       *                the subtree for which state is requested.
       *                
  -    * @param os OutputStream to write state               
  +    * @param os ObjectOutputStream to write state               
       *
       * @see org.jboss.cache.Region#activate() 
  +    * @see NodeData
       */
       void loadState(Fqn subtree,ObjectOutputStream os) throws Exception;
   
       /**
  -    * Store the given portion of the cache tree's state in secondary storage.
  +    * Stores the given portion of the cache tree's state in secondary storage.
       * Overwrite whatever is currently in secondary storage.  If the transferred
       * state has Fqns equal to or children of parameter <code>subtree</code>,
       * then no special behavior is required.  Otherwise, ensure that
  @@ -222,6 +250,7 @@
       * in the latter case <code>subtree</code> would be the Fqn of the buddy
       * backup region for
       * a buddy group; e.g.
  +    * 
       * <p>
       * If the the transferred state had Fqns starting with "/a" and
       * <code>subtree</code> was "/_BUDDY_BACKUP_/192.168.1.2:5555" then the
  @@ -229,13 +258,24 @@
       * "/_BUDDY_BACKUP_/192.168.1.2:5555/a"
       * </p>
       *
  -    * @param is InputStream to read state 
  +    * <p>
  +    * 
  +    * Implementations of this method should not catch any exception or close the 
  +    * given ObjectInputStream parameter. In order to ensure cacheloader interoperability 
  +    * contents of the cache are read from the ObjectInputStream as a sequence of 
  +    * NodeData objects.
  +    * <p> 
  +    *     
  +    * @param is ObjectInputStream to read state 
       * @param subtree Fqn naming the root (i.e. highest level parent) node of
       *                the subtree included in <code>state</code>.  If the Fqns
       *                of the data included in <code>state</code> are not
       *                already children of <code>subtree</code>, then their
       *                Fqns should be altered to make them children of
       *                <code>subtree</code> before they are persisted.
  +    *                
  +    * @see NodeData
  +    *
       */
       void storeState(Fqn subtree,ObjectInputStream is) throws Exception;