merged 1.1 branch into head

[mir.git] / source / mir / producer / Producer.java

diff --git a/source/mir/producer/Producer.java b/source/mir/producer/Producer.java
index a7ffe93..a288304 100755 (executable)
--- a/source/mir/producer/Producer.java
+++ b/source/mir/producer/Producer.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2001, 2002 The Mir-coders group
+ * Copyright (C) 2001-2006 The Mir-coders group
  *
  * This file is part of Mir.
  *
@@ -19,8 +19,6 @@
  *
  * In addition, as a special exception, The Mir-coders gives permission to link
  * the code of this program with  any library licensed under the Apache Software License,
- * The Sun (tm) Java Advanced Imaging library (JAI), The Sun JIMI library
- * (or with modified versions of the above that use the same license as the above),
  * and distribute linked combinations including the two.  You must obey the
  * GNU General Public License in all respects for all of the code used other than
  * the above mentioned libraries.  If you modify this file, you may extend this
@@ -29,17 +27,38 @@
  */
 package mir.producer;
 
-import mir.log.LoggerWrapper;
-
+/**
+ * <p>A Producer is  a set of tasks, scripted  in xml. Producers allow
+ * mir installations to have their  own actions that can be called for
+ * instance when  a new article is posted.   Originally producers were
+ * mostly used  to generate  pages, but  they are used  for a  lot of
+ * other  tasks such  as  pulling rss  feeds  for the  global wire  on
+ * indymedia.org. </p>
+ * 
+ * <p>Producers  can  be  easily  added  and  configured  through  the
+ * producers.xml file.</p>
+ * 
+ * <p>In the  admin web interface,  producers appear, for  example, on
+ * the admin->"Generate manually"->"advanced page": (as Tasks)</p>
+ *
+ * <p>Architecture: a "poducer" tag  in the producers.xml file defines
+ * a small  program. This program  (or script) may  contain constructs
+ * such as  if, loop,  and variables... The  program is parsed  into a
+ * tree  of ProducerNodes.   The root  of this  tree is  defined  in a
+ * NodedProducer (which  is the  only class that  currently implements
+ * the  Producer  interface).   When  the Producer  is  executed,  the
+ * "produce" methods of each  node are recursively called, effectively
+ * executing the program as it was scripted</p>
+ */
 public interface Producer {
   /**
-   *
-   *
-   * @param aLogger
-   * @return <code>false</code> if aborted,<code>true</code> if not
-   * @throws ProducerFailure
-   * @throws ProducerExc
+   * Execute the producer
+   */
+  public boolean execute(ProductionContext aContext) throws ProducerFailure, ProducerExc;
+
+  /**
+   * Abort the execution of the producer. Will be called from a different
+   * thread and implementations should take this into account.
    */
-  public boolean produce( LoggerWrapper aLogger ) throws ProducerFailure, ProducerExc;
-  public void abort();
+  public void abort(ProductionContext aContext);
 }