ErrorParser
11 months ago
Parser
11 months ago
Serializer
11 months ago
AbstractModel.php
11 months ago
ApiProvider.php
11 months ago
DateTimeResult.php
11 months ago
DocModel.php
11 months ago
ListShape.php
11 months ago
MapShape.php
11 months ago
Operation.php
11 months ago
Service.php
11 months ago
Shape.php
11 months ago
ShapeMap.php
11 months ago
StructureShape.php
11 months ago
TimestampShape.php
11 months ago
Validator.php
11 months ago
Service.php
536 lines
| 1 | <?php |
| 2 | namespace Aws\Api; |
| 3 | |
| 4 | /** |
| 5 | * Represents a web service API model. |
| 6 | */ |
| 7 | class Service extends AbstractModel |
| 8 | { |
| 9 | /** @var callable */ |
| 10 | private $apiProvider; |
| 11 | |
| 12 | /** @var string */ |
| 13 | private $serviceName; |
| 14 | |
| 15 | /** @var string */ |
| 16 | private $apiVersion; |
| 17 | |
| 18 | /** @var array */ |
| 19 | private $clientContextParams = []; |
| 20 | |
| 21 | /** @var Operation[] */ |
| 22 | private $operations = []; |
| 23 | |
| 24 | /** @var array */ |
| 25 | private $paginators = null; |
| 26 | |
| 27 | /** @var array */ |
| 28 | private $waiters = null; |
| 29 | |
| 30 | /** @var boolean */ |
| 31 | private $modifiedModel = false; |
| 32 | |
| 33 | /** |
| 34 | * @param array $definition |
| 35 | * @param callable $provider |
| 36 | * |
| 37 | * @internal param array $definition Service description |
| 38 | */ |
| 39 | public function __construct(array $definition, callable $provider) |
| 40 | { |
| 41 | static $defaults = [ |
| 42 | 'operations' => [], |
| 43 | 'shapes' => [], |
| 44 | 'metadata' => [], |
| 45 | 'clientContextParams' => [] |
| 46 | ], $defaultMeta = [ |
| 47 | 'apiVersion' => null, |
| 48 | 'serviceFullName' => null, |
| 49 | 'serviceId' => null, |
| 50 | 'endpointPrefix' => null, |
| 51 | 'signingName' => null, |
| 52 | 'signatureVersion' => null, |
| 53 | 'protocol' => null, |
| 54 | 'uid' => null |
| 55 | ]; |
| 56 | |
| 57 | $definition += $defaults; |
| 58 | $definition['metadata'] += $defaultMeta; |
| 59 | $this->definition = $definition; |
| 60 | $this->apiProvider = $provider; |
| 61 | parent::__construct($definition, new ShapeMap($definition['shapes'])); |
| 62 | |
| 63 | if (isset($definition['metadata']['serviceIdentifier'])) { |
| 64 | $this->serviceName = $this->getServiceName(); |
| 65 | } else { |
| 66 | $this->serviceName = $this->getEndpointPrefix(); |
| 67 | } |
| 68 | $this->apiVersion = $this->getApiVersion(); |
| 69 | if (isset($definition['clientContextParams'])) { |
| 70 | $this->clientContextParams = $definition['clientContextParams']; |
| 71 | } |
| 72 | } |
| 73 | |
| 74 | /** |
| 75 | * Creates a request serializer for the provided API object. |
| 76 | * |
| 77 | * @param Service $api API that contains a protocol. |
| 78 | * @param string $endpoint Endpoint to send requests to. |
| 79 | * |
| 80 | * @return callable |
| 81 | * @throws \UnexpectedValueException |
| 82 | */ |
| 83 | public static function createSerializer(Service $api, $endpoint) |
| 84 | { |
| 85 | static $mapping = [ |
| 86 | 'json' => Serializer\JsonRpcSerializer::class, |
| 87 | 'query' => Serializer\QuerySerializer::class, |
| 88 | 'rest-json' => Serializer\RestJsonSerializer::class, |
| 89 | 'rest-xml' => Serializer\RestXmlSerializer::class |
| 90 | ]; |
| 91 | |
| 92 | $proto = $api->getProtocol(); |
| 93 | |
| 94 | if (isset($mapping[$proto])) { |
| 95 | return new $mapping[$proto]($api, $endpoint); |
| 96 | } |
| 97 | |
| 98 | if ($proto == 'ec2') { |
| 99 | return new Serializer\QuerySerializer($api, $endpoint, new Serializer\Ec2ParamBuilder()); |
| 100 | } |
| 101 | |
| 102 | throw new \UnexpectedValueException( |
| 103 | 'Unknown protocol: ' . $api->getProtocol() |
| 104 | ); |
| 105 | } |
| 106 | |
| 107 | /** |
| 108 | * Creates an error parser for the given protocol. |
| 109 | * |
| 110 | * Redundant method signature to preserve backwards compatibility. |
| 111 | * |
| 112 | * @param string $protocol Protocol to parse (e.g., query, json, etc.) |
| 113 | * |
| 114 | * @return callable |
| 115 | * @throws \UnexpectedValueException |
| 116 | */ |
| 117 | public static function createErrorParser($protocol, Service $api = null) |
| 118 | { |
| 119 | static $mapping = [ |
| 120 | 'json' => ErrorParser\JsonRpcErrorParser::class, |
| 121 | 'query' => ErrorParser\XmlErrorParser::class, |
| 122 | 'rest-json' => ErrorParser\RestJsonErrorParser::class, |
| 123 | 'rest-xml' => ErrorParser\XmlErrorParser::class, |
| 124 | 'ec2' => ErrorParser\XmlErrorParser::class |
| 125 | ]; |
| 126 | |
| 127 | if (isset($mapping[$protocol])) { |
| 128 | return new $mapping[$protocol]($api); |
| 129 | } |
| 130 | |
| 131 | throw new \UnexpectedValueException("Unknown protocol: $protocol"); |
| 132 | } |
| 133 | |
| 134 | /** |
| 135 | * Applies the listeners needed to parse client models. |
| 136 | * |
| 137 | * @param Service $api API to create a parser for |
| 138 | * @return callable |
| 139 | * @throws \UnexpectedValueException |
| 140 | */ |
| 141 | public static function createParser(Service $api) |
| 142 | { |
| 143 | static $mapping = [ |
| 144 | 'json' => Parser\JsonRpcParser::class, |
| 145 | 'query' => Parser\QueryParser::class, |
| 146 | 'rest-json' => Parser\RestJsonParser::class, |
| 147 | 'rest-xml' => Parser\RestXmlParser::class |
| 148 | ]; |
| 149 | |
| 150 | $proto = $api->getProtocol(); |
| 151 | if (isset($mapping[$proto])) { |
| 152 | return new $mapping[$proto]($api); |
| 153 | } |
| 154 | |
| 155 | if ($proto == 'ec2') { |
| 156 | return new Parser\QueryParser($api, null, false); |
| 157 | } |
| 158 | |
| 159 | throw new \UnexpectedValueException( |
| 160 | 'Unknown protocol: ' . $api->getProtocol() |
| 161 | ); |
| 162 | } |
| 163 | |
| 164 | /** |
| 165 | * Get the full name of the service |
| 166 | * |
| 167 | * @return string |
| 168 | */ |
| 169 | public function getServiceFullName() |
| 170 | { |
| 171 | return $this->definition['metadata']['serviceFullName']; |
| 172 | } |
| 173 | |
| 174 | /** |
| 175 | * Get the service id |
| 176 | * |
| 177 | * @return string |
| 178 | */ |
| 179 | public function getServiceId() |
| 180 | { |
| 181 | return $this->definition['metadata']['serviceId']; |
| 182 | } |
| 183 | |
| 184 | /** |
| 185 | * Get the API version of the service |
| 186 | * |
| 187 | * @return string |
| 188 | */ |
| 189 | public function getApiVersion() |
| 190 | { |
| 191 | return $this->definition['metadata']['apiVersion']; |
| 192 | } |
| 193 | |
| 194 | /** |
| 195 | * Get the API version of the service |
| 196 | * |
| 197 | * @return string |
| 198 | */ |
| 199 | public function getEndpointPrefix() |
| 200 | { |
| 201 | return $this->definition['metadata']['endpointPrefix']; |
| 202 | } |
| 203 | |
| 204 | /** |
| 205 | * Get the signing name used by the service. |
| 206 | * |
| 207 | * @return string |
| 208 | */ |
| 209 | public function getSigningName() |
| 210 | { |
| 211 | return $this->definition['metadata']['signingName'] |
| 212 | ?: $this->definition['metadata']['endpointPrefix']; |
| 213 | } |
| 214 | |
| 215 | /** |
| 216 | * Get the service name. |
| 217 | * |
| 218 | * @return string |
| 219 | */ |
| 220 | public function getServiceName() |
| 221 | { |
| 222 | return $this->definition['metadata']['serviceIdentifier']; |
| 223 | } |
| 224 | |
| 225 | /** |
| 226 | * Get the default signature version of the service. |
| 227 | * |
| 228 | * Note: this method assumes "v4" when not specified in the model. |
| 229 | * |
| 230 | * @return string |
| 231 | */ |
| 232 | public function getSignatureVersion() |
| 233 | { |
| 234 | return $this->definition['metadata']['signatureVersion'] ?: 'v4'; |
| 235 | } |
| 236 | |
| 237 | /** |
| 238 | * Get the protocol used by the service. |
| 239 | * |
| 240 | * @return string |
| 241 | */ |
| 242 | public function getProtocol() |
| 243 | { |
| 244 | return $this->definition['metadata']['protocol']; |
| 245 | } |
| 246 | |
| 247 | /** |
| 248 | * Get the uid string used by the service |
| 249 | * |
| 250 | * @return string |
| 251 | */ |
| 252 | public function getUid() |
| 253 | { |
| 254 | return $this->definition['metadata']['uid']; |
| 255 | } |
| 256 | |
| 257 | /** |
| 258 | * Check if the description has a specific operation by name. |
| 259 | * |
| 260 | * @param string $name Operation to check by name |
| 261 | * |
| 262 | * @return bool |
| 263 | */ |
| 264 | public function hasOperation($name) |
| 265 | { |
| 266 | return isset($this['operations'][$name]); |
| 267 | } |
| 268 | |
| 269 | /** |
| 270 | * Get an operation by name. |
| 271 | * |
| 272 | * @param string $name Operation to retrieve by name |
| 273 | * |
| 274 | * @return Operation |
| 275 | * @throws \InvalidArgumentException If the operation is not found |
| 276 | */ |
| 277 | public function getOperation($name) |
| 278 | { |
| 279 | if (!isset($this->operations[$name])) { |
| 280 | if (!isset($this->definition['operations'][$name])) { |
| 281 | throw new \InvalidArgumentException("Unknown operation: $name"); |
| 282 | } |
| 283 | $this->operations[$name] = new Operation( |
| 284 | $this->definition['operations'][$name], |
| 285 | $this->shapeMap |
| 286 | ); |
| 287 | } else if ($this->modifiedModel) { |
| 288 | $this->operations[$name] = new Operation( |
| 289 | $this->definition['operations'][$name], |
| 290 | $this->shapeMap |
| 291 | ); |
| 292 | } |
| 293 | |
| 294 | return $this->operations[$name]; |
| 295 | } |
| 296 | |
| 297 | /** |
| 298 | * Get all of the operations of the description. |
| 299 | * |
| 300 | * @return Operation[] |
| 301 | */ |
| 302 | public function getOperations() |
| 303 | { |
| 304 | $result = []; |
| 305 | foreach ($this->definition['operations'] as $name => $definition) { |
| 306 | $result[$name] = $this->getOperation($name); |
| 307 | } |
| 308 | |
| 309 | return $result; |
| 310 | } |
| 311 | |
| 312 | /** |
| 313 | * Get all of the error shapes of the service |
| 314 | * |
| 315 | * @return array |
| 316 | */ |
| 317 | public function getErrorShapes() |
| 318 | { |
| 319 | $result = []; |
| 320 | foreach ($this->definition['shapes'] as $name => $definition) { |
| 321 | if (!empty($definition['exception'])) { |
| 322 | $definition['name'] = $name; |
| 323 | $result[] = new StructureShape($definition, $this->getShapeMap()); |
| 324 | } |
| 325 | } |
| 326 | |
| 327 | return $result; |
| 328 | } |
| 329 | |
| 330 | /** |
| 331 | * Get all of the service metadata or a specific metadata key value. |
| 332 | * |
| 333 | * @param string|null $key Key to retrieve or null to retrieve all metadata |
| 334 | * |
| 335 | * @return mixed Returns the result or null if the key is not found |
| 336 | */ |
| 337 | public function getMetadata($key = null) |
| 338 | { |
| 339 | if (!$key) { |
| 340 | return $this['metadata']; |
| 341 | } |
| 342 | |
| 343 | if (isset($this->definition['metadata'][$key])) { |
| 344 | return $this->definition['metadata'][$key]; |
| 345 | } |
| 346 | |
| 347 | return null; |
| 348 | } |
| 349 | |
| 350 | /** |
| 351 | * Gets an associative array of available paginator configurations where |
| 352 | * the key is the name of the paginator, and the value is the paginator |
| 353 | * configuration. |
| 354 | * |
| 355 | * @return array |
| 356 | * @unstable The configuration format of paginators may change in the future |
| 357 | */ |
| 358 | public function getPaginators() |
| 359 | { |
| 360 | if (!isset($this->paginators)) { |
| 361 | $res = call_user_func( |
| 362 | $this->apiProvider, |
| 363 | 'paginator', |
| 364 | $this->serviceName, |
| 365 | $this->apiVersion |
| 366 | ); |
| 367 | $this->paginators = isset($res['pagination']) |
| 368 | ? $res['pagination'] |
| 369 | : []; |
| 370 | } |
| 371 | |
| 372 | return $this->paginators; |
| 373 | } |
| 374 | |
| 375 | /** |
| 376 | * Determines if the service has a paginator by name. |
| 377 | * |
| 378 | * @param string $name Name of the paginator. |
| 379 | * |
| 380 | * @return bool |
| 381 | */ |
| 382 | public function hasPaginator($name) |
| 383 | { |
| 384 | return isset($this->getPaginators()[$name]); |
| 385 | } |
| 386 | |
| 387 | /** |
| 388 | * Retrieve a paginator by name. |
| 389 | * |
| 390 | * @param string $name Paginator to retrieve by name. This argument is |
| 391 | * typically the operation name. |
| 392 | * @return array |
| 393 | * @throws \UnexpectedValueException if the paginator does not exist. |
| 394 | * @unstable The configuration format of paginators may change in the future |
| 395 | */ |
| 396 | public function getPaginatorConfig($name) |
| 397 | { |
| 398 | static $defaults = [ |
| 399 | 'input_token' => null, |
| 400 | 'output_token' => null, |
| 401 | 'limit_key' => null, |
| 402 | 'result_key' => null, |
| 403 | 'more_results' => null, |
| 404 | ]; |
| 405 | |
| 406 | if ($this->hasPaginator($name)) { |
| 407 | return $this->paginators[$name] + $defaults; |
| 408 | } |
| 409 | |
| 410 | throw new \UnexpectedValueException("There is no {$name} " |
| 411 | . "paginator defined for the {$this->serviceName} service."); |
| 412 | } |
| 413 | |
| 414 | /** |
| 415 | * Gets an associative array of available waiter configurations where the |
| 416 | * key is the name of the waiter, and the value is the waiter |
| 417 | * configuration. |
| 418 | * |
| 419 | * @return array |
| 420 | */ |
| 421 | public function getWaiters() |
| 422 | { |
| 423 | if (!isset($this->waiters)) { |
| 424 | $res = call_user_func( |
| 425 | $this->apiProvider, |
| 426 | 'waiter', |
| 427 | $this->serviceName, |
| 428 | $this->apiVersion |
| 429 | ); |
| 430 | $this->waiters = isset($res['waiters']) |
| 431 | ? $res['waiters'] |
| 432 | : []; |
| 433 | } |
| 434 | |
| 435 | return $this->waiters; |
| 436 | } |
| 437 | |
| 438 | /** |
| 439 | * Determines if the service has a waiter by name. |
| 440 | * |
| 441 | * @param string $name Name of the waiter. |
| 442 | * |
| 443 | * @return bool |
| 444 | */ |
| 445 | public function hasWaiter($name) |
| 446 | { |
| 447 | return isset($this->getWaiters()[$name]); |
| 448 | } |
| 449 | |
| 450 | /** |
| 451 | * Get a waiter configuration by name. |
| 452 | * |
| 453 | * @param string $name Name of the waiter by name. |
| 454 | * |
| 455 | * @return array |
| 456 | * @throws \UnexpectedValueException if the waiter does not exist. |
| 457 | */ |
| 458 | public function getWaiterConfig($name) |
| 459 | { |
| 460 | // Error if the waiter is not defined |
| 461 | if ($this->hasWaiter($name)) { |
| 462 | return $this->waiters[$name]; |
| 463 | } |
| 464 | |
| 465 | throw new \UnexpectedValueException("There is no {$name} waiter " |
| 466 | . "defined for the {$this->serviceName} service."); |
| 467 | } |
| 468 | |
| 469 | /** |
| 470 | * Get the shape map used by the API. |
| 471 | * |
| 472 | * @return ShapeMap |
| 473 | */ |
| 474 | public function getShapeMap() |
| 475 | { |
| 476 | return $this->shapeMap; |
| 477 | } |
| 478 | |
| 479 | /** |
| 480 | * Get all the context params of the description. |
| 481 | * |
| 482 | * @return array |
| 483 | */ |
| 484 | public function getClientContextParams() |
| 485 | { |
| 486 | return $this->clientContextParams; |
| 487 | } |
| 488 | |
| 489 | /** |
| 490 | * Get the service's api provider. |
| 491 | * |
| 492 | * @return callable |
| 493 | */ |
| 494 | public function getProvider() |
| 495 | { |
| 496 | return $this->apiProvider; |
| 497 | } |
| 498 | |
| 499 | /** |
| 500 | * Get the service's definition. |
| 501 | * |
| 502 | * @return callable |
| 503 | */ |
| 504 | public function getDefinition() |
| 505 | { |
| 506 | return $this->definition; |
| 507 | } |
| 508 | |
| 509 | /** |
| 510 | * Sets the service's api definition. |
| 511 | * Intended for internal use only. |
| 512 | * |
| 513 | * @return void |
| 514 | * |
| 515 | * @internal |
| 516 | */ |
| 517 | public function setDefinition($definition) |
| 518 | { |
| 519 | $this->definition = $definition; |
| 520 | $this->modifiedModel = true; |
| 521 | } |
| 522 | |
| 523 | /** |
| 524 | * Denotes whether or not a service's definition has |
| 525 | * been modified. Intended for internal use only. |
| 526 | * |
| 527 | * @return bool |
| 528 | * |
| 529 | * @internal |
| 530 | */ |
| 531 | public function isModifiedModel() |
| 532 | { |
| 533 | return $this->modifiedModel; |
| 534 | } |
| 535 | } |
| 536 |