OODT Query Service - Query Servlet

Query Servlet

The query servlet enables you to inject generic queries into the OODT framework using HTTP. This enables you to query for profiles and products without requiring a Java, RMI, or CORBA enabled application.

Requirements

The query servlet accepts various parameters for a query and turns them into an XMLQuery object. It uses this object internally to send the query around the network and to gather results. It then returns a text/xml representation of the XMLQuery object (for product queries) or a text/xml representation of all matching profiles (for profile queries).

That means you must be able to process XML in order to use the query servlet. Luckily, this isn't an onerous restriction, as many languages are more than capable of doing so.

For more details, view the Javadocs for the jpl.oodt.servlets.QueryServlet class.

Using the Query Servlet

In order to use the query servlet, you need to specify three parameters:

You need to know the type of the query you want to make. You will use a string value of profile to make a profile query, and product to make a product query. You specify your choice in a parameter named type .
You need to know the name of the object that should receive the query. This takes the for m of urn:eda: protocol : name such as urn:eda:corba:PDS.Profile or urn:eda:rmi:NCI-ImageServer . You specify the object name in a parameter named object .
You need the actual query you want to send. You can express this in two ways:
1. As an keyword query expression like TARGET_NAME = MARS . You specify the query expression in a parameter named keywordQuery .
2. As a text serialized XMLQuery object . You specify the XML document in a parameter named query .
Using the latter enables you to fully specify all sorts of parameters in the query. The former, though, is far easier to use.

You then URL encode parameters' values and make either an HTTP GET or POST request to the query servlet. If all goes according to plan, the servlet will execute the query and return to you a text/xml document describing the results. You can then manipulate that document as you see fit. For profile queries, the return value is a < profiles > document with zero or more matching profiles. For product queries, it's a < query > document with the original XMLQuery object with any product results in the < queryResults > section.

Query Examples

Let's look at a couple of concrete examples. In the first example, we'll run a profile query against some planetary data servers; the second example will run a product query for cancer biomarkers.

Planetary Profile Query

Suppose you wanted to know what PDS product servers supported the query el ement ONLINE_FILE_SPECIFICATION_NAME . You could pass that element to the PDS system profile server named urn:eda:rmi:PDS.System.Profile using the query servlet at http://starbrite.jpl.nasa.gov/servlet/jpl.oodt.servlets.QueryServlet . You can formulate the HTTP GET request in a URL as follows:

http://starbrite.jpl.nasa.gov/servlet/jpl.oodt.servlets.QueryServlet? object=urn:eda:rmi:PDS.System.Profile & type=profile & keywordQuery=ONLINE_FILE_SPECIFICATION_NAME+%3D+ANY

Note that we've broken this URL into multiple lines for readability. There should be no linebreaks in a real URL. Note the following about this URL:

The question-mark separates the request URI from its parameters.
The parameters may come in any order.
The object parameter names the target of the query; in this case, the RMI product server named urn:eda:rmi:PDS.System.Profile .
The type parameter specifies that we're doing a profile search .
The keywordQuery parameter identifies the query expression. Note the URL encoding: the spaces become + symbols, and the equals sign become %3D .

The response from such a query is an XML document; this XML document describes matching profiles and may take a form such as the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE profiles PUBLIC "-//JPL//DTD OODT Profile 1.1//EN"
"http://starshine.jpl.nasa.gov:80/dtd/prof.dtd">

