groovyx.net.http
Class ParserRegistry

java.lang.Object
  groovyx.net.http.ParserRegistry

public class ParserRegistry
extends Object

Keeps track of response parsers for each content type. Each parser should should be a closure that accepts an HttpResponse instance, and returns whatever handler is appropriate for reading the response data for that content-type. For example, a plain-text response should probably be parsed with a Reader, while an XML response might be parsed by an XmlSlurper, which would then be passed to the response closure.

Note that all methods in this class assume HttpResponse.getEntity() return a non-null value. It is the job of the HTTPBuilder instance to ensure a NullPointerException is not thrown by passing a response that contains no entity.

You can see the list of content-type parsers that are built-in to the ParserRegistry class in buildDefaultParserMap().

Author:

Tom Nichols

See Also:

ContentType

Field Summary

protected static CatalogResolver	catalogResolver This CatalogResolver is static to avoid the overhead of re-parsing the catalog definition file every time.
static String	DEFAULT_CHARSET The default charset to use when no charset is given in the Content-Type header of a response.
protected Closure	DEFAULT_PARSER The default parser used for unregistered content-types.
protected static org.apache.commons.logging.Log	log

Constructor Summary

ParserRegistry()

Method Summary

static void	addCatalog(URL catalogLocation) Add a new XML catalog definiton to the static XML resolver catalog.
protected Map<String,Closure>	buildDefaultParserMap() Returns a map of default parsers.
Closure	getAt(Object contentType) Retrieve a parser for the given response content-type string.
static CatalogResolver	getCatalogResolver() Access the default catalog used by all HTTPBuilder instances.
static String	getCharset(HttpResponse resp) Helper method to get the charset from the response.
static String	getContentType(HttpResponse resp) Helper method to get the content-type string from the response (no charset).
Closure	getDefaultParser() Get the default parser used for unregistered content-types.
Iterator<Map.Entry<String,Closure>>	iterator() Iterate over the entire parser map
Map<String,String>	parseForm(HttpResponse resp) Default parser used to decode a URL-encoded response.
GPathResult	parseHTML(HttpResponse resp) Parse an HTML document by passing it through the NekoHTML parser.
JSON	parseJSON(HttpResponse resp) Default parser used to decode a JSON response.
InputStream	parseStream(HttpResponse resp) Default parser used for binary data.
Reader	parseText(HttpResponse resp) Default parser used to handle plain text data.
GPathResult	parseXML(HttpResponse resp) Default parser used to decode an XML response.
Closure	propertyMissing(Object key) Alias for getAt(Object) to allow property-style access.
void	propertyMissing(Object key, Closure value) Alias for putAt(Object, Closure) to allow property-style access.
void	putAt(Object contentType, Closure value) Register a new parser for the given content-type.
static void	setDefaultCharset(String charset) Set the charset to use for parsing character streams when no charset is given in the Content-Type header.
void	setDefaultParser(Closure defaultParser) Set the default parser used for unregistered content-types.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_PARSER

protected final Closure DEFAULT_PARSER

The default parser used for unregistered content-types. This is a copy of parseStream(HttpResponse), which is like a no-op that just returns the unaltered response stream.

DEFAULT_CHARSET

public static final String DEFAULT_CHARSET

The default charset to use when no charset is given in the Content-Type header of a response. This can be modifid via setDefaultCharset(String).

See Also:

Constant Field Values

log

protected static final org.apache.commons.logging.Log log

catalogResolver

protected static CatalogResolver catalogResolver

This CatalogResolver is static to avoid the overhead of re-parsing the catalog definition file every time. Unfortunately, there's no way to share a single Catalog instance between resolvers. The Catalog class is technically not thread-safe, but as long as you do not parse catalog files while using the resolver, it should be fine.

Constructor Detail

ParserRegistry

public ParserRegistry()

Method Detail

setDefaultCharset

public static void setDefaultCharset(String charset)

Set the charset to use for parsing character streams when no charset is given in the Content-Type header.

Parameters:

charset - the charset to use, or null to use DEFAULT_CHARSET

getCharset

public static String getCharset(HttpResponse resp)

Helper method to get the charset from the response. This should be done when manually parsing any text response to ensure it is decoded using the correct charset. For instance:

 Reader reader = new InputStreamReader( resp.getEntity().getContent(), 
   ParserRegistry.getCharset( resp ) );

Parameters:

resp -

getContentType

public static String getContentType(HttpResponse resp)

Helper method to get the content-type string from the response (no charset).

