NASA Logo, National Aeronautics and Space Administration

SSC Web Services Developer's Kit

Introduction

The Satellite Situation Center (SSC) is a system to cast geocentric spacecraft location information into a framework of (empirical) geophysical regions and mappings of spacecraft locations along lines of the Earth's magnetic field. This capability is one key to mission science planning (both single missions and coordinated observations of multiple spacecraft with ground-based investigations) and to subsequent multi-mission data analysis.  While SSCWeb provides access to the system through an HTML-based user interface, these Web services provides a distributed programming interface to SSC.  Figure 1.1-1 shows a simplified view of the software architecture.


 
Figure 1.1-1 Software Architecture
SSC 
Client Program
SSC 
Web services
SSC 
Unique Stubs
SSC 
Unique Ties
JAX-RPC Runtime SOAP Message JAX-RPC Runtime

Table 1.1-1 describes each component in more detail.
 

Table 1.1-1.  Component Description
Component Description Source
SSC Client Program A SSC client program.  It may use the SSC unique stubs and JAX-RPC or some other runtime support library. Developed by any organization wishing to use the SSC Web services.
SSC Unique Stubs SSC unique client wrapper to the JAX-RPC library.   This code is generated by the wscompile tool included with the JWSDP. Provided in the SSC Web services SDK by the group which developed the SSC Web services.
JAX-RPC runtime JAX-RPC runtime which handles the actual formatting and sending and receiving of SOAP messages. JWSDP.
SSC Unique Ties SSC unique server wrapper to the JAX-RPC library.   This code is generated by the wsdeploy tool included with the JWSDP. Delivered with the SSC Web services by the group which developed the SSC Web services.
SSC Web services The implementation of the SSC Web services.  This component interfaces with existing SSC software and data to fulfill Web service requests. Delivered with the SSC Web services by the group which developed the SSC Web services.

Description

This developer's kit contains the development files required to develop a client application that uses the SSC web services.  This document also provides information to help a developer in developing an SSC web service client.  Specifically, the kit contains the following: This document assumes the reader is already familiar with distributed programming concepts and a programming language but previous knowledge of web services is not required.

Issues common to all types of clients

This sections describes issues related to utilizing the SSC Web Services API from any type of client. That is, the issues described in this section apply to all clients irrespective of the programming language/tools used to develop the client or runtime enviroment in which the client is executed. The following issues are common to all types of clients:

These issues are described below.

WSDL binding style

The SSC Web services were initially developed before the Web Service Interoperability (WS-I) Basic Profile was finalized.  The SSC Web services currently use an RPC/encoded WSDL binding style.  This binding style may cause interoperability issues for clients that don't use the JAX-RPC libraries and the provided sscWebServices-client.jar.  In particular, Microsoft .NET clients may have problems calling the SSC Web services because of their use of RPC/encoded binding style.  We are considering a change to the document/literal binding style.  If you have comments concerning the binding style, please submit them to SSC.

HTTP User-Agent header

You are strongly encouraged to have your client set the HTTP User-Agent header (RFC 2068) to a value that identifies your client application in each SSC Web Service request that it makes. This will allow us to measure the usefulness of these services and justify their continued support. It isn't too important what value you use but it's best if it uniquely identifies your application. The specifics of how to do this in the client varies depending upon the programming language and support libraries used for the client. The example Java client described below contains the code required to set the header in a Java/JAX-RPC client. If you are unable or unwilling to set the User-Agent value in your client but still want us to know that your client uses the SSC Web Services, you may send a description of your client and any comments about the SSC Web Services to SSC.

Server resource limits

There are server computer resource limits imposed on the SSC Web services. While these limits are not expected to be limiting for legitimate requests, making requests for a long period of time or for a large number of spacecraft can exceed these limits and result in a "request exceeded computer resource limits" exception. A client may want to be prepared to deal with such occasions.

How to use the WSDL file

The WSDL file provides a standard description of SSC web services.  The file is available from http://sscweb.gsfc.nasa.gov/WS/ssc/jaxrpc?WSDL.   You may want to save the file to your computer's disk for later use.

Note
Depending upon your browser's XML capabilities and how it handles an XML file that doesn't contain any style information, you may need to use the browser's "view source" option to view the WSDL in the browser.  Recent versions of Internet Explorer and Mozilla will have no problem displaying the WSDL.  Alternately, you may force the browser to save the WSDL file and view it using another application.  The file should be viewable in a simple text editor.