<profiles>
  <profile>
    <profAttributes>
      <profId>1.3.6.1.4.1.1306.2.1.1.7</profId>
      <profType>profile</profType>
      <profStatusId>active</profStatusId>
    </profAttributes>
    <resAttributes>
      <Identifier>PDS.ASU.Product</Identifier>
      <Title>
      PDS Arizona State University Data Node Product Server
      </Title>
      <Format>text/html</Format>
      <resContext>NASA.PDS.ASU</resContext>
      <resClass>system.productServer</resClass>
      <resLocation>
      http://starbrite.jpl.nasa.gov/servlet/
      jpl.oodt.servlets.ProductServlet?object=PDS.ASU.Product
      </resLocation>
      <resLocation>urn:eda:rmi:PDS.ASU.Product</resLocation>
    </resAttributes>
    <profElement>
      <elemName>ONLINE_FILE_SPECIFICATION_NAME</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
    <profElement>
      <elemName>RETURN_TYPE</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemValue>PDS_ZIP</elemValue>
      <elemValue>PDS_LABEL</elemValue>
      <elemValue>RAW</elemValue>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
  </profile>

  <profile>
    <profAttributes>
      <profId>1.3.6.1.4.1.1306.2.1.1.6</profId>
      <profType>profile</profType>
      <profStatusId>active</profStatusId>
    </profAttributes>
    <resAttributes>
      <Identifier>PDS.RS.Product</Identifier>
      <Title>PDS Radio Science Product Server</Title>
      <Format>text/html</Format>
      <resContext>NASA.PDS.RS</resContext>
      <resClass>system.productServer</resClass>
      <resLocation>
      http://starbrite.jpl.nasa.gov/servlet/
      jpl.oodt.servlets.ProductServlet?object=PDS.RS.Product
      </resLocation>
      <resLocation>urn:eda:rmi:PDS.RS.Product</resLocation>
    </resAttributes>
    <profElement>
      <elemName>ONLINE_FILE_SPECIFICATION_NAME</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
    <profElement>
      <elemName>RETURN_TYPE</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemValue>PDS_ZIP</elemValue>
      <elemValue>PDS_LABEL</elemValue>
      <elemValue>RAW</elemValue>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
  </profile>

  <profile>
    <profAttributes>
      <profId>1.3.6.1.4.1.1306.2.1.1.4</profId>
      <profType>profile</profType>
      <profStatusId>active</profStatusId>
    </profAttributes>
    <resAttributes>
      <Identifier>PDS.Atmos.Product</Identifier>
      <Title>PDS Atmospheres Product Server</Title>
      <Format>text/html</Format>
      <resContext>NASA.PDS.Atmos</resContext>
      <resClass>system.productServer</resClass>
      <resLocation>
      http://starbrite.jpl.nasa.gov/servlet/
      jpl.oodt.servlets.ProductServlet?object=PDS.Atmos.Product
      </resLocation>
      <resLocation>urn:eda:rmi:PDS.Atmos.Product</resLocation>
    </resAttributes>
    <profElement>
      <elemName>ONLINE_FILE_SPECIFICATION_NAME</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
    <profElement>
      <elemName>RETURN_TYPE</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemValue>PDS_ZIP</elemValue>
      <elemValue>PDS_LABEL</elemValue>
      <elemValue>RAW</elemValue>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
  </profile>

  <profile>
    <profAttributes>
      <profId>1.3.6.1.4.1.1306.2.1.1.3</profId>
      <profType>profile</profType>
      <profStatusId>active</profStatusId>
    </profAttributes>
    <resAttributes>
      <Identifier>PDS.NAIF.Product</Identifier>
      <Title>PDS NAIF Product Server</Title>
      <Format>text/html</Format>
      <resContext>NASA.PDS.NAIF</resContext>
      <resClass>system.productServer</resClass>
      <resLocation>
      http://starbrite.jpl.nasa.gov/servlet/
      jpl.oodt.servlets.ProductServlet?object=PDS.NAIF.Product
      </resLocation>
      <resLocation>urn:eda:rmi:PDS.NAIF.Product</resLocation>
    </resAttributes>
    <profElement>
      <elemName>ONLINE_FILE_SPECIFICATION_NAME</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
    <profElement>
      <elemName>RETURN_TYPE</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemValue>PDS_ZIP</elemValue>
      <elemValue>PDS_LABEL</elemValue>
      <elemValue>RAW</elemValue>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
  </profile>

  <profile>
    <profAttributes>
      <profId>1.3.6.1.4.1.1306.2.1.1.2</profId>
      <profType>profile</profType>
      <profStatusId>active</profStatusId>
    </profAttributes>
    <resAttributes>
      <Identifier>PDS.Geo.Product</Identifier>
      <Title>PDS Geosciences Product Server</Title>
      <Format>text/html</Format>
      <resContext>NASA.PDS.GEO</resContext>
      <resClass>system.productServer</resClass>
      <resLocation>
      http://starbrite.jpl.nasa.gov/servlet/
      jpl.oodt.servlets.ProductServlet?object=PDS.Geo.Product
      </resLocation>
      <resLocation>urn:eda:rmi:PDS.Geo.Product</resLocation>
    </resAttributes>
    <profElement>
      <elemName>ONLINE_FILE_SPECIFICATION_NAME</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
    <profElement>
      <elemName>RETURN_TYPE</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemValue>PDS_ZIP</elemValue>
      <elemValue>PDS_LABEL</elemValue>
      <elemValue>RAW</elemValue>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
  </profile>

  <profile>
    <profAttributes>
      <profId>1.3.6.1.4.1.1306.2.1.1.1</profId>
      <profType>profile</profType>
      <profStatusId>active</profStatusId>
    </profAttributes>
    <resAttributes>
      <Identifier>PDS.CN.Product</Identifier>
      <Title>PDS Central Node Archive Product Server</Title>
      <Format>text/html</Format>
      <resContext>NASA.PDS.CN</resContext>
      <resClass>system.productServer</resClass>
      <resLocation>
      http://starbrite.jpl.nasa.gov/servlet/
      jpl.oodt.servlets.ProductServlet?object=PDS.CN.Product
      </resLocation>
      <resLocation>urn:eda:rmi:PDS.CN.Product</resLocation>
    </resAttributes>
    <profElement>
      <elemName>ONLINE_FILE_SPECIFICATION_NAME</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
    <profElement>
      <elemName>RETURN_TYPE</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemValue>PDS_ZIP</elemValue>
      <elemValue>PDS_LABEL</elemValue>
      <elemValue>RAW</elemValue>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
  </profile>

  <profile>
    <profAttributes>
      <profId>1.3.6.1.4.1.1306.2.1.1.10</profId>
      <profType>profile</profType>
      <profStatusId>active</profStatusId>
    </profAttributes>
    <resAttributes>
      <Identifier>PDS.CN.Profile</Identifier>
      <Title>PDS.CN.Profile</Title>
      <Format>text/html</Format>
      <resContext>NASA.PDS.CN</resContext>
      <resClass>system.productServer</resClass>
      <resLocation>
      http://starbrite.jpl.nasa.gov/servlet/
      jpl.oodt.servlets.ProductServlet?object=PDS.CN.Profile
      </resLocation>
      <resLocation>urn:eda:rmi:PDS.CN.Profile</resLocation>
    </resAttributes>
    <profElement>
      <elemName>ONLINE_FILE_SPECIFICATION_NAME</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
    <profElement>
      <elemName>RETURN_TYPE</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemValue>PDS_ZIP</elemValue>
      <elemValue>PDS_LABEL</elemValue>
      <elemValue>RAW</elemValue>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
  </profile>

  <profile>
    <profAttributes>
      <profId>1.3.6.1.4.1.1306.2.1.1.9</profId>
      <profType>profile</profType>
      <profStatusId>active</profStatusId>
    </profAttributes>
    <resAttributes>
      <Identifier>PDS.PPI.Product</Identifier>
      <Title>
      PDS Planetary Plasma Interactions Product Server
      </Title>
      <Format>text/html</Format>
      <resContext>NASA.PDS.PPI</resContext>
      <resClass>system.productServer</resClass>
      <resLocation>
      http://starbrite.jpl.nasa.gov/servlet/
      jpl.oodt.servlets.ProductServlet?object=PDS.PPI.Product
      </resLocation>
      <resLocation>urn:eda:rmi:PDS.PPI.Product</resLocation>
    </resAttributes>
    <profElement>
      <elemName>ONLINE_FILE_SPECIFICATION_NAME</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
    <profElement>
      <elemName>RETURN_TYPE</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemValue>PDS_ZIP</elemValue>
      <elemValue>PDS_LABEL</elemValue>
      <elemValue>RAW</elemValue>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
  </profile>

  <profile>
    <profAttributes>
      <profId>1.3.6.1.4.1.1306.2.1.1.8</profId>
      <profType>profile</profType>
      <profStatusId>active</profStatusId>
    </profAttributes>
    <resAttributes>
      <Identifier>PDS.Img.Product</Identifier>
      <Title>PDS Imaging Product Server</Title>
      <Format>text/html</Format>
      <resContext>NASA.PDS.Img</resContext>
      <resClass>system.productServer</resClass>
      <resLocation>
      http://starbrite.jpl.nasa.gov/servlet/
      jpl.oodt.servlets.ProductServlet?object=PDS.Img.Product
      </resLocation>
      <resLocation>urn:eda:rmi:PDS.Img.Product</resLocation>
    </resAttributes>
    <profElement>
      <elemName>ONLINE_FILE_SPECIFICATION_NAME</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
    <profElement>
      <elemName>RETURN_TYPE</elemName>
      <elemType>CHARACTER</elemType>
      <elemEnumFlag>T</elemEnumFlag>
      <elemValue>PDS_ZIP</elemValue>
      <elemValue>PDS_LABEL</elemValue>
      <elemValue>RAW</elemValue>
      <elemMaxOccurrence>0</elemMaxOccurrence>
    </profElement>
  </profile>
