VSO WSDL Interface

From VSO NetDRMS & JMD Wiki

Jump to: navigation, search

Contents

VSO WSDL

VSO WSDL Document

WSDL: Web Service Definition Language

A WSDL is an xml document that describes how the message interaction between a SOAP client and server takes place, how the message structure looks like, what operations implements and what is the protocol and network end-point the client should connect to.

Note: by "client" we understand your program or application, by "server" a VSO Core implementation.

VSO WSDL

The current implementation of the VSO WSDL is RPC-Literal. This is just a flavor of the many variants out there. RPC-Literal works well with stub generating packages, such us axis2. So it is fairly easy to quickly build a client in java or C.

The other version the VSO supports is RPC-encoded but there is no WSDL for that. Instead you will use a perl code to connect to the VSO. Its natural language.


VSOi_rpc_literal.wsdl download

VSO code samples

IDL

See VSO IDL documentation in VSO IDL DOC

JAX-WS (JWS)

We used JAX-WS, which comes as default with the Java VM, to generate stub code for Java and C. We experimented with versions 2.1.1 and the more uptodate 2.2.2. To generate the stub code you simply have to run one command: E.g. 

 wsimport -s ./src http://docs.virtualsolar.org/WSDL/VSOi_rpc_literal.wsdl

       VSOiService service   = new VSOiService();
       VSOiPort    port      = service.getNsoVSOi();

       QueryRequest request = new QueryRequest();

       request.setVersion(new Float("0.6").floatValue());
       QueryRequestBlock block = new QueryRequestBlock();

       //Set Time object
       // This example finds the last record available
       // by using the "near time" feature
       Time timeParam = new Time();
       timeParam.setStart("20100907161400");
       timeParam.setEnd(  "20100907161500");

       block.setTime(timeParam );     //Set Time
       block.setPixels("1024");       //Set Pixel resolution
       block.setProvider("jsoc");     //Set Provider
       block.setInstrument("aia");    //Set Instrument

       //Finishing setting up the Query message
       request.setBlock(block );
       //Finally perform the request.
       QueryResponse response = port.query(request);

       //Request is sent and received.
       //The request is type array.
       List<ProviderQueryResponse> qReturn = response.getProvideritem();

       //Go over the returned array
       for (ProviderQueryResponse qr:qReturn) {
        ....
       }

The full java code sample can be downloaded from VSOJWSClient.java
A color version of the code can be visualized in VSOJWSClient.java.


Axis2

We used axis2 to generate stub code for Java and C. You can get the axis2 package from http://ws.apache.org/axis2. We experimented with versions 1.5 and 1.6. Once it is installed, defined your JAVA_HOME and AXIS2_HOME environment variables.

E.g. 

#for a bash shell:
export JAVA_HOME=/usr/local/java
export AXIS2_HOME=/usr/local/axis2-1.5.1
export PATH=$AXIS2_HOME/bin:$PATH

Java

To generate the Java stub classes simply run the wsdl2java.sh utility program with the arguments to generate the client stubs.

E.g. 

wsdl2java.sh -s -S ./src -uri VSOi_rpc_literal.wsdl

This will generate the java code in the directory ./src"

E.g. 

src/org
src/org/virtualsolar
src/org/virtualsolar/vso
src/org/virtualsolar/vso/vsoi
src/org/virtualsolar/vso/vsoi/VSOiServiceStub.java

