# Package uk.ac.starlink.registry

package uk.ac.starlink.registry

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 `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 `BasicRegistryClient`, which is a simple implementation of the more flexible `AbstractRegistryClient` class, and represents registry resources by instances of the `BasicResource` and `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 `BasicResource` and `BasicCapability`, you will need to write your own SOAP response body SAX handler, and make it available by writing a concrete subclass of the `AbstractRegistryClient` class. You can write the SAX ContentHandler any way you like, but you can use the `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 `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.

Author
  Mark Taylor

Class
Description
AbstractRegistryClient<R>
Can submit ADQL queries to a registry and return the result as a list of resources.
BasicCapability
Describes a service capability interface belonging to a registry resource.
BasicRegistryClient
RegistryClient concrete subclass which turns registry queries into BasicResource elements.
BasicResource
Basic details of a registry resource record.
RegClientTest
Example standalone utility which uses the registry client code.
RegistryQueryException
Unchecked exception used to contain a checked Exception.
RegistryRequestFactory
Constructs SOAP requests for use with RI 1.0 registries.
ResourceSink<R>
Interface for receiving resources.
SoapClient
Lightweight, freestanding SOAP client which can make simple requests and allows the responses to be processed as a SAX stream.
SoapRequest
Aggregates the information required to make a SOAP request.