</profiles>

Biomarker Product Query

Suppose you had a query servlet available at http://pancreas/qs , and you want to query the CORBA product server urn:eda:corba:TissueBank with the query expression SeverityLevel = 3 . You can formulate the entire GET request as the following URL:

  http://pancreas/qs?
  type=product&
  object=urn:eda:corba:TissueBank&
  keywordQuery=SeverityLevel+%3D+3

(Again, we've broken the URL for readability.) The result to this query could be an XML document like the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE query PUBLIC "-//JPL//DTD OODT Query 1.0//EN"
                       "http://pancreas/dtd/query.dtd">

<query>
  <queryAttributes>
    <queryId>UNKNOWN</queryId>
    <queryTitle>UNKNOWN</queryTitle>
    <queryDesc>UNKNOWN</queryDesc>
    <queryType>QUERY</queryType>
    <queryStatusId>ACTIVE</queryStatusId>
    <querySecurityType>UNKNOWN</querySecurityType>
    <queryRevisionNote>
    1999-12-12 JSH V1.0 Under Development
    </queryRevisionNote>
    <queryDataDictId>UNKNOWN</queryDataDictId>
  </queryAttributes>
  <queryResultModeId>ATTRIBUTE</queryResultModeId>
  <queryPropogationType>BROADCAST</queryPropogationType>
  <queryPropogationLevels>N/A</queryPropogationLevels>
  <queryMimeAccept>*/*</queryMimeAccept>
  <queryMaxResults>100</queryMaxResults>
  <queryResults>0</queryResults>
  <queryKWQString>SeverityLevel = 3</queryKWQString>
  <querySelectSet>
    <queryElement>
      <tokenRole>LITERAL</tokenRole>
      <tokenValue>3</tokenValue>
    </queryElement>
    <queryElement>
      <tokenRole>elemName</tokenRole>
      <tokenValue>SeverityLevel</tokenValue>
    </queryElement>
    <queryElement>
      <tokenRole>RELOP</tokenRole>
      <tokenValue>EQ</tokenValue>
    </queryElement>
  </querySelectSet>
  <queryFromSet/>
  <queryWhereSet/>
  <queryResultSet>
    <resultElement>
      <resultId>1</resultId>
      <resultMimeType>text/plain</resultMimeType>
      <profId>TissueBank</profId>
      <identifier/>
      <resultHeader>
        <headerElement>
          <elemName>UNKNOWN</elemName>
          <elemType>TEXT</elemType>
        </headerElement>
      </resultHeader>
      <Resultvalue xml:space="preserve">
      PatientIDs=[1,2,4,7,11,19,22]</resultValue>
    </resultElement>
  </queryResultSet>
</query>

Instead of using the keywordQuery parameter, you can create your own XMLQuery document and pass it in as the query parameter instead. The query document would look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE query PUBLIC "-//JPL//DTD OODT Query 1.0//EN"
                       "http://pancreas:80/dtd/query.dtd">

<query>
  <queryAttributes>
    <queryId>expr1</queryId>
    <queryTitle>Command-line Expression Query</queryTitle>
    <queryDesc>
    The expression for this query came from the command-line.
    </queryDesc>
    <queryType>QUERY</queryType>
    <queryStatusId>ACTIVE</queryStatusId>
    <querySecurityType>UNKNOWN</querySecurityType>
    <queryRevisionNote>
    1999-12-12 JSH V1.0 Under Development
    </queryRevisionNote>
    <queryDataDictId>UNKNOWN</queryDataDictId>
  </queryAttributes>
  <queryResultModeId>ATTRIBUTE</queryResultModeId>
  <queryPropogationType>BROADCAST</queryPropogationType>
  <queryPropogationLevels>N/A</queryPropogationLevels>
  <queryMimeAccept>*/*</queryMimeAccept>
  <queryMaxResults>100</queryMaxResults>
  <queryResults>0</queryResults>
  <queryKWQString>SeverityLevel = 3</queryKWQString>
  <querySelectSet/>
  <queryFromSet/>
  <queryWhereSet>
    <queryElement>
      <tokenRole>elemName</tokenRole>
      <tokenValue>SeverityLevel</tokenValue>
    </queryElement>
    <queryElement>
      <tokenRole>LITERAL</tokenRole>
      <tokenValue>3</tokenValue>
    </queryElement>
    <queryElement>
      <tokenRole>RELOP</tokenRole>
      <tokenValue>EQ</tokenValue>
    </queryElement>
  </queryWhereSet>
  <queryResultSet/>
</query>

Passing such a long string as a URL parameter in a GET request can be tricky, though. For such long parameters, it's better to use a POST request instead. See your HTTP API documentation for details on formulating POST requests.