This package provides a set of classes which can be used to make lightweight queries of an RI 1.0-compliant IVOA registry. They are lightweight in two senses:

1. Few external libraries are required (see Dependencies section below)
2. A very small memory footprint is required for processing, since returned resources are streamed and only those parts required are retained

The way it works is basically:

1. Assemble a SOAP request, as XML
2. Send it to the SOAP endpoint of the registry
3. Stream the SOAP response through a SAX parser.
   - In case of SOAP error, throw an exception based on the response
   - In case of success, stream the response body to a user-supplied SAX parser, which can create objects representing registry resources
4. Take the user-generated resource objects and make them available to calling code.

## Example

For an example of usage, see the source code of the {@link uk.ac.starlink.registry.RegClientTest} class, which allows you to make Search or KeywordSearch queries from the command line (using the main method with the "`-help`" flag will provide usage information). The output is a rudimentary summary of resources and their associated capabilities matching the submitted query. The code uses {@link uk.ac.starlink.registry.BasicRegistryClient}, which is a simple implementation of the more flexible {@link uk.ac.starlink.registry.AbstractRegistryClient} class, and represents registry resources by instances of the {@link uk.ac.starlink.registry.BasicResource} and {@link uk.ac.starlink.registry.BasicCapability} classes. These classes provide more per-resource metadata than is printed by the example program, but still a very limited amount.

## Customisation

If you wish to acquire more information about the returned resources than is available from {@link uk.ac.starlink.registry.BasicResource} and {@link uk.ac.starlink.registry.BasicCapability}, you will need to write your own SOAP response body SAX handler, and make it available by writing a concrete subclass of the {@link uk.ac.starlink.registry.AbstractRegistryClient} class. You can write the SAX ContentHandler any way you like, but you can use the {@link uk.ac.starlink.registry.BasicRegistryClient} implementation as a template if you like.

## Dependencies

The classes in this package do not require Axis or any other SOAP client. Its only dependency is on part of Ray Plante's IVOARegistry library, specifically the part which can convert ADQL/S to ADQL/X for use within a registry Search request. This is done within the {@link uk.ac.starlink.registry.RegistryRequestFactory#adqlsSearch RegistryRequestFactory.adqlsSearch} method. If that method not required (for instance you are using the KeywordSearch operation instead, or you can construct your own ADQL/X), then no external libraries, beyond the J2SE5 itself, are required.

## Status

This is not an all-singing or all-dancing registry client. The focus is on something which does a limited job fast and in a small memory footprint. Use of it will probably require customisation. Anyone is free to use this code in any way they please. I'm happy to provide assistance or advice if I can.

Mark Taylor