NASA Logo, National Aeronautics and Space Administration

Web Service To Install Java And Launch The SSC 4D Orbit Viewer

Introduction

The Web service described below creates an HTML page containing JavaScript to test for the presence of Java and initiate an installation if necessary.  Once Java is installed, the page calls another Web service to Launch the SSC 4D Orbit Viewer with the initial time-range and satellite information provided to this service.  If Java is known to already be installed on the end-user's computer, this Web service can be avoided and the Orbit Viewer can be launched directly from the other Web service.  The description below is intended for Web application developers.

REST-Style Web API

This service provides a REST-style (or RESTful) Application Programming Interface (API) through HTTP, for launching the SSC 4D Orbit Viewer.  To launch the application, a client makes an HTTP GET (or POST) to

http://sscweb.gsfc.nasa.gov/WS/tipsod/1/installJavaAndLaunch.jsp?parameters

where parameters is a variable number of parameter-name=parameter-value pairs as described in the following table.

Parameter-name
 Parameter-value
 Description
begin
 Beginning of time range
 This value should be formatted as yyyy-MM-ddTHH:mm (see java.text.SimpleDateFormat API documentation for the pattern description) and be specified for the UTC time zone.  If this parameter is not given or its value is not formatted correctly, the viewer will be launched but the user will have to specify a value before the orbits will be shown.
end
 Ending of time range
 This value should be formatted as yyyy-MM-ddTHH:mm (see java.text.SimpleDateFormat API documentation for the pattern description) and be specified for the UTC time zone.  If this parameter is not given or its value is not formatted correctly, the viewer will be launched but the user will have to specify a value before the orbits will be shown.
coord
 coordinate system
 This value should be one of SM, GSM, GSE, GM, GEO, GEI_J2000, GEI_TOD.  This parameter is optional and defaults to the 4D Orbit Viewer's default value.
resolution
 small integer
 This value corresponds to the SSC DB factor.  This parameter is optional and defaults to the 4D Orbit Viewer's default value.
btrace
 1
 This value enables magnetic field line tracing.  This should be disabled to improve performance unless tracing is actually desired.  This parameter is optional and defaults to "disabled" if the parameter is omitted or has a value other than 1.
single
 1
 This value specifies whether subsequent requests should be handled by a single instance of the Orbit Viewer application or if each request should start a new instance of the application. This parameter is optional and defaults to "disabled" (that is, multiple instances) if the parameter is omitted or has a value other than 1.
sat
 satellite identifier
 This parameter may be given any number of times.  If the parameter is omitted, the viewer will be launched but the user will have to choose the satellites that are to be shown.  The values should be the Id value from  the SatelliteDescriptions returned by SatelliteSituationCenterInterface.getAllSatellites() Web service call or the corresponding SPASE Observatory ResourceID shown here.

The result of such an HTTP GET or POST is an HTML document containing JavaScript to do the following:
Web application developers will most likely want to have this resulting HTML document displayed in a new window/tab.

Examples

The  following URL will launch the 4D Orbit Viewer with the specified initial selection

http://sscweb.gsfc.nasa.gov/WS/tipsod/1/installJavaAndLaunch.jsp?begin=2008-07-01T00:00&end=2008-07-02T00:00&sat=cluster1&sat=fast

The URL details shown above are meant as an example for Web application developers.  Web applications can hide the details from the end user like shown below.

launch application


The above example utilized the default values for coordinate system, resolution, and B-field tracing parameters.  The following demonstrates a call that explicitly specifies all parameter values

launch application

Troubleshooting

If the Orbit Viewer does not automatically display the orbits or appears to be using the wrong parameter values, display the Java console and look for error messages involving the parameter values.

Changes

We strive not to make changes to the Web services that would cause client applications to fail. Major functional changes and changes to the Web services' public interface are only made at major releases (e.g., R1.0 to R2.0) and not at minor releases (e.g., R1.0 to R1.1). We provide advanced notice of major changes and leave the existing Web services available for a transition period after the new release has been deployed (at a URL that is different from the previous major release). Announcements of both major and minor releases are made to the spdf_announcements e-mail list. All client developers are encouraged to subscribe to this e-mail list so they are aware of changes. Otherwise, it is possible that Web service changes could be made that adversely affect a developer's client without the developer knowing about the change.

NASA Logo - nasa.gov