source: TI03-DataExtractor/branches/old_stuff/dx_source/for_usr_local/dx/doc/dxWebServiceInterface_module.txt @ 793

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI03-DataExtractor/branches/old_stuff/dx_source/for_usr_local/dx/doc/dxWebServiceInterface_module.txt@793
Revision 793, 6.6 KB checked in by astephen, 13 years ago (diff)

Put all the old code in the old_stuff branch.

Line 
1Help on module dxWebServiceInterface:
2
3NAME
4    dxWebServiceInterface
5
6FILE
7    /usr/local/dx-0.1.1/dxWebServiceInterface.py
8
9DESCRIPTION
10    dxWebServiceInterface.py
11    ========================
12   
13    A web service wrapper around the entire DataExtractor.
14   
15    Wraps the dx functionality into the following Web Services:
16   
17    - callControlExtractClass(args)
18   
19    - startSession(username=None, password=None, secureToken=None)
20   
21    - getOptions(sessionID, secureToken=None)
22   
23    - selectOptions(sessionID, opt_1, opt_2, ...,opt_n, secureToken=None)
24   
25    - numberOfDatasets(sessionID, n, secureToken=None)
26   
27    - summariseRequest(sessionID, secureToken=None)
28   
29    - isComplete(sessionID, secureToken=None)
30   
31    - getDataSubsetSpecifier(sessionID, secureToken=None)  # This returns XML
32   
33    - getExtractionCosts(sessionID, secureToken=None)
34   
35    - extractData(sessionID, secureToken=None)  # This extracts actual data
36   
37    - newRequest(sessionID, secureToken=None)
38   
39   
40    Notes about the sessionID and secureToken object
41    ------------------------------------------------
42   
43    The sessionID carries information about the current request but has no security
44    implications. It is simply a way for the server to keep track of the request
45    between calls.
46   
47    The secureToken is an encoded security object that is time limited and provides
48    information on what the user is allowed to access on the server. Some dx servers
49    do not run security and so just send around a None type as the secureToken. Those
50    implementing security will require that the secureToken (held in a string) is sent
51    with each call to the dx. During each call it will updated (to ensure it remains
52    time valid) and returned.
53   
54   
55   
56    ############# THE FOLLOWING MIGHT BE IMPLEMENTED IN FUTURE #############
57    getDatasetGroupOptions(sessionID, secureToken=None)
58   
59    selectDatasetGroups(sessionID, datasetGroup_1, datasetGroup_2, ..., datasetGroup_n, secureToken=None)
60   
61    getDatasetOptions(sessionID, secureToken=None)
62   
63    selectDatasets(sessionID, dataset_1, dataset_2, ..., dataset_n, secureToken=None)
64   
65    getVariableOptions(sessionID, secureToken=None)
66   
67    selectVariables(sessionID, variable_1, variable_2, ..., variable_n, secureToken=None)
68   
69    getHorizontalDomainOptions(sessionID, secureToken=None)
70   
71    selectHorizontalDomain(sessionID, northernExtent, westernExtent,
72           easternExtent, southernExtent, secureToken=None)
73           
74    getVerticalDomainOptions(sessionID, secureToken=None)
75   
76    selectVerticalDomain(sessionID, verticalDomain_1, verticalDomain_2, ...,
77                            verticalDomain_n, secureToken=None)
78                           
79    getTemporalDomainOptions(sessionID, secureToken=None)
80   
81    selectTemporalDomainOptions(sessionID, startTime_1, endTime_1, startTime_2, endTime_2,
82                                    ..., startTime_n, endTime_n, secureToken=None)
83                    # Note that times are expressed as: "YYYY-MM-DD hh:mm:ss" or minimally as "YYYY"
84                    # which convert to "YYYY-01-01 00:00:00".
85                   
86    getOutputFormatOptions(sessionID, secureToken=None)
87   
88    selectOutputFormat(sessionID, outputFormat, secureToken=None)
89
90FUNCTIONS
91    callControlExtractClass(**args)
92        Function wrapper to ControlExtract class. This can be called directly
93        to perform all operations or the other Web Services can be called in
94        the appropriate order.
95   
96    extractData(sessionID, secureToken=None)
97        Extracts the actual data you specified in the request. It writes these files
98        locally and returns a list of paths to the data as either FTP or HTTP
99        locations.
100        Returns a list of paths and a security token.
101   
102    getDataSubsetSpecifier(sessionID, secureToken=None)
103        Returns the dataSubsetSpecifier XML document (which might be S-metadata)
104        required by a Delivery Service to describe the subset requested, and a
105        security token.
106   
107    getExtractionCosts(sessionID, secureToken=None)
108        Returns an estimated duration for the creation of the output data and the
109        estimated volume of the output.
110   
111    getOptions(sessionID, secureToken=None, optionCategoryRequested=None)
112        Returns a category description of the next set of options (or the option category
113        requested by the user), a list of options based
114        on what the user has yet to request, a string explaining some more about this and a
115        security token.
116       
117        The options will be presented following the heirarchy:
118            DatasetGroups
119            Datasets
120            Variables
121            HorizontalDomain
122            VerticalDomain
123            TemporalDomain
124            OutputFormat
125   
126    isComplete(sessionID, secureToken=None)
127        Returns 1 if the request is complete (i.e. ready for extraction)
128        and 0 if not. Also returns a security token.
129   
130    newRequest(sessionID, secureToken=None)
131        Deletes content of current request.
132        Returns the sessionID and the security token..
133   
134    numberOfDatasets(sessionID, n, secureToken=None)
135        Re-selects the number of datasets the user wants to deal with in the request.
136        Default is 1.
137        Returns 1 if successful and an errorString if not, as well as a security token.
138   
139    selectOptions(sessionID, **args)
140        Makes a selection based on user requirements. This will typically follow a call
141        to getOptions() to find out what the options are.
142        Returns a call to getOptions() to grab the next set of options available to the
143        user. Alternatively, if it fails, an errorString is returned.
144   
145    serveAll()
146        Serves all functions via Web Services.
147   
148    startSession(username=None, password=None, secureToken=None)
149        Logs a user into the dx and supplies them with a session ID as well
150        as an encoded security token. The session ID connects them to their
151        current request serverside whilst the security token is used to
152        authorise their access.
153   
154    summariseRequest(sessionID, secureToken=None)
155        Returns a listing of the current request in a string and a security token.
156   
157    uploadRequest(sessionID, requestXMLString, secureToken=None)
158        Allows the user to send a request in the form of a string containing the
159        contents of an XML file conforming to the dx request specification (not
160        yet written). This is also called a Data Subset Specifier.
161        This function parses the XML into a dictionary and then uploads the arguments.
162        Returns a status flag (1=success, None=failure) and the secure token.
163
Note: See TracBrowser for help on using the repository browser.