Merge pull request #109 from adamretter/develop

Fixed some javadoc descriptions which were misleading

src/org/exist/storage/StartupTrigger.java

@@ -12,13 +12,19 @@ public interface StartupTrigger {
 
     /**
      * Synchronously execute a task at database Startup before the database is made available to connections
-     * 
+     * Remember, your code within the execute function will block the database startup until it completes!
+     *
      * Any RuntimeExceptions thrown will be ignored and database startup will continue
      * Database Startup cannot be aborted by this Trigger!
      * 
-     * Note, If you want an Asynchronous Trigger, simply use a Future in your implementation
+     * Note: If you want an Asynchronous Trigger, you could use a Future in your implementation
+     * to start a new thread, however you cannot access the sysBroker from that thread
+     * as it may have been returned to the broker pool. Instead if you need a broker, you may be able to
+     * do something clever by checking the database status and then acquiring a new broker
+     * from the broker pool. If you wish to work with the broker pool you must obtain this before
+     * starting your asynchronous execution by calling sysBroker.getBrokerPool().
      * 
-     * @param broker
+     * @param sysBroker The single system broker available during database startup
      * @param params Key, Values
      */
     public void execute(final DBBroker sysBroker, final Map<String, List<? extends Object>> params);

src/org/exist/storage/SystemTask.java

@@ -1,6 +1,6 @@
 /*
  *  eXist Open Source Native XML Database
- *  Copyright (C) 2001-04 The eXist Team
+ *  Copyright (C) 2014 The eXist Team
  *
  *  http://exist-db.org
  *  
@@ -37,12 +37,14 @@
  * written to the log.
  * 
  * A task can be scheduled for execution 
- * via {@link BrokerPool#triggerSystemTask(SystemTask)}.
+ * via {@link BrokerPool#triggerSystemTask(SystemTask)} or
+ * {@link org.exist.scheduler.Scheduler}.
  *
  * IMPORTANT: SystemTask implementations should avoid to acquire
  * locks on collections! Doing so may lead to a deadlock situation.
- * The system task runs in a privileged mode. Locking a collection is
- * not required since no writing transactions will be allowed.
+ * The system task runs in a privileged mode. Locking collections
+ * and resources is not required as no other transactions will be
+ * taking place.
  * 
  * @author wolf
  */
@@ -66,4 +68,4 @@ public interface SystemTask {
 	 * runs. A checkpoint guarantees that all changes were written to disk.
 	 */
 	boolean afterCheckpoint();
-}
+}