NASA Logo, National Aeronautics and Space Administration

Web Service To Launch The SSC 4D Orbit Viewer

Introduction

The Web service described below, allows any Web application to conveniently link to the SSC 4D Orbit Viewer in such a way that the viewer can be launched from any web page with initial time-range and satellite information.  This allows any Web application to offer an interactive 4D display of the trajectories of satellites known to SSC.

The 4D Orbit Viewer requires that Java be installed on the end-users computer.  If there is the possibility that Java is not already installed on the end-user's computer, Web application developers should use the Web Service To Install Java And Launch the SSC 4D Orbit Viewer instead of this 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/launch.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 XML document with MIME-type application/x-java-jnlp-file and conforming to the Java Network Launching Protocol (JNLP) Specification (JSR-56), versions 1.5 and higher.   The resulting JNLP does not contain <shortcut> and <desktop> elements.  Furthermore, to discourage intermediate proxies, Web browsers, and JNLP clients from caching this dynamic response, the response will have the HTTP header fields set as described in the table below

Header
 Value
 Comment
Cache-Control
 no-store
 for HTTP 1.1
Pragma
 no-cache
 for HTTP 1.0
Expires
 0
 to prevent caching at a proxy server

On a system with Java installed and enabled, this resulting document should cause a Web browser to launch a JNLP client (e.g., Web Start) which should then launch the 4D Orbit Viewer with the given initial selection parameters.

Examples

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

http://sscweb.gsfc.nasa.gov/WS/tipsod/1/launch.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 hid 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 a browser that performs the GET fails to start the Orbit Viewer, the most likely cause is that Java is not installed, Java is disabled, or the browser is otherwise mis-configured for JNLP.

To view the resulting JNLP document, configure the browser to display or save JNLP files instead of launching a JNLP client or simply use wget.  The following is an example using wget
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