# Google Data APIs Client Library (1.43.0)

## com.google.gdata.client
Interface Service.GDataRequest

All Known Implementing Classes:
  GoogleGDataRequest, HttpGDataRequest

Enclosing class:
  Service

    public static interface Service.GDataRequest

The GDataRequest interface represents a streaming connection to a GData service that can be used either to send request data to the service using an OutputStream (or XmlWriter for XML content) or to receive response data from the service as an InputStream (or ParseSource for XML data). The calling client then has full control of the request data generation and response data parsing. This can be used to integrate GData services with an external Atom or RSS parsing library, such as Rome.

A GDataRequest instance will be returned by the streaming client APIs of the Service class. The basic usage pattern is:

     GDataRequest request = ...     // createXXXRequest API call
     try {
        OutputStream requestStream = request.getRequestStream();
        // stream request data, if any
        request.execute()                // execute the request
        InputStream responseStream = request.getResponseStream();
        // process the response data, if any
     }
     catch (IOException ioe) {
        // handle errors writing to / reading from server
     } catch (ServiceException se) {
        // handle service invocation errors
     } finally {
       request.end();
     }

See Also:
  `Service.createEntryRequest(URL)`, `Service.createFeedRequest(URL)`, `Service.createInsertRequest(URL)`, `Service.createUpdateRequest(URL)`, `Service.createDeleteRequest(URL)`

Nested Class Summary
`static class` `Service.GDataRequest.RequestType` The RequestType enumeration defines the set of expected GData request types.

Method Summary
`void` `end()` Ends all processing associated with this request and releases any transient resources (such as open data streams) required for execution.
`void` `execute()` Executes the GData service request.
`ParseSource` `getParseSource()` Returns a parse source that can be used to read response data from the GData service.
`ContentType` `getRequestContentType()` Returns the `ContentType` of the data that will be written to the service by this request or `null` if no data is written to the server by the request.
`java.io.OutputStream` `getRequestStream()` Returns a stream that can be used to write request data to the GData service.
`java.net.URL` `getRequestUrl()` Returns the `URL` that is the target of the GData request
`ContentType` `getResponseContentType()` Returns the content type of the GData response.
`DateTime` `getResponseDateHeader(java.lang.String headerName)` Returns the value of a header containing a header or `null` if no response header of this type exists or it could not be parsed as a valid date.
`java.lang.String` `getResponseHeader(java.lang.String headerName)` Returns the value of the specified response header name or `null` if no response header of this type exists.
`java.io.InputStream` `getResponseStream()` Returns an input stream that can be used to read response data from the GData service.
`void` `setConnectTimeout(int timeout)` Sets the number of milliseconds to wait for a connection to the remote GData service before timing out.
`void` `setEtag(java.lang.String etag)` Sets the entity tag value that will be used to conditionalize the request if not `null`.
`void` `setHeader(java.lang.String name, java.lang.String value)` Sets a request header (and logs it, if logging is enabled)
`void` `setIfModifiedSince(DateTime conditionDate)` Sets the If-Modified-Since date precondition to be applied to the request.
`void` `setPrivateHeader(java.lang.String name, java.lang.String value)` Sets request header (and log just the name but not the value, if logging is enabled)
`void` `setReadTimeout(int timeout)` Sets the number of milliseconds to wait for a response from the remote GData service before timing out.

Method Detail

### setConnectTimeout

    void setConnectTimeout(int timeout)

  Sets the number of milliseconds to wait for a connection to the remote GData service before timing out.

  Parameters:
    `timeout` - the read timeout. A value of zero indicates an infinite timeout.
  Throws:
    `java.lang.IllegalArgumentException` - if the timeout value is negative.
  See Also:
    `URLConnection.setConnectTimeout(int)`

### setReadTimeout

    void setReadTimeout(int timeout)

  Sets the number of milliseconds to wait for a response from the remote GData service before timing out.

  Parameters:
    `timeout` - the read timeout. A value of zero indicates an infinite timeout.
  Throws:
    `java.lang.IllegalArgumentException` - if the timeout value is negative.
  See Also:
    `URLConnection.setReadTimeout(int)`

