1: <?php
  2: 
  3: namespace Guzzle\Service;
  4: 
  5: use Guzzle\Common\FromConfigInterface;
  6: use Guzzle\Common\Exception\InvalidArgumentException;
  7: use Guzzle\Inflection\InflectorInterface;
  8: use Guzzle\Http\ClientInterface as HttpClientInterface;
  9: use Guzzle\Service\Exception\CommandTransferException;
 10: use Guzzle\Service\Command\CommandInterface;
 11: use Guzzle\Service\Description\ServiceDescriptionInterface;
 12: use Guzzle\Service\Command\Factory\FactoryInterface as CommandFactoryInterface;
 13: use Guzzle\Service\Resource\ResourceIteratorInterface;
 14: use Guzzle\Service\Resource\ResourceIteratorFactoryInterface;
 15: 
 16: /**
 17:  * Client interface for executing commands on a web service.
 18:  */
 19: interface ClientInterface extends HttpClientInterface, FromConfigInterface
 20: {
 21:     /**
 22:      * Get a command by name. First, the client will see if it has a service description and if the service description
 23:      * defines a command by the supplied name. If no dynamic command is found, the client will look for a concrete
 24:      * command class exists matching the name supplied. If neither are found, an InvalidArgumentException is thrown.
 25:      *
 26:      * @param string $name Name of the command to retrieve
 27:      * @param array  $args Arguments to pass to the command
 28:      *
 29:      * @return CommandInterface
 30:      * @throws InvalidArgumentException if no command can be found by name
 31:      */
 32:     public function getCommand($name, array $args = array());
 33: 
 34:     /**
 35:      * Execute one or more commands
 36:      *
 37:      * @param CommandInterface|array $command Command or array of commands to execute
 38:      *
 39:      * @return mixed Returns the result of the executed command or an array of commands if executing multiple commands
 40:      * @throws InvalidArgumentException if an invalid command is passed
 41:      * @throws CommandTransferException if an exception is encountered when transferring multiple commands
 42:      */
 43:     public function execute($command);
 44: 
 45:     /**
 46:      * Set the service description of the client
 47:      *
 48:      * @param ServiceDescriptionInterface $service Service description
 49:      *
 50:      * @return ClientInterface
 51:      */
 52:     public function setDescription(ServiceDescriptionInterface $service);
 53: 
 54:     /**
 55:      * Get the service description of the client
 56:      *
 57:      * @return ServiceDescriptionInterface|null
 58:      */
 59:     public function getDescription();
 60: 
 61:     /**
 62:      * Set the command factory used to create commands by name
 63:      *
 64:      * @param CommandFactoryInterface $factory Command factory
 65:      *
 66:      * @return ClientInterface
 67:      */
 68:     public function setCommandFactory(CommandFactoryInterface $factory);
 69: 
 70:     /**
 71:      * Get a resource iterator from the client.
 72:      *
 73:      * @param string|CommandInterface $command         Command class or command name.
 74:      * @param array                   $commandOptions  Command options used when creating commands.
 75:      * @param array                   $iteratorOptions Iterator options passed to the iterator when it is instantiated.
 76:      *
 77:      * @return ResourceIteratorInterface
 78:      */
 79:     public function getIterator($command, array $commandOptions = null, array $iteratorOptions = array());
 80: 
 81:     /**
 82:      * Set the resource iterator factory associated with the client
 83:      *
 84:      * @param ResourceIteratorFactoryInterface $factory Resource iterator factory
 85:      *
 86:      * @return ClientInterface
 87:      */
 88:     public function setResourceIteratorFactory(ResourceIteratorFactoryInterface $factory);
 89: 
 90:     /**
 91:      * Set the inflector used with the client
 92:      *
 93:      * @param InflectorInterface $inflector Inflection object
 94:      *
 95:      * @return ClientInterface
 96:      */
 97:     public function setInflector(InflectorInterface $inflector);
 98: 
 99:     /**
100:      * Get the inflector used with the client
101:      *
102:      * @return InflectorInterface
103:      */
104:     public function getInflector();
105: }
106: