GetDAQ Web Service

Table Of Contents

1. Introduction
2. General Overview
3. Technical Overview
4. Status Page
5. Dynamically Updated Page
6. Examples
7. Links

1. Introduction

GetDAQ application is a data acquisition web service for ACNET control system. It provides an opportunity for outer networks to read data of Fermilab's site-located devices.

Complete project description is available here: http://beamdocs.fnal.gov/AD-public/DocDB/ShowDocument?docid=3949.

2. General Overview

The web service is an additional layer between the user's application and the DAE (Data Acquisition Engine), providing a mapping between the request-response pattern to a constantly running DAQ (Data AcQuisition) job thread.

The service has the following key features:

• An HTTP-based request-response text protocol for data acquisition.
• Support for both GET and POST requests. POST requests may be used to obtain large sets of data. GET request allows one to use RESTful URL to query necessary devices.
• 4 different formats of devices' replies: XML, HTML, plaintext (CSV), JSON.
• Different options for choosing the representation format of requested data.
• Caching system for DAQ jobs. There's also cache cleaner responsible for stopping jobs which are not needed anymore.

3. Technical Overview

a. General

GetDAQ service is implemented by a Java servlet running on ACNET infrastructure. It accepts HTTP requests for data, parses the DAQ request and submits the request to a cache manager which is responsible for modifying the devices' cache. If the request contains devices which are not currently stored in cache, the manager starts a new DAQ jobs containing these devices. Right after the submittal, the device will have a "pending" status indicated by a status code «72 1». All replies of the devices are then marshalled to a representation specified by the client. By default, the service will return an XML document.

Due to a read-only nature of DAQ requests, no authentication mechanism was introduced.

b. DAQ Request

The request string can be either a part of the URL or a POST parameter "request". There are two ways of writing the request: either by separating device names by brackets or semicolons. Device names must abide DRF2 specification.
Below are examples of using both methods. Note, that it should be specified explicitly if the request is bracket-separated. For the details, please refer to Section 3c.

Example of the semicolon-separated request:

m:outtmp;m:outhum;z:cache.reading;n:ccfoxy;i:beam

Device names MUST NOT contain any whitespaces. However, it is allowed to use spaces in between.

Also the user may use a bracket-separated form of the request, if it is more convenient:

(m:outtmp),(m;outhum),(z:cache.reading),(n:ccfoxy),(i:beam)

It is encouraged to use either commas or semicolons between brackets. Moreover, same constraints as above are applied on the device names.

c. Parameters

This section completely describes HTTP parameters which can be used for changing a representation format.

d. GET requests via a RESTful URL

The user may query the service using URL in a format http:///<request>, where <request> is the request string specified in Section 3b.

In order to choose a data representation format, the user may specify in the query string parameters described in Section 3c.

e. POST requests

To query a large set of data or just considering it a more convenient way, one may query devices using a POST method. The URL for POST is http://, same as for the GET request, however the URL should not contain a request string, instead of it request-body must provide "request" parameter containing the request string, along with the parameters from Section 3g. See the POST Request Form for further details.

Note, that content-type "application/x-www-form-urlencoded" must be used in the request body.

f. Headers

The only thing which can be affected by headers is the content type. Instead of using a "type" parameter, the user may provide an "Accept" header. The content type which has the highest priority will be returned, XML is returned by default. Note that the "type" parameter has a strong priority over the headers, thus if both present, the content type specified in the parameter will be returned.

Below is an example of "Accept" header for which the response will be in the HTML format:

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

For more information refer to HTTP RFC.

g. Response

The response XML format is completely described at http://www-bd.fnal.gov/issues/wiki/DAQDataXMLMarshalling. The HTML, JSON and plaintext formats are the result of transformation of the initial XML.

h. HTTP Status Codes

This section describes HTTP status codes which may be generated by a web service.

4. Status Page

For the purpose of statistics gathering, there exists a status page, which returns an XML document with information about entries and devices currently kept in cache. Page URL is http://.

5. Dynamically Updated Page

Here is an example of dynamically updated page. It uses an AJAX technology to query the service and continuously provides the user with the most recent data.

6. Examples

• M:OUTTMP
• Several Devices
• Bracket-Separated Request

7. Links

1. Project Report
2. Complete Project Description
3. Data Request Format 2.0
4. DAQ Data XML Marshalling Rules
5. DAQ Data Protocol
6. RFC 2616
7. http://json.org/