### setEtag

    void setEtag(java.lang.String etag)

  Sets the entity tag value that will be used to conditionalize the request if not `null`. For a query requests, the tag will cause the target resource to be returned if the resource entity tag does not match the specified value (i.e. if the resource has not changed). For update or delete request types, the entity tag value is used to indicate that the requested operation should occur only if the specified etag value does match the specified value (i.e. if the resource has changed). A request entity tag value may not be associated with other request types.

  Parameters:
    `etag` -

### setIfModifiedSince

    void setIfModifiedSince(DateTime conditionDate)

  Sets the If-Modified-Since date precondition to be applied to the request. If this precondition is set, then the request will be performed only if the target resource has been modified since the specified date; otherwise, a `NotModifiedException` will be thrown. The default value is `null`, indicating no precondition.

  Parameters:
    `conditionDate` - the date that should be used to limit the operation on the target resource. The operation will only be performed if the resource has been modified later than the specified date.

### setHeader

    void setHeader(java.lang.String name,
                   java.lang.String value)

  Sets a request header (and logs it, if logging is enabled)

  Parameters:
    `name` - the header name
    `value` - the header value

### setPrivateHeader

    void setPrivateHeader(java.lang.String name,
                          java.lang.String value)

  Sets request header (and log just the name but not the value, if logging is enabled)

  Parameters:
    `name` - the header name
    `value` - the header value

### getRequestUrl

    java.net.URL getRequestUrl()

  Returns the `URL` that is the target of the GData request

### getRequestStream

    java.io.OutputStream getRequestStream()
                                          throws java.io.IOException

  Returns a stream that can be used to write request data to the GData service.

  Returns:
    OutputStream that can be used to write GData request data.
  Throws:
    `java.io.IOException` - error obtaining the request output stream.

### getRequestContentType

    ContentType getRequestContentType()

  Returns the `ContentType` of the data that will be written to the service by this request or `null` if no data is written to the server by the request.

### execute

    void execute()
                 throws java.io.IOException,
                        ServiceException

  Executes the GData service request.

  Throws:
    `java.io.IOException` - error writing to or reading from GData service.
    `ResourceNotFoundException` - invalid request target resource.
    `ServiceException` - system error executing request.

### getResponseContentType

    ContentType getResponseContentType()
                                       throws java.io.IOException,
                                              ServiceException

  Returns the content type of the GData response.

  Returns:
    ContentType the GData response content type or `null` if no response content.
  Throws:
    `java.lang.IllegalStateException` - attempt to read content type without first calling `execute()`.
    `java.io.IOException` - error obtaining the response content type.
    `ServiceException` - error obtaining the response content type.

### getResponseStream

    java.io.InputStream getResponseStream()
                                          throws java.io.IOException

  Returns an input stream that can be used to read response data from the GData service. Returns null if response data cannot be read as an input stream. Use `getParseSource()` instead.

  The caller is responsible for ensuring that the input stream is properly closed after the response has been read.

  Returns:
    InputStream providing access to GData response input stream.
  Throws:
    `java.lang.IllegalStateException` - attempt to read response without first calling `execute()`.
    `java.io.IOException` - error obtaining the response input stream.

### getResponseHeader

    java.lang.String getResponseHeader(java.lang.String headerName)

  Returns the value of the specified response header name or `null` if no response header of this type exists.

  Parameters:
    `headerName` - name of header
  Returns:
    header value.

### getResponseDateHeader

    DateTime getResponseDateHeader(java.lang.String headerName)

  Returns the value of a header containing a header or `null` if no response header of this type exists or it could not be parsed as a valid date.

  Parameters:
    `headerName` - name of header
  Returns:
    header value.

### getParseSource

    ParseSource getParseSource()
                               throws java.io.IOException,
                                      ServiceException

  Returns a parse source that can be used to read response data from the GData service. Parse source is an abstraction over input streams, readers, and other forms of input.

  The caller is responsible for ensuring that input streams and readers contained in the parse source are properly closed after the response has been read.

  Returns:
    ParseSource providing access to GData response data.
  Throws:
    `java.lang.IllegalStateException` - attempt to read response without first calling `execute()`.
    `java.io.IOException` - error obtaining the response data.
    `ServiceException` - error obtaining the response data.

### end

    void end()

  Ends all processing associated with this request and releases any transient resources (such as open data streams) required for execution.