Many programming languages now understand WSDL and can use this file to automatically invoke SSC services. For example, the WSDL can be imported into .NET, converted into Java code using the JAX-RPC wscompile tool, or used directly by Perl SOAP::Lite.  Refer to your particular development tools' documentation to learn how to use the provided WSDL file to develop a client application.  If you are developing your client in a language other than Java or don't want to use the included Java library, then you must use the WSDL and can ignore the next section.

How to use the Java API

For convenience, we have included a Java library based upon JAX-RPC.  It is not necessary to use this library but it will be the easiest way for someone developing a Java client to access the SSC Web Services.  You may use the WSDL described above along with any other standards complying web service development tools to develop a client instead of using this library.

The Java API provides an easy to use, high level API for accessing the SSC web services.  It was developed using JAX-RPC 1.0.  Here is a description of the CDAS Web services Java API .  In order to use the Java API, you must already have a Java 1.4 or higher development environment with the JAX-RPC 1.0 run-time class libraries (including the JAXP and SAAJ libraries).  At the time of this writing, JAX-RPC was not available as a separate download from Sun Microsystems.  Your options from Sun are to get the Java XML Pack or the Java Web Services Developer's Pack which both contain JAX-RPC.  Vendors other than Sun may offer other options.

The sscWebService-client.jar library provided with this kit contains an application that can be used to test the client run-time environment with the SSC web services.  To use the test client, use the equivalent of the following, single line command for your environment:

java -classpath jax-rpc-jars:sscWebServices-client.jar gov.nasa.gsfc.spdf.ssc.test.WsExample http://sscWeb.gsfc.nasa.gov/WS/ssc/jaxrpc

where jax-rpc-jars is to be replaced by all of the JAX-RPC jar files.

This should produce output similar to the following:

 Satellites:
   ace  ACE
   active  Active
   akebono  Akebono
   apex  APEX-MAIN
   astrid2  ASTRID II
...
   soho  SOHO
   timed  TIMED
   uars  UARS
   viking  Viking
   wind  Wind
   yohkoh  Yohkoh (Solar-A)
 Time to execute getAllSatellites = 1.631seconds
 start/end date = Tue Feb 17 14:26:15 EST 2004, Wed Feb 18 14:26:15 EST 2004
 Satellite[0] = POLAR
   beginTime = Sun Dec 31 19:00:00 EST 2000, endTime = Wed Jan 10 18:57:00 EST 2001
   CoordinateSystem = GSE
  -0.788028875672881 8.925380513561208 2.3655839247262382
  -0.8081627106650446 8.926213821948064 2.4012889391523187
  -0.8282461588970873 8.926492240332657 2.4368442134284094
  -0.8482779879331774 8.926218562674086 2.472248241409687
  -0.8682575589984121 8.925393412307814 2.5074992339540376
  -0.8881835121241222 8.924020319725233 2.5425954762644016
  -0.9080551013667406 8.922099887925055 2.5775356336756623
  -0.9278710963038708 8.919634150118615 2.612317648431352
  -0.9476307888515569 8.916625237656676 2.6469404544807045
  -0.9673327175884407 8.913075140082354 2.6814016882803697
  -0.9869763120931807 8.908985253733997 2.715700283779584
...
  -0.43791710999571065 8.201827014469993 4.195539777695964
  -0.45834483926818237 8.173558759296416 4.2185670330746055
  -0.47874541141251936 8.144771421469322 4.241325785884391
  -0.4991175196783957 8.115463679168101 4.263812718048686
  -0.5194596039938884 8.08563571365125 4.286025197409699
  -0.5397701296065258 8.055286915727164 4.307960703327206
  -0.5600481481978847 8.02441609913505 4.3296165664708886
  -0.580291581495084 7.993023247306708 4.350989580281684

 Time to execute getSatelliteLocations = 12.985seconds

 getSatelliteLocationCDF returned:
   http://ncssparc.gsfc.nasa.gov/spdf/ssc/polar_20020313132826.cdf

 Time to execute getSatelliteLocationCDF = 0.166seconds

 getSatelliteTime() returned
   1995/206 20:00:00 -0400
   2000/333 19:00:00 -0500

 Time to execute getSatelliteTime = 0.169seconds

 getSatelliteResolution() returned
   60 seconds

 Time to execute getSatelliteResolution = 0.131seconds


Here is the Java source code for the WsExample class.


The sscWebServices-client.jar and JAX-RPC jar files (jaxp-api.jar, dom.jar, sax.jar, xalan.jar, xercesImpl.jar, xsltc.jar, saaj-api.jar, saaj-ri.jar, activation.jar, commons-logging.jar, dom4j.jar, mail.jar, jaxrpc-api.jar, jaxrpc-ri.jar) must be in your classpath when compiling and running any application that uses the SSC web services.

NASA Logo - nasa.gov