| | 1 | [[TOC]] |
| | 2 | |
| | 3 | |
| | 4 | |
| | 5 | == Experiments == |
| | 6 | |
| | 7 | (Adopted from the NewAPI, need to modify) |
| | 8 | |
| | 9 | The experiment interface controls managing experiment definitions and realizing experiments (allocating and initializing resources). The experiment definition is in some flux, which is reflected in this section. |
| | 10 | |
| | 11 | === Viewing Experiments === |
| | 12 | |
| | 13 | 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. |
| | 14 | |
| | 15 | |
| | 16 | * '''Service:''' Experiments |
| | 17 | * '''Operation:''' viewExperiments |
| | 18 | * '''Input Parameters:''' |
| | 19 | * Userid - the user making the request |
| | 20 | * ExperimentRE - a string containing a regular expression matched against project names (may be omitted) |
| | 21 | * Owner - a string holding the owner of experiments to find (may be omitted) |
| | 22 | * Components - a 32-bit integer containing a mask of fields to include |
| | 23 | * EXPERIMENT_TOPOLOGY - include the topology |
| | 24 | * EXPERIMENT_ACTIONS - include the actions |
| | 25 | * EXPERIMENT_CONSTRAINTS - include constraints |
| | 26 | * EXPERIMENT_DATACOLLECTION - include data collection |
| | 27 | * EXPERIMENT_RESOURCES - include resources needed or allocated |
| | 28 | * EXPERIMENT_CONTAINERS - include components if realized |
| | 29 | * EXPERIMENT_LOG - include realization log and fault |
| | 30 | * EXPERIMENT_PERMISSIONS - include project permissions |
| | 31 | * TopologyFormat - an optional 32-bit int naming the topology format |
| | 32 | * TOPOLOGY_TOPDL - return a topdl file |
| | 33 | * TOPOLOGY_NS2 - return an ns2 file |
| | 34 | * TopologyFilter - an optional filter for limiting scope of the topology file format TBD |
| | 35 | * ActionFormat - an optional 32-bit int naming the action file format (values TBD) |
| | 36 | * ActionFilter - an optional filter for limiting scope of the constraint file format TBD |
| | 37 | * ConstraintFormat - an optional 32-bit int naming the constraint format (values TBD) |
| | 38 | * ConstraintFilter - an optional filter for limiting scope of the constraint file format TBD |
| | 39 | * DataCollectionFormat - an optional 32-bit int naming the data collection format (values TBD) |
| | 40 | * DataCollectionFilter - an optional filter for limiting scope of the data collection file format TBD |
| | 41 | * ResourceFilter - an optional filter for limiting scope of the resouces returned format TBD |
| | 42 | * ContainerFilter - an optional filter for limiting scope of the constainers returned format TBD |
| | 43 | |
| | 44 | * '''Return Values:''' |
| | 45 | * One or more structures with the following fields |
| | 46 | * Name - a string containing the experiment name |
| | 47 | * Owner - a string containing the owner's userid |
| | 48 | * Project - an optional string. If present the experiment is realized under this project |
| | 49 | * Topology - an optional file describing the experiment topology subject to filters and format constraints |
| | 50 | * Actions - an optional file describing the experiment actions subject to filters and format constraints |
| | 51 | * Constraints - an optional file describing the experiment constraints subject to filters and format constraints |
| | 52 | * DataCollection - an optional file describing the experiment data collection subject to filters and format constraints |
| | 53 | * Containers - an optional list with the following fields describing the containers in the experimnet, if it is realized. Subject to filtering. |
| | 54 | * Name - the container name |
| | 55 | * State - a string indicating state (Up, Down, Configured, Pinned, None) |
| | 56 | * Type - a string indicating the container type |
| | 57 | * Resources - an optional list of structures giving resources needed by or allocated to the experiment, subject to filtering. |
| | 58 | * Name - resource name |
| | 59 | * Type - resource type |
| | 60 | * State - a string, one of |
| | 61 | * "Unrealized", "Realized", "Changing", "Pinned" (Pinned means that some modification other than realization is underway) |
| | 62 | * StateDetail - a string giving additional state information. values TBD |
| | 63 | * Log - an optional file containing messages from the last realization attempt for debugging |
| | 64 | * FaultInfo - an optional structure containing the high level error message (if any) from the last realization. It contains the error fields from a DeterFault: |
| | 65 | * 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: |
| | 66 | * access - access denied |
| | 67 | * request - bad request |
| | 68 | * internal - internal server error |
| | 69 | * ErrorString - a string describing the broad error |
| | 70 | * DetailString - a string describing the details that caused the error |
| | 71 | * ReadProjects - a list of project names allowed to read this experiment |
| | 72 | * WriteProjects - a list of project names allowed to modify this experiment |
| | 73 | * RealizeProjects - a list of project names allowed to realize this experiment |
| | 74 | |
| | 75 | === Creating and Deleting Experiments === |
| | 76 | |
| | 77 | An experiment is created using: |
| | 78 | |
| | 79 | * '''Service:''' Experiments |
| | 80 | * '''Operation:''' createExperiment |
| | 81 | * '''Input Parameters:''' |
| | 82 | * Userid - the user making the request (the owner on success) |
| | 83 | * Name - a string containing a new experiment's name |
| | 84 | * Topology - an optional file describing the experiment topology |
| | 85 | * Actions - an optional file describing the experiment actions |
| | 86 | * Constraints - an optional file describing the experiment constraints s |
| | 87 | * DataCollection - an optional file describing the experiment data collection |
| | 88 | * ReadProjects - a list of project names allowed to read this experiment |
| | 89 | * WriteProjects - a list of project names allowed to modify this experiment |
| | 90 | * RealizeProjects - a list of project names allowed to realize this experiment |
| | 91 | * '''Return Values:''' |
| | 92 | * None |
| | 93 | |
| | 94 | An experiment is modified using: |
| | 95 | |
| | 96 | * '''Service:''' Experiments |
| | 97 | * '''Operation:''' modifyExperiment |
| | 98 | * '''Input Parameters:''' |
| | 99 | * Userid - the user making the request (the owner on success) |
| | 100 | * Owner - the experiment owner |
| | 101 | * Name - a string containing the experiment's name |
| | 102 | * Topology - an optional file describing the experiment topology |
| | 103 | * Actions - an optional file describing the experiment actions |
| | 104 | * Constraints - an optional file describing the experiment constraints s |
| | 105 | * DataCollection - an optional file describing the experiment data collection |
| | 106 | * ReadProjects - a list of project names allowed to read this experiment |
| | 107 | * WriteProjects - a list of project names allowed to modify this experiment |
| | 108 | * RealizeProjects - a list of project names allowed to realize this experiment |
| | 109 | * '''Return Values:''' |
| | 110 | * None |
| | 111 | |
| | 112 | Omitted arguments are not overwritten. To delete a field supply an empty description. |
| | 113 | |
| | 114 | There will also be filter-based modification interfaces, but these are TBD. |
| | 115 | |
| | 116 | An experiment is deleted using: |
| | 117 | |
| | 118 | * '''Service:''' Experiments |
| | 119 | * '''Operation:''' removeExperiment |
| | 120 | * '''Input Parameters:''' |
| | 121 | * Userid - the user making the request (the owner on success) |
| | 122 | * Owner - the experiment owner |
| | 123 | * Name - a string containing the experiment to delete |
| | 124 | * '''Return Values:''' |
| | 125 | * None |
| | 126 | |
| | 127 | After {{{removeExperiment}}} succeeds, experiment state is removed from the testbed completely. |
| | 128 | |
| | 129 | === Realizing and Releasing Experiments === |
| | 130 | |
| | 131 | To realize an experiment use: |
| | 132 | |
| | 133 | * '''Service:''' Experiments |
| | 134 | * '''Operation:''' realizeExperiment |
| | 135 | * '''Input Parameters:''' |
| | 136 | * Userid - the user making the request (the owner on success) |
| | 137 | * Owner - the experiment owner |
| | 138 | * Name - a string containing the experiment to realize |
| | 139 | * Notify - a flag, if true send the user a notification when realization is complete |
| | 140 | * '''Return Values:''' |
| | 141 | * None |
| | 142 | |
| | 143 | The user can either poll the experiment using {{{viewExperiments}}} and examining the {{{StateDetail}}} field or poll for a notification that the realization is complete. |
| | 144 | |
| | 145 | If the realization fails - as indicated by the {{{State}}} variable in a {{{viewExperiments}}} response, the {{{Log}}} and {{{FaultInfo}}} fields characterize the error. |
| | 146 | |
| | 147 | To release an experiment's resources: |
| | 148 | |
| | 149 | * '''Service:''' Experiments |
| | 150 | * '''Operation:''' releaseExperiment |
| | 151 | * '''Input Parameters:''' |
| | 152 | * Userid - the user making the request (the owner on success) |
| | 153 | * Owner - the experiment owner |
| | 154 | * Name - a string containing the experiment to release |
| | 155 | * Notify - a flag, if true send the user a notification when realization is complete |
| | 156 | * '''Return Values:''' |
| | 157 | * None |
| | 158 | |
| | 159 | After {{{releaseExperiment}}} succeeds, experiment state remains in the testbed, but containers are stopped and resources are returned to the testbed. |
