Jump to main content.

WATERS JavaScript Library

Description

The WATERS JavaScript Library provides an easy to use interface that hides the complexities of calling the WATERS HTTP services. The library supports both AJAST and AJAX style requests. The below diagram depicts how the library fits into a consumer application and the WATERS Service architecture.

 

 

Please refer to the WATERS Code Playground Exit for examples of library usage.

Hyperlink to Library

Include Script
<script type="text/javascript" src="http://www.epa.gov/waters/tools/WATERSServicesJSLib/WATERSServices-1.0.0-min.js"></script>

Usage Information

The library provides easy to use JavaScript functions that abstract the web services that reside in WATERS. The individual JavaScript functions are identified under each corresponding WATERS Service page. All library service functions take two input objects parameters {data and options}. The data input object contains the specific service input parameters to use during execution of the service {includes specific HTTP Service parameters mention on the corresponding service page). The options input object contains the parameters to use during the invocation of the remote service.

An example call to the Name Service is below.

<html>
<head>
<script type="text/javascript" src="http://www.epa.gov/waters/tools/WATERSServicesJSLib/WATERSServices-1.0.0-min.js"></script>    //Include WATERS library
<script type="text/javascript">

   function Success(data, textStatus) {                                   //Define success callback
     alert(textStatus);
   }

   function Error(XMLHttpRequest, textStatus, errorThrown) {              //Define error callback
     alert(textStatus);
   }

   var options = {"success" : "Success", "error" : "Error"};              //Define options input object
   var data = {“pFullText” : “potomac river”};                            //Define data input object
   rtnStr = WATERS.Services.NameService(data, options);                   //Call WATERS JavaScript Service function
   if (rtnStr != "") {                                                    //Check return string to make sure JS Service call registered correctly
      alert(rtnStr); 
   } 

</script>
</head>
<body>
</body>
</html>

Proxy Usage

Proxy support is available to provide more control over the request lifecycle. The main advantages of proxy usage include but are not limited to, working around browser location length limitations, working around web server URL length limitations, and providing synchronous request support. The WATERS JavaScript Library proxy support has been specifically tested using the free proxy code provided by ESRI. Exit

Input Parameters

Data Object Parameter

The parameters in this object are specific to each service. Please refer to the corresponding WATERS Service page for additional information about input parameters on a per service basis.

Options Object Parameters

The WATERS JavaScript library makes extensive use of the JQueryExitand JQuery-jsonpExitJavaScript libraries to provide the core communication functionality in the WATERS JavaScript library. As such, the below parameters mimic the AJAX/AJAST parameters documented on the JQuery Options web page.Exit