Parameters:

resp -

parseStream

public InputStream parseStream(HttpResponse resp)
                        throws IOException

Default parser used for binary data. This simply returns the underlying response InputStream.

Parameters:

resp -

Returns:

an InputStream the binary response stream

Throws:

IllegalStateException

IOException

See Also:

ContentType.BINARY, HttpEntity.getContent()

parseText

public Reader parseText(HttpResponse resp)
                 throws IOException

Default parser used to handle plain text data. The response text is decoded using the charset passed in the response content-type header.

Parameters:

resp -

Returns:

Throws:

UnsupportedEncodingException

IllegalStateException

IOException

See Also:

ContentType.TEXT

parseForm

public Map<String,String> parseForm(HttpResponse resp)
                             throws IOException

Default parser used to decode a URL-encoded response.

Parameters:

resp -

Returns:

Throws:

IOException

See Also:

ContentType.URLENC

parseHTML

public GPathResult parseHTML(HttpResponse resp)
                      throws IOException,
                             SAXException

Parse an HTML document by passing it through the NekoHTML parser.

Parameters:

resp - HTTP response from which to parse content

Returns:

the GPathResult from calling XmlSlurper.parse(Reader)

Throws:

IOException

SAXException

See Also:

ContentType.HTML, org.cyberneko.html.parsers.SAXParser, XmlSlurper.parse(Reader)

parseXML

public GPathResult parseXML(HttpResponse resp)
                     throws IOException,
                            SAXException,
                            ParserConfigurationException

Default parser used to decode an XML response.

Parameters:

resp - HTTP response from which to parse content

Returns:

the GPathResult from calling XmlSlurper.parse(Reader)

Throws:

IOException

SAXException

ParserConfigurationException

See Also:

ContentType.XML, XmlSlurper.parse(Reader)

parseJSON

public JSON parseJSON(HttpResponse resp)
               throws IOException

Default parser used to decode a JSON response.

Parameters:

resp -

Returns:

Throws:

IOException

See Also:

ContentType.JSON

buildDefaultParserMap

protected Map<String,Closure> buildDefaultParserMap()

Returns a map of default parsers. Override this method to change what parsers are registered by default. A 'parser' is really just a closure that acceipts an HttpResponse instance and returns some parsed data. You can of course call super.buildDefaultParserMap() and then add or remove from that result as well.

Default registered parsers are:

• ContentType.BINARY : parseStream()
• ContentType.TEXT : parseText()
• ContentType.URLENC : parseForm()
• ContentType.XML : parseXML()
• ContentType.JSON : parseJSON()

addCatalog

public static void addCatalog(URL catalogLocation)
                       throws IOException

Add a new XML catalog definiton to the static XML resolver catalog. See the HTTPBuilder source catalog for an example.

Parameters:

catalogLocation - URL of a catalog definition file

Throws:

IOException - if the given URL cannot be parsed or accessed for whatever reason.

getCatalogResolver

public static CatalogResolver getCatalogResolver()

Access the default catalog used by all HTTPBuilder instances.

Returns:

the static CatalogResolver instance

getDefaultParser

public Closure getDefaultParser()

Get the default parser used for unregistered content-types.

Returns:

setDefaultParser

public void setDefaultParser(Closure defaultParser)

Set the default parser used for unregistered content-types.

Parameters:

defaultParser - if

getAt

public Closure getAt(Object contentType)

Retrieve a parser for the given response content-type string. This is called by HTTPBuildre to retrieve the correct parser for a given content-type. The parser is then used to decode the response data prior to passing it to a response handler.

Parameters:

contentType -

Returns:

parser that can interpret the given response content type, or the default parser if no parser is registered for the given content-type. It should NOT return a null value.

putAt

public void putAt(Object contentType,
                  Closure value)

Register a new parser for the given content-type. The parser closure should accept an HttpResponse argument and return a type suitable to be passed as the 'parsed data' argument of a response handler closure.

Parameters:

contentType - content-type string

value - code that will parse the HttpResponse and return parsed data to the response handler.

propertyMissing

public Closure propertyMissing(Object key)

Alias for getAt(Object) to allow property-style access.

Parameters:

key - content-type string

Returns:

propertyMissing

public void propertyMissing(Object key,
                            Closure value)

Alias for putAt(Object, Closure) to allow property-style access.

Parameters:

key - content-type string

value - parser closure

iterator

public Iterator<Map.Entry<String,Closure>> iterator()

Iterate over the entire parser map

Returns: