| | 370 | |
| | 371 | == Experiments == |
| | 372 | |
| | 373 | The experiment interface controls managing experiment definitions and realizing experimnets (allocating and initializing resources). The experimnet definition is in some flux, which is reflected in this section. |
| | 374 | |
| | 375 | === Viewing Experiments === |
| | 376 | |
| | 377 | One or more experiments can be viewed by an authorized user assuming that user has the proper permissions. The creator of a project owns it and that userid scopes its name. That is an experiment's name is a pair: (owner, name). This allows experiments to be instantiated in different projects. |
| | 378 | |
| | 379 | |
| | 380 | * '''Service:''' Experiments |
| | 381 | * '''Operation:''' viewExperiments |
| | 382 | * '''Input Parameters:''' |
| | 383 | * Userid - the user making the request |
| | 384 | * ExperimentRE - a string containing a regular expression matched against project names (may be omitted) |
| | 385 | * Owner - a string holding the owner of experiments to find (may be omitted) |
| | 386 | * Components - a 32-bit integer containing a mask of fields to include |
| | 387 | * EXPERIMENT_TOPOLOGY - include the topology |
| | 388 | * EXPERIMENT_ACTIONS - include the actions |
| | 389 | * EXPERIMENT_CONSTRAINTS - include constraints |
| | 390 | * EXPERIMENT_DATACOLLECTION - include data collection |
| | 391 | * EXPERIMENT_RESOURCES - include resources needed or allocated |
| | 392 | * EXPERIMENT_CONTAINERS - include components if realized |
| | 393 | * EXPERIMENT_LOG - include realization log and fault |
| | 394 | * EXPERIMENT_PERMISSIONS - include project permissions |
| | 395 | * TopologyFormat - an optional 32-bit int naming the topology format |
| | 396 | * TOPOLOGY_TOPDL - return a topdl file |
| | 397 | * TOPOLOGY_NS2 - return an ns2 file |
| | 398 | * TopologyFilter - an optional filter for limiting scope of the topology file format TBD |
| | 399 | * ActionFormat - an optional 32-bit int naming the action file format (values TBD) |
| | 400 | * ActionFilter - an optional filter for limiting scope of the constraint file format TBD |
| | 401 | * ConstraintFormat - an optional 32-bit int naming the constraint format (values TBD) |
| | 402 | * ConstraintFilter - an optional filter for limiting scope of the constraint file format TBD |
| | 403 | * DataCollectionFormat - an optional 32-bit int naming the data collection format (values TBD) |
| | 404 | * DataCollectionFilter - an optional filter for limiting scope of the data collection file format TBD |
| | 405 | * ResourceFilter - an optional filter for limiting scope of the resouces returned format TBD |
| | 406 | * ContainerFilter - an optional filter for limiting scope of the constainers returned format TBD |
| | 407 | |
| | 408 | * '''Return Values:''' |
| | 409 | * One or more structures with the following fields |
| | 410 | * Name - a string containing the experiment name |
| | 411 | * Owner - a string containing the owner's userid |
| | 412 | * Project - an optional string. If present the experiment is realized under this project |
| | 413 | * Topology - an optional file describing the experiment topology subject to filters and format constraints |
| | 414 | * Actions - an optional file describing the experiment actions subject to filters and format constraints |
| | 415 | * Constraints - an optional file describing the experiment constraints subject to filters and format constraints |
| | 416 | * DataCollection - an optional file describing the experiment data collection subject to filters and format constraints |
| | 417 | * Containers - an optional list with the following fields describing the containers in the experimnet, if it is realized. Subject to filtering. |
| | 418 | * Name - the container name |
| | 419 | * State - a string indicating state (Up, Down, Configured, Pinned, None) |
| | 420 | * Type - a string indicating the container type |
| | 421 | * Resources - an optional list of structures giving resources needed by or allocated to the experiment, subject to filtering. |
| | 422 | * Name - resource name |
| | 423 | * Type - resource type |
| | 424 | * State - a string, one of |
| | 425 | * "Unrealized", "Realized", "Changing", "Pinned" (Pinned means that some modification other than realization is underway) |
| | 426 | * StateDetail - a string giving additional state information. values TBD |
| | 427 | * Log - an optional file containing messages from the last realization attempt for debugging |
| | 428 | * FaultInfo - an optional structure containing the high level error message (if any) from the last realization. It contains the error fields from a DeterFault: |
| | 429 | * ErrorCode - a 32-bit integer encoding the type of error. Constants are available in the [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/api/DeterFault.html javadoc for DeterFault]. Values are: |
| | 430 | * access - access denied |
| | 431 | * request - bad request |
| | 432 | * internal - internal server error |
| | 433 | * ErrorString - a string describing the broad error |
| | 434 | * DetailString - a string describing the details that caused the error |
| | 435 | * ReadProjects - a list of project names allowed to read this experiment |
| | 436 | * WriteProjects - a list of project names allowed to modify this experiment |
| | 437 | * RealizeProjects - a list of project names allowed to realize this experiment |
| | 438 | |
| | 439 | === Creating and Deleting Experiments === |
| | 440 | |
| | 441 | An experiment is created using: |
| | 442 | |
| | 443 | * '''Service:''' Experiments |
| | 444 | * '''Operation:''' createExperiment |
| | 445 | * '''Input Parameters:''' |
| | 446 | * Userid - the user making the request (the owner on success) |
| | 447 | * Name - a string containing a new experiment's name |
| | 448 | * Topology - an optional file describing the experiment topology |
| | 449 | * Actions - an optional file describing the experiment actions |
| | 450 | * Constraints - an optional file describing the experiment constraints s |
| | 451 | * DataCollection - an optional file describing the experiment data collection |
| | 452 | * ReadProjects - a list of project names allowed to read this experiment |
| | 453 | * WriteProjects - a list of project names allowed to modify this experiment |
| | 454 | * RealizeProjects - a list of project names allowed to realize this experiment |
| | 455 | * '''Return Values:''' |
| | 456 | * None |
| | 457 | |
| | 458 | An experiment is modified using: |
| | 459 | |
| | 460 | * '''Service:''' Experiments |
| | 461 | * '''Operation:''' modifyExperiment |
| | 462 | * '''Input Parameters:''' |
| | 463 | * Userid - the user making the request (the owner on success) |
| | 464 | * Owner - the experiment owner |
| | 465 | * Name - a string containing the experiment's name |
| | 466 | * Topology - an optional file describing the experiment topology |
| | 467 | * Actions - an optional file describing the experiment actions |
| | 468 | * Constraints - an optional file describing the experiment constraints s |
| | 469 | * DataCollection - an optional file describing the experiment data collection |
| | 470 | * ReadProjects - a list of project names allowed to read this experiment |
| | 471 | * WriteProjects - a list of project names allowed to modify this experiment |
| | 472 | * RealizeProjects - a list of project names allowed to realize this experiment |
| | 473 | * '''Return Values:''' |
| | 474 | * None |
| | 475 | |
| | 476 | Omitted arguments are not overwritten. To delete a field supply an empty description. |
| | 477 | |
| | 478 | There will also be filter-based modification interfaces, but these are TBD. |
| | 479 | |
| | 480 | An experiment is deleted using: |
| | 481 | |
| | 482 | * '''Service:''' Experiments |
| | 483 | * '''Operation:''' removeExperiment |
| | 484 | * '''Input Parameters:''' |
| | 485 | * Userid - the user making the request (the owner on success) |
| | 486 | * Owner - the experiment owner |
| | 487 | * Name - a string containing the experiment to delete |
| | 488 | * '''Return Values:''' |
| | 489 | * None |
| | 490 | |
| | 491 | After {{{removeExperiment}}} succeeds, experiment state is removed from the testbed completely. |
| | 492 | |
| | 493 | === Realizing and Releasing Experiments === |
| | 494 | |
| | 495 | To realize an experiment use: |
| | 496 | |
| | 497 | * '''Service:''' Experiments |
| | 498 | * '''Operation:''' realizeExperiment |
| | 499 | * '''Input Parameters:''' |
| | 500 | * Userid - the user making the request (the owner on success) |
| | 501 | * Owner - the experiment owner |
| | 502 | * Name - a string containing the experiment to realize |
| | 503 | * Notify - a flag, if true send the user a notification when realization is complete |
| | 504 | * '''Return Values:''' |
| | 505 | * None |
| | 506 | |
| | 507 | The user can either poll the experiment using {{{viewExperiments}}} and examining the {{{StateDetail}}} field or poll for a notification that the realization is complete. |
| | 508 | |
| | 509 | If the realization fails - as indicated by the {{{State}}} variable in a {{{viewExperiments}}} response, the {{{Log}}} and {{{FaultInfo}}} fields characterize the error. |
| | 510 | |
| | 511 | To release an experiment's resources: |
| | 512 | |
| | 513 | * '''Service:''' Experiments |
| | 514 | * '''Operation:''' releaseExperiment |
| | 515 | * '''Input Parameters:''' |
| | 516 | * Userid - the user making the request (the owner on success) |
| | 517 | * Owner - the experiment owner |
| | 518 | * Name - a string containing the experiment to release |
| | 519 | * Notify - a flag, if true send the user a notification when realization is complete |
| | 520 | * '''Return Values:''' |
| | 521 | * None |
| | 522 | |
| | 523 | After {{{releaseExperiment}}} succeeds, experiment state remains in the testbed, but containers are stopped and resources are returned to the testbed. |