Parameter Datatype Required Description
async Boolean   Default = true. If you need synchronous requests, set this option to false. Note that synchronous requests may temporarily lock the browser, disabling any actions while the request is active. This parameter is only available for AJAX style requests.
beforeSend String   A string representing the name of a pre-callback function that can modify the XMLHttpRequest object before it is sent. Use this to set custom headers etc. The XMLHttpRequest is passed as the only argument. You may return false in function to cancel the request.
cache Boolean   Default = false. If set to false it will force the pages that you request to not be cached by the browser.
complete String   A string representing the name of function to be called when the request finishes (after success and error callbacks are executed). The function gets passed two arguments: The XMLHttpRequest object and a string describing the type of success of the request.
contentType String   Default = "application/x-www-form-urlencoded". For sending data to the server, use this content-type.
dataFilter String   A string representing the name of function to be used to handle the raw responsed data of XMLHttpRequest.This is a pre-filtering function to sanitize the response. You should return the sanitized data. The function gets passed two arguments: The raw data returned from the server, and the 'dataType' parameter.
dataType String   Default = "JSON". Type of data that you're expecting back from the server.
error String True A string representing the name of function to be called if the request fails. The function is passed three arguments: The XMLHttpRequest object, a string describing the type of error that occurred and an optional exception object, if one occurred. Possible values for the second argument (besides null) are "timeout", "error", "notmodified" and "parsererror".
featureID Number   For results containing numerous iterable geometry objects, each object will be assigned a feature id beginning with the value of this parameter or 1 if the parameter is not specified.
geomCS String   By default all geometry output from WATERS services utilize the NAD83 geodetic coordinate system. Use this parameter to specify if a different coordinate system for output geometries is desired.  All server side transformations are highly dependent on Oracle Spatial settings, particularly as regards those coordinate systems which are not part of Oracle Spatial by default.  Use the format "SRID=4326" to specify that the server utilize spatial reference id 4326 (WGS84) to transform outgoing geometries. If the exact Oracle Spatial SRID is unknown, use the format "EPSG:4326" to utilize the OGP Surveying & Positioning Committee Exit code for WGS84 instead.
geomFormat String   For data structures containing geometries, the output format of the geometries defaults to best match the format of the data structure. For example, requesting the JSON data structure format produces by default GEOJSON formatted geometries. Use this parameter to override defaults and force custom output geometry format. See the HTTP service geometry format section for more information on available formats.
geomStyleURL String   Keyword utilized by services when creating output data structures for stylization of geometries.  The optStyleURL parameter is used as a prefix to the geometry field name in the output object.
geomVerticeLimit Number   Depending on the parameters used, WATERS services may return results that are too large to reasonably transfer via a HTTP service.  In most cases the attribute information associated with output results are only a small portion of the total payload.  By far the geometry is the largest data structure being passed to the client.  Restricting results to those having a total count of vertices less than this parameter is an effective way to avoid service timeouts.  While the service endpoint may cap total vertices returned at a certain number, the client has the option to use this parameter to further restrict output results.  This parameter cannot be used to loosen those vertice restrictions imposed by the service endpoint.
global Boolean   Whether to trigger global AJAX event handlers for this request. The default is true. Set to false to prevent the global handlers like ajaxStart or ajaxStop from being triggered. This can be used to control various Ajax Events.
OSTolerance Number   Geometry functions and transformations within Oracle Spatial utilize the concept of tolerance extensively. Tolerance values indicate the minimum distance by which two points are considered distinct when manipulating geometries. See Oracle Spatial Documentation Exit for more information.  The default tolerance value for WATERS geometries stored using the NAD83 coordinate system is 0.05 meters.  Raising or lowering this value will affect performance with larger values producing speedier but less accurate results.
outFormat String   While the majority of WATERS HTTP services produce JSON and/or JSONP formatted output, some services are also available as SLD. Use this parameter corresponds to the optOutFormat HTTP Parameter.
prettyPrint Number   Optional feature to attempt to format output with logical indentations and linefeeds to promote visualization and debugging efforts. Numeric value indicates the number of three-space indentations to begin pretty printing efforts at. Value of 0 begins at the left margin. Do not pass any value for compacted results. Pretty printed results should never be used in production usage.
proxyurl String   URL to custom proxy server to use for AJAX style request. This parameter is REQUIRED when using the library in AJAX mode.
submissionID String   Identifier submitted with a service request representing a unique or meaningful name for the request. This value will be reflected in return results allowing control over multiple asynchronous service calls. In KML-formatted requests the upper-most folder in the results will be named with this value.
success String True A string representing the name of function to be called if the request succeeds. The function gets passed two arguments: The data returned from the server, formatted according to the 'dataType' parameter, and a string describing the status.
timeout Number   Set a local timeout (in milliseconds) for the request.
type String   Default = GET. The type of request to make ("POST" or "GET"). Note #1: Other HTTP request methods, such as PUT and DELETE, can also be used here, but they are not supported by all browsers. Note #1: AJAST style requests only support GET.

Output


All JSON based output will contain a standard anonymous surrogate output object. This object acts as a standard container for all the HTTP WATERS Services. Please refer to the Anonymous Surrogate Object for more information.

Anonymous Surrogate Object

Parameter Datatype Description
output Object The result from a particular WATERS Service. Please refer to the individual WATERS Service pages for for information about specific output return values.
status Object See Status Object.

Status Object

Parameter Datatype Description
submission_id String Identifier passed into the service via the options submissionID parameter.
status_code Number Code indicating that the service returned an erroneous condition. A value of zero indicates success.
status_message String Message explaining any errors indicated by the error code.
execution_time Number Amount of time the internal service took to complete. This does not include transmittal time between client and service.
output_bytes Number Size in bytes of information contained in the output object of the Anonymous Surrogate Object.

Metadata

This web page serves as the metadata for the WATERS JavaScript Library.

Versioning


At a minimum, a 6 month support cycle is expected to be followed when making contract changing updates to the library. The 6 month countdown cycle will began after the initial notice is delivered to stakeholders. All possible efforts will be made to ensure compatibility between versions of the library. If needed, these efforts may include maintaining duplicate service code in the WATERS database. In all cases, minimizing the impact on our consumers will dictate which actions we take regarding updates to the library.

Usage Notes

The library contains a top level namespace ("WATERS") to avoid variable name clashes within consumers applications and other libraries.

Changelog

Version: 1.0 - Released: August 31, 2009

  • Initial release of the WATERS JavaScript Library

Version: 1.0 (Update)- Released: September 9, 2009

Local Navigation

Jump to main content.