gov.nasa.gsfc.spdf.ssc
Interface SatelliteSituationCenterInterface

public interface SatelliteSituationCenterInterface

This interface represents the XML Web Service interface to NASA's Satellite Situation Center.

Important Notes:

• These Web services adhere to the NASA Web Privacy Policy and Important Notices. To aid Web service client applications in making their users aware of these policies, a link to these notices are also programmatically available through the getPrivacyAndImportantNotices() method.
• When refering to this javadoc documentation of this Web Service interface, be aware that the code-level details seen by a client developer may contain differences. For example, where this javadoc documentation may describe a parameter as being of type java.util.Calendar, a client developer may be required to use a different type such as javax.xml.datatype.XMLGregorianCalendar. It is also likely that the object constructors used by a client do not function exactly like the ones described here (client developers should not trust that their constructors have the same default behavior). These types of differences are determined by the language (Java, Perl, etc.) and the tools and libararies (for example JAX-WS) the client is using. The WSDL is the offical description of this Web Service. Nonetheless, this javadoc documentation contains important semantic information about about this Web Service that is valuable to a client developer regardless of the language or tools they may be using.
• As of Release 2.1, these Web services recognize Space Physics Archive Search and Extract (SPASE) Spase/Observatory/ResourceID values (for example, "spase://SMWG/Observatory/ACE") as an alternative to SSC satellite identifier values (for example, "ace"). Specifically, a client may make a request with a SatelliteSpecification.getId() value set to a SPASE ResourceID of an Observatory corresponding to an SSC satellite. The following additional notes apply to SPASE ResourceIDs:
  • As of August 2008, not all SSC satellites have corresponding /Spase/Observatory/ResourceID values.
  • As of August 2008, some SSC satellites have multiple corresponding /Spase/Observatory/ResourceID values (usually issued by a different authority).
  • Even when a client request contains a SPASE ResourceID, the results provided by these Web services may contain the corresponding SSC satellite identifier.
  • Clients should use getAllSpaseObservatories() to programmatically obtain the associations between SPASE ResourceID and SSC satellite identifier values. These associations are also viewable at SPDF SPASE Observatories
• Clients that use these Web services are encouraged to acknowledge their use. To aid Web service client applications in making this acknowledgment, the getAcknowledgements() method is provided.
• 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 is 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.
• There are server computer resource limits imposed on the methods of this interface. 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.

Version:

$Revision: 1.1.2.9 $

Author:

B. Harris

Method Summary

FileResult	getAcknowledgements() This method provides a list of URLs that can be used by clients to acknowledge the use of these Web Services.
java.util.List<GroundStationDescription>	getAllGroundStations() Provides descriptions of all the ground stations available through this Web Service.
java.util.List<SatelliteDescription>	getAllSatellites() Provides descriptions of all the Satellites available through this Web Service.
java.util.List<SpaseObservatoryDescription>	getAllSpaseObservatories() Provides descriptions of all the Space Physics Archive Search and Extract (SPASE) Observatories available through this Web Service.
DataResult	getData(DataRequest request) Requests various information (see DataRequest) about a set of satellites.
FileResult	getDataFiles(DataFileRequest request) Requests various information (see DataFileRequest) about a set of satellites and returns the information in one or more files.
FileResult	getGraphs(GraphRequest request) Requests a graph (see GraphRequest) of a set of satellites.
FileResult	getPrivacyAndImportantNotices() This method provides a list of URLs to privacy and important notices concerning the use of these Web Services.

Method Detail

getPrivacyAndImportantNotices

FileResult getPrivacyAndImportantNotices()
                                         throws SSCExternalException

This method provides a list of URLs to privacy and important notices concerning the use of these Web Services.

Returns:

URLs to privacy and important notices

Throws:

SSCExternalException - thrown if unable to fulfill request

getAcknowledgements

FileResult getAcknowledgements()
                               throws SSCExternalException

This method provides a list of URLs that can be used by clients to acknowledge the use of these Web Services.

Returns:

URLs to acknowledgment of the use of these Web Services

Throws:

SSCExternalException - thrown if unable to fulfill request

getAllSatellites

java.util.List<SatelliteDescription> getAllSatellites()
                                                      throws SSCExternalException

Provides descriptions of all the Satellites available through this Web Service. The descriptions are returned in ascending alphabetical order of the identifier values.

Returns:

list containing the descriptions of all the available satellites

Throws:

SSCExternalException - thrown if unable to fulfill request

getAllSpaseObservatories

java.util.List<SpaseObservatoryDescription> getAllSpaseObservatories()
                                                                     throws SSCExternalException

Provides descriptions of all the Space Physics Archive Search and Extract (SPASE) Observatories available through this Web Service. See notes concerning SPASE support.

Returns:

list containing the descriptions of all the available observatories

Throws:

SSCExternalException - thrown if unable to fulfill request

getAllGroundStations

java.util.List<GroundStationDescription> getAllGroundStations()
                                                              throws SSCExternalException

Provides descriptions of all the ground stations available through this Web Service.

Returns:

list containing the description of all the available ground stations

Throws:

SSCExternalException - thrown if unable to fulfill request

getData

DataResult getData(DataRequest request)
                   throws SSCExternalException,
                          SSCResourceLimitExceededException

Requests various information (see DataRequest) about a set of satellites.

Parameters:

request - specifies what data is being requested

Returns:

the requested data

Throws:

SSCExternalException - if unable to fulfill request

SSCResourceLimitExceededException - if unable to fulfill request due to a server resource limit

Since:

2.0

getDataFiles

FileResult getDataFiles(DataFileRequest request)
                        throws SSCExternalException,
                               SSCResourceLimitExceededException

Requests various information (see DataFileRequest) about a set of satellites and returns the information in one or more files.

Parameters:

request - specifies what data is being requested

Returns:

the requested data

Throws:

SSCExternalException - if unable to fulfill request

SSCResourceLimitExceededException - if unable to fulfill request due to a server resource limit

Since:

1.5

getGraphs

FileResult getGraphs(GraphRequest request)
                     throws SSCExternalException,
                            SSCResourceLimitExceededException

Requests a graph (see GraphRequest) of a set of satellites.

Parameters:

request - specifies what data is being requested

Returns:

the requested graph

Throws:

SSCExternalException - if unable to fulfill request

SSCResourceLimitExceededException - if unable to fulfill request due to a server resource limit

Since:

1.5