1. <?php
  2. /**
  3.  * File containing the ezcWorkflow class.
  4.  *
  5.  * @package Workflow
  6.  * @version 1.2
  7.  * @copyright Copyright (C) 2005-2008 eZ systems as. All rights reserved.
  8.  * @license http://ez.no/licenses/new_bsd New BSD License
  9.  */
 10.  
 11. /**
 12.  * Class representing a workflow.
 13.  *
 14.  * @property ezcWorkflowDefinitonStorage $definitionStorage 
 15.  *            The definition handler used to fetch sub workflows on demand.
 16.  *            This property is set automatically if you load a workflow using
 17.  *            a workflow definition storage.
 18.  * @property int                         $id 
 19.  *            Unique ID set automatically by the definition handler when the
 20.  *            workflow is stored.
 21.  * @property string                      $name 
 22.  *            A unique name (accross the system) for this workflow.
 23.  * @property int                         $version 
 24.  *            The version of the workflow. This must be incremented manually
 25.  *            whenever you want a new version.
 26.  * @property-read ezcWorkflowNodeStart   $startNode The unique start node of the workflow.
 27.  * @property-read ezcWorkflowNodeEnd     $endNode The default end node of the workflow.
 28.  * @property-read ezcWorkflowNodeFinally $finallyNode The start of a node
 29.  *                                        sequence that is executed when a
 30.  *                                        workflow execution is cancelled.
 31.  * @property-read array(ezcWorkflowNode) $nodes All the nodes of this workflow.
 32.  *
 33.  * @package Workflow
 34.  * @version 1.2
 35.  * @mainclass
 36.  */
 37. class ezcWorkflow implements ezcWorkflowVisitable
 38. {
 39.     /**
 40.      * Container to hold the properties
 41.      *
 42.      * @var array(string=>mixed) 
 43.      */
 44.     protected $properties = array(
 45.       'definitionStorage' => null,
 46.       'id'                => false,
 47.       'name'              => '',
 48.       'startNode'         => null,
 49.       'endNode'           => null,
 50.       'finallyNode'       => null,
 51.       'version'           => 1
 52.     );
 53.  
 54.     /**
 55.      * The variable handlers of this workflow.
 56.      *
 57.      * @var array 
 58.      */
 59.     protected $variableHandlers = array();
 60.  
 61.     /**
 62.      * Constructs a new workflow object with the name $name.
 63.      *
 64.      * Use $startNode and $endNode parameters if you don't want to use the
 65.      * default start and end nodes.
 66.      *
 67.      * $name must uniquely identify the workflow within the system.
 68.      *
 69.      * @param string                 $name        The name of the workflow.
 70.      * @param ezcWorkflowNodeStart   $startNode   The start node of the workflow.
 71.      * @param ezcWorkflowNodeEnd     $endNode     The default end node of the workflow.
 72.      * @param ezcWorkflowNodeFinally $finallyNode The start of a node sequence
 73.      *                                             that is executed when a workflow
 74.      *                                             execution is cancelled.
 75.      */
 76.     public function __construct( $name, ezcWorkflowNodeStart $startNode = null, ezcWorkflowNodeEnd $endNode = null, ezcWorkflowNodeFinally $finallyNode = null )
 77.     {
 78.         $this->name = $name;
 79.  
 80.         // Create a new ezcWorkflowNodeStart object, if necessary.
 81.         if ( $startNode === null )
 82.         {
 83.             $this->properties['startNode'] = new ezcWorkflowNodeStart;
 84.         }
 85.         else
 86.         {
 87.             $this->properties['startNode'] = $startNode;
 88.         }
 89.  
 90.         // Create a new ezcWorkflowNodeEnd object, if necessary.
 91.         if ( $endNode === null )
 92.         {
 93.             $this->properties['endNode'] = new ezcWorkflowNodeEnd;
 94.         }
 95.         else
 96.         {
 97.             $this->properties['endNode'] = $endNode;
 98.         }
 99.  
100.         // Create a new ezcWorkflowNodeFinally object, if necessary.
101.         if ( $finallyNode === null )
102.         {
103.             $this->properties['finallyNode'] = new ezcWorkflowNodeFinally;
104.         }
105.         else
106.         {
107.             $this->properties['finallyNode'] = $finallyNode;
108.         }
109.     }
110.  
111.     /**
112.      * Property read access.
113.      *
114.      * @throws ezcBasePropertyNotFoundException
115.      *          If the the desired property is not found.
116.      * 
117.      * @param string $propertyName Name of the property.
118.      * @return mixed Value of the property or null.
119.      * @ignore
120.      */
121.     public function __get( $propertyName )
122.     {
123.         switch ( $propertyName ) 
124.         {
125.             case 'definitionStorage':
126.             case 'id':
127.             case 'name':
128.             case 'startNode':
129.             case 'endNode':
130.             case 'finallyNode':
131.             case 'version':
132.                 return $this->properties[$propertyName];
133.  
134.             case 'nodes':
135.                 $visitor = new ezcWorkflowVisitorNodeCollector( $this );
136.  
137.                 return $visitor->getNodes();
138.         }
139.  
140.         throw new ezcBasePropertyNotFoundException( $propertyName );
141.     }
142.  
143.     /**
144.      * Property write access.
145.      * 
146.      * @param string $propertyName Name of the property.
147.      * @param mixed $val  The value for the property.
148.      *
149.      * @throws ezcBaseValueException
150.      *          If the value for the property definitionStorage is not an
151.      *          instance of ezcWorkflowDefinitionStorage.
152.      * @throws ezcBaseValueException
153.      *          If the value for the property id is not an integer.
154.      * @throws ezcBaseValueException
155.      *          If the value for the property name is not a string.
156.      * @throws ezcBasePropertyPermissionException
157.      *          If there is a write access to startNode.
158.      * @throws ezcBasePropertyPermissionException
159.      *          If there is a write access to endNode.
160.      * @throws ezcBasePropertyPermissionException
161.      *          If there is a write access to finallyNode.
162.      * @throws ezcBasePropertyPermissionException
163.      *          If there is a write access to nodes.
164.      * @throws ezcBaseValueException
165.      *          If the value for the property version is not an integer.
166.      * @ignore
167.      */
168.     public function __set( $propertyName, $val )
169.     {
170.         switch ( $propertyName ) 
171.         {
172.             case 'definitionStorage':
173.                 if ( !( $val instanceof ezcWorkflowDefinitionStorage ) )
174.                 {
175.                     throw new ezcBaseValueException( $propertyName, $val, 'ezcWorkflowDefinitionStorage' );
176.                 }
177.  
178.                 $this->properties['definitionStorage'] = $val;
179.  
180.                 return;
181.  
182.             case 'id':
183.                 if ( !( is_int( $val ) ) )
184.                 {
185.                     throw new ezcBaseValueException( $propertyName, $val, 'integer' );
186.                 }
187.  
188.                 $this->properties['id'] = $val;
189.  
190.                 return;
191.  
192.             case 'name':
193.                 if ( !( is_string( $val ) ) )
194.                 {
195.                     throw new ezcBaseValueException( $propertyName, $val, 'string' );
196.                 }
197.  
198.                 $this->properties['name'] = $val;
199.  
200.                 return;
201.  
202.             case 'startNode':
203.             case 'endNode':
204.             case 'finallyNode':
205.             case 'nodes':
206.                 throw new ezcBasePropertyPermissionException(
207.                   $propertyName, ezcBasePropertyPermissionException::READ
208.                 );
209.  
210.             case 'version':
211.                 if ( !( is_int( $val ) ) )
212.                 {
213.                     throw new ezcBaseValueException( $propertyName, $val, 'integer' );
214.                 }
215.  
216.                 $this->properties['version'] = $val;
217.  
218.                 return;
219.         }
220.  
221.         throw new ezcBasePropertyNotFoundException( $propertyName );
222.     }
223.  
224.     /**
225.      * Property isset access.
226.      * 
227.      * @param string $propertyName Name of the property.
228.      * @return bool True is the property is set, otherwise false.
229.      * @ignore
230.      */
231.     public function __isset( $propertyName )
232.     {
233.         switch ( $propertyName )
234.         {
235.             case 'definitionStorage':
236.             case 'id':
237.             case 'name':
238.             case 'startNode':
239.             case 'endNode':
240.             case 'finallyNode':
241.             case 'nodes':
242.             case 'version':
243.                 return true;
244.         }
245.  
246.         return false;
247.     }
248.  
249.     /**
250.      * Returns true when the workflow requires user interaction
251.      * (ie. when it contains ezcWorkflowNodeInput nodes)
252.      * and false otherwise.
253.      *
254.      * @return boolean true when the workflow is interactive, false otherwise.
255.      */
256.     public function isInteractive()
257.     {
258.         foreach ( $this->nodes as $node )
259.         {
260.             if ( $node instanceof ezcWorkflowNodeInput )
261.             {
262.                 return true;
263.             }
264.         }
265.  
266.         return false;
267.     }
268.  
269.     /**
270.      * Returns true when the workflow has sub workflows
271.      * (ie. when it contains ezcWorkflowNodeSubWorkflow nodes)
272.      * and false otherwise.
273.      *
274.      * @return boolean true when the workflow has sub workflows, false otherwise.
275.      */
276.     public function hasSubWorkflows()
277.     {
278.         foreach ( $this->nodes as $node )
279.         {
280.             if ( $node instanceof ezcWorkflowNodeSubWorkflow )
281.             {
282.                 return true;
283.             }
284.         }
285.  
286.         return false;
287.     }
288.  
289.     /**
290.      * Verifies the specification of this workflow.
291.      *
292.      * See the documentation of ezcWorkflowVisitorVerification for
293.      * details.
294.      *
295.      * @throws ezcWorkflowInvalidWorkflowException if the specification of this workflow is not correct.
296.      */
297.     public function verify()
298.     {
299.         $this->accept( new ezcWorkflowVisitorVerification );
300.     }
301.  
302.     /**
303.      * Overridden implementation of accept() calls
304.      * accept on the start node.
305.      *
306.      * @param ezcWorkflowVisitor $visitor 
307.      */
308.     public function accept( ezcWorkflowVisitor $visitor )
309.     {
310.         $visitor->visit( $this );
311.         $this->properties['startNode']->accept( $visitor );
312.     }
313.  
314.     /**
315.      * Sets the class $className to handle the variable named $variableName.
316.      *
317.      * $className must be the name of a class implementing the
318.      * ezcWorkflowVariableHandler interface.
319.      *
320.      * @param string $variableName 
321.      * @param string $className 
322.      * @throws ezcWorkflowInvalidWorkflowException if $className does not contain the name of a valid class implementing ezcWorkflowVariableHandler
323.      */
324.     public function addVariableHandler( $variableName, $className )
325.     {
326.         if ( class_exists( $className ) )
327.         {
328.             $class = new ReflectionClass( $className );
329.  
330.             if ( $class->implementsInterface( 'ezcWorkflowVariableHandler' ) )
331.             {
332.                 $this->variableHandlers[$variableName] = $className;
333.             }
334.             else
335.             {
336.                 throw new ezcWorkflowInvalidWorkflowException(
337.                   'Class does not implement the ezcWorkflowVariableHandler interface.'
338.                 );
339.             }
340.         }
341.         else
342.         {
343.             throw new ezcWorkflowInvalidWorkflowException(
344.                 'Class not found.'
345.             );
346.         }
347.     }
348.  
349.     /**
350.      * Removes the handler for $variableName and returns true
351.      * on success.
352.      *
353.      * Returns false if no handler was set for $variableName.
354.      *
355.      * @param string $variableName 
356.      * @return boolean 
357.      */
358.     public function removeVariableHandler( $variableName )
359.     {
360.         if ( isset( $this->variableHandlers[$variableName] ) )
361.         {
362.             unset( $this->variableHandlers[$variableName] );
363.             return true;
364.         }
365.  
366.         return false;
367.     }
368.  
369.     /**
370.      * Sets handlers for multiple variables.
371.      *
372.      * The format of $variableHandlers is
373.      * array( 'variableName' => ezcWorkflowVariableHandler )
374.      *
375.      * @throws ezcWorkflowInvalidWorkflowException if $className does not contain the name of a valid class implementing ezcWorkflowVariableHandler
376.      * @param array $variableHandlers 
377.      */
378.     public function setVariableHandlers( array $variableHandlers )
379.     {
380.         $this->variableHandlers = array();
381.  
382.         foreach ( $variableHandlers as $variableName => $className )
383.         {
384.             $this->addVariableHandler( $variableName, $className );
385.         }
386.     }
387.  
388.     /**
389.      * Returns the variable handlers.
390.      *
391.      * The format of the returned array is
392.      * array( 'variableName' => ezcWorkflowVariableHandler )
393.      *
394.      * @return array 
395.      */
396.     public function getVariableHandlers()
397.     {
398.         return $this->variableHandlers;
399.     }
400. }
401. ?>