VSOiServiceStub.java implements all the classes necessary to build/read the message and send or receive from VSO end. 


	// Create SOAP service handler class
	VSOiServiceStub service = new VSOiServiceStub();
        
        // Create and populate request block
	QueryRequestBlock block = new QueryRequestBlock();
	Time timeParam = new Time();
	timeParam.setStart("20100909000000");
	timeParam.setEnd(  "20100909000002");
		
	block.setTime(timeParam);      // Set Time
	block.setPixels("1024");	   // Set Pixel resolution
	block.setProvider("jsoc");	   // Set Provider
	block.setInstrument("aia");    // Set Instrument
		      
	QueryRequest request = new QueryRequest();	
	request.setVersion(new Float("0.6").floatValue());	
	request.setBlock(block );      // Set block query
		
	Query query = new Query();		
	query.setBody(request);        // Set request message in SOAP body
		
	//Finally perform the request.
	QueryResponseE response = service.query(query);
		
	//Request is sent and received.
	//The request is type array.   
	ProviderQueryResponse qReturn[] = response.getBody().getProvideritem();

The full java code sample can be downloaded from VSOAxis2Client.java
A color version of the code can be visualized in VSOAxis2Client.java.

C code

C stubs can be similarly obtained by running the WSDL2C.sh shell script. Making sure it gets the arguments to generate the client code.

E.g. 

sh $AXIS2_HOME/bin/tools/wsdl2c/WSDL2C.sh -uri VSOi_rpc_literal.wsdl -d adb -u

This will generate the stub code in a directory "src" with the following contents: 

> ls src
adb_DataContainer.c    adb_GetDataResponse.c          adb_QueryResponseBlock.c
adb_DataContainer.h    adb_GetDataResponse.h          adb_QueryResponseBlock.h
adb_DataItem.c         adb_GetDataResponseItem.c      adb_QueryResponse.c
adb_DataItem.h         adb_GetDataResponseItem.h      adb_QueryResponseE0.c
adb_DataRequestItem.c  adb_Info.c                     adb_QueryResponseE0.h
adb_DataRequestItem.h  adb_Info.h                     adb_QueryResponse.h
adb_Extent.c           adb_info_type0.c               adb_Thumbnail.c
adb_Extent.h           adb_info_type0.h               adb_Thumbnail.h
adb_Extra.c            adb_MethodItem.c               adb_Time.c
adb_Extra.h            adb_MethodItem.h               adb_Time.h
adb_Field.c            adb_ProviderQueryResponse.c    adb_VSOGetDataRequest.c
adb_Field.h            adb_ProviderQueryResponse.h    adb_VSOGetDataRequest.h
adb_FileidItem.c       adb_Query.c                    adb_VSOGetDataResponse.c
adb_FileidItem.h       adb_Query.h                    adb_VSOGetDataResponse.h
adb_GetData.c          adb_QueryRequestBlock.c        adb_Wave.c
adb_GetData.h          adb_QueryRequestBlock.h        adb_Wave.h
adb_GetDataItem.c      adb_QueryRequest.c             axis2_stub_VSOiService.c
adb_GetDataItem.h      adb_QueryRequest.h             axis2_stub_VSOiService.h
adb_GetDataRequest.c   adb_QueryResponseBlockArray.c
adb_GetDataRequest.h   adb_QueryResponseBlockArray.h

A sample client code can be found at RPCVSOClient.c

C#

TBD

Perl

A generic sample perl code can be found at VSOSOAPClient.pl

A more specific sample perl code that downloads Stereo data at Noon and Midnight can be found at VSOSOAPStereoTwoRecordsADaySample.pl

VSO xml samples

VSO Query xml

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <ns1:Query xmlns:ns1="http://virtualsolar.org/VSO/VSOi">
      <body>
        <version>0.6</version>
        <block>
          <provider>jsoc</provider>
          <instrument>aia</instrument>
          <time>
            <start>20100701000000</start>
            <end>20100701000200</end>
          </time>
          <wave>
            <wavemin>193</wavemin>
            <wavemax>193</wavemax>
            <waveunit>Angstrom</waveunit>
          </wave>
          <field>
            <fielditem>thumbnail</fielditem>
            <fielditem>detector</fielditem>
          </field>
          <pixels>1024</pixels>
        </block>
      </body>
    </ns1:Query>
  </soapenv:Body>
</soapenv:Envelope>

VSO Query Response xml

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:VSO="http://virtualsolar.org/VSO/VSOi">
  <soap:Body>
    <VSO:QueryResponse>
      <body>
        <provideritem>
          <provider>JSOC</provider>
          <record>
            <recorditem>
              <info>AIA test series 1024x1024</info>
              <source>SDO</source>
              <provider>JSOC</provider>
              <physobs>intensity</physobs>
              <fileid>aia_synoptic2:193:11744640</fileid>
              <time>
                <start>20100701000006</start>
                <end>20100701000007</end>
              </time>
              <instrument>AIA</instrument>
              <size>4200</size>
              <wave>
                <waveunit>Angstrom</waveunit>
                <wavemin>193</wavemin>
                <wavetype>NARROW</wavetype>
                <wavemax>193</wavemax>
              </wave>
              <extent>
                <type>FULLDISK</type>
              </extent>
            </recorditem>
            <recorditem>
              <info>AIA test series 1024x1024</info>
              <source>SDO</source>
              <provider>JSOC</provider>
              <physobs>intensity</physobs>
              <fileid>aia_synoptic2:193:11744641</fileid>
              <time>
                <start>20100701000130</start>
                <end>20100701000131</end>
              </time>
              <instrument>AIA</instrument>
              <size>4200</size>
              <wave>
                <waveunit>Angstrom</waveunit>
                <wavemin>193</wavemin>
                <wavetype>NARROW</wavetype>
                <wavemax>193</wavemax>
              </wave>
              <extent>
                <type>FULLDISK</type>
              </extent>
            </recorditem>
          </record>
          <version>1</version>
          <no_of_records_found>2</no_of_records_found>
          <no_of_records_returned>2</no_of_records_returned>
          <debug>AND  (date_obs BETWEEN ? AND ?) and (wave BETWEEN ? AND ? ) </debug>
        </provideritem>
      </body>
    </VSO:QueryResponse>
  </soap:Body>
</soap:Envelope>

VSO GetData Query xml

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <ns1:GetData xmlns:ns1="http://virtualsolar.org/VSO/VSOi">
      <body>
        <version>1</version>
        <request>
          <method>
            <methodtype>URL-FILE</methodtype>
          </method>
          <datacontainer>
            <datarequestitem>
              <provider>JSOC</provider>
              <fileiditem>
                <fileid>aia_synoptic2:193:11744640</fileid>
                <fileid>aia_synoptic2:193:11744641</fileid>
              </fileiditem>
            </datarequestitem>
          </datacontainer>
        </request>
      </body>
    </ns1:GetData>
  </soapenv:Body>
</soapenv:Envelope>


VSO GetData Response xml

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:VSO="http://virtualsolar.org/VSO/VSOi">
  <soap:Body>
    <VSO:GetDataResponse>
      <body>
        <getdataresponseitem>
          <provider>JSOC</provider>
          <version>1</version>
          <method>
            <methodtype>URL-FILE</methodtype>
          </method>
          <getdataitem>
            <dataitem>
              <provider>JSOC</provider>
              <fileid>aia_synoptic2:193:11744640</fileid>
              <url>http://kurasuta.cfa.harvard.edu/cgi-bin/VSO/prod/drms_export.cgi?series=aia_synoptic2;record=193_11744640-11744640</url>
            </dataitem>
            <dataitem>
              <provider>JSOC</provider>
              <fileid>aia_synoptic2:193:11744641</fileid>
              <url>http://kurasuta.cfa.harvard.edu/cgi-bin/VSO/prod/drms_export.cgi?series=aia_synoptic2;record=193_11744641-11744641</url>
            </dataitem>
          </getdataitem>
        </getdataresponseitem>
      </body>
    </VSO:GetDataResponse>
  </soap:Body>
</soap:Envelope>

VSO Talks and Posters on programmatic interfaces

Retrieved from "http://vso.tuc.noao.edu/VSO/w/index.php/VSO_WSDL_Interface"
Personal tools