[Sommaire] [Imprimer]

   1  <?php
   2  /*
   3   *  $Id: Task.php 3076 2006-12-18 08:52:12Z fabien $
   4   *
   5   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   6   * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   7   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   8   * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
   9   * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  10   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  11   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  12   * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  13   * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  14   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  15   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  16   *
  17   * This software consists of voluntary contributions made by many individuals
  18   * and is licensed under the LGPL. For more information please see
  19   * <http://phing.info>.
  20   */
  21  
  22  require_once 'phing/ProjectComponent.php';
  23  include_once 'phing/RuntimeConfigurable.php';
  24  
  25  /**
  26   * The base class for all Tasks.
  27   *
  28   * Use {@link Project#createTask} to register a new Task.
  29   *
  30   * @author    Andreas Aderhold <andi@binarycloud.com>
  31   * @copyright © 2001,2002 THYRELL. All rights reserved
  32   * @version   $Revision: 1.11 $
  33   * @see       Project#createTask()
  34   * @package   phing
  35   */
  36  abstract class Task extends ProjectComponent {
  37  
  38      /** owning Target object */
  39      protected $target;
  40      
  41      /** description of the task */
  42      protected $description;
  43      
  44      /** internal taskname (req) */
  45      protected $taskType;
  46      
  47      /** taskname for logger */
  48      protected $taskName;
  49      
  50      /** stored buildfile location */
  51      protected $location;
  52      
  53      /** wrapper of the task */
  54      protected $wrapper;
  55  
  56      /**
  57       * Sets the owning target this task belongs to.
  58       *
  59       * @param   object  Reference to owning target
  60       * @access  public
  61       */
  62      function setOwningTarget(Target $target) {
  63          $this->target = $target;
  64      }
  65  
  66      /**
  67       *  Returns the owning target of this task.
  68       *
  69       *  @return  object    The target object that owns this task
  70       *  @access  public
  71       */
  72      function getOwningTarget() {
  73          return $this->target;
  74      }
  75  
  76      /**
  77       *  Returns the name of task, used only for log messages
  78       *
  79       *  @return  string  Name of this task
  80       *  @access  public
  81       */
  82      function getTaskName() {
  83          if ($this->taskName === null) {
  84              // if no task name is set, then it's possible
  85              // this task was created from within another task.  We don't
  86              // therefore know the XML tag name for this task, so we'll just
  87              // use the class name stripped of "task" suffix.  This is only
  88              // for log messages, so we don't have to worry much about accuracy.
  89              return preg_replace('/task$/i', '', get_class($this));
  90          }
  91          return $this->taskName;
  92      }
  93  
  94      /**
  95       *  Sets the name of this task for log messages
  96       *
  97       *  @return  string  A string representing the name of this task for log
  98       *  @access  public
  99       */
 100      function setTaskName($name) {
 101          $this->taskName = (string) $name;
 102      }
 103  
 104      /**
 105       *  Returns the name of the task under which it was invoked,
 106       *  usually the XML tagname
 107       *
 108       *  @return string The type of this task (XML Tag)
 109       */
 110      function getTaskType() {
 111          return $this->taskType;
 112      }
 113  
 114      /**
 115       *  Sets the type of the task. Usually this is the name of the XML tag
 116       *
 117       *  @param string The type of this task (XML Tag)
 118       */
 119      function setTaskType($name) {
 120          $this->taskType = (string) $name;
 121      }
 122      
 123      /**
 124       * Returns a name 
 125       * 
 126       */
 127  	protected function getRegisterSlot($slotName) {
 128          return Register::getSlot('task.' . $this->getTaskName() . '.' . $slotName);
 129      }
 130      
 131      /**
 132       *  Provides a project level log event to the task.
 133       *
 134       *  @param string  The message to log
 135       *  @param integer The priority of the message
 136       *  @see BuildEvent
 137       *  @see BuildListener
 138       */
 139      function log($msg, $level = PROJECT_MSG_INFO) {
 140          $this->project->logObject($this, $msg, $level);
 141      }
 142  
 143      /**
 144       *  Sets a textual description of the task
 145       *
 146       *  @param    string    The text describing the task
 147       */
 148      public function setDescription($desc) {
 149          $this->description = $desc;
 150      }
 151  
 152      /**
 153       *  Returns the textual description of the task
 154       *
 155       *  @return  string  The text description of the task
 156       */
 157      public function getDescription() {
 158          return $this->description;
 159      }
 160  
 161      /**
 162       *  Called by the parser to let the task initialize properly.
 163       *  Should throw a BuildException if something goes wrong with the build
 164       *
 165       *  This is abstract here, but may not be overloaded by subclasses.
 166       *
 167       * @throws BuildException
 168       */
 169      public function init() {
 170      }
 171  
 172      /**
 173       *  Called by the project to let the task do it's work. This method may be
 174       *  called more than once, if the task is invoked more than once. For
 175       *  example, if target1 and target2 both depend on target3, then running
 176       *  <em>phing target1 target2</em> will run all tasks in target3 twice.
 177       *
 178       *  Should throw a BuildException if someting goes wrong with the build
 179       *
 180       *  This is abstract here. Must be overloaded by real tasks.
 181       *
 182       *  @access  public
 183       */
 184      abstract function main();
 185  
 186      /**
 187       *  Returns the location within the buildfile this task occurs. Used
 188       *  by {@link BuildException} to give detailed error messages.
 189       *
 190       *  @return Location The location object describing the position of this
 191       *                   task within the buildfile.
 192       */
 193      function getLocation() {
 194          return $this->location;
 195      }
 196  
 197      /**
 198       *  Sets the location within the buildfile this task occurs. Called by
 199       *  the parser to set location information.
 200       *
 201       *  @return  object  The location object describing the position of this
 202       *                   task within the buildfile.
 203       *  @access  public
 204       */
 205      function setLocation(Location $location) {
 206          $this->location = $location;
 207      }
 208  
 209      /**
 210       *  Returns the wrapper object for runtime configuration
 211       *
 212       *  @return  object  The wrapper object used by this task
 213       *  @access  public
 214       */
 215      function getRuntimeConfigurableWrapper() {
 216          if ($this->wrapper === null) {
 217              $this->wrapper = new RuntimeConfigurable($this, $this->getTaskName());
 218          }
 219          return $this->wrapper;
 220      }
 221  
 222      /**
 223       *  Sets the wrapper object this task should use for runtime
 224       *  configurable elements.
 225       *
 226       *  @param   object  The wrapper object this task should use
 227       *  @access  public
 228       */
 229      function setRuntimeConfigurableWrapper(RuntimeConfigurable $wrapper) {
 230          $this->wrapper = $wrapper;
 231      }
 232  
 233      /**
 234       *  Configure this task if it hasn't been done already.
 235       *
 236       *  @access  public
 237       */
 238      function maybeConfigure() {
 239          if ($this->wrapper !== null) {
 240              $this->wrapper->maybeConfigure($this->project);
 241          }
 242      }
 243  
 244      /**
 245       *  Perfrom this task
 246       *
 247       *  @access  public
 248       */
 249      function perform() {
 250  
 251          try { // try executing task
 252              $this->project->fireTaskStarted($this);
 253              $this->maybeConfigure();
 254              $this->main();
 255              $this->project->fireTaskFinished($this, $null=null);
 256          } catch (Exception $exc) {
 257              if ($exc instanceof BuildException) {
 258                  if ($exc->getLocation() === null) {
 259                      $exc->setLocation($this->getLocation());
 260                  }
 261              }
 262              $this->project->fireTaskFinished($this, $exc);
 263              throw $exc;
 264          }
 265      }
 266  }