h1. Discovery
----

h2. Overview

Often the address of a service of interest is not a "well known" value, and is something that is discovered at runtime. caGrid provides the means to discover services of interest by querying a live registry of available caGrid services. All caGrid services are required to publish standard metadata (described in the caGrid Metadata Design Document) that describes their functionality. This information is aggregated in the registry Index Service, and can be used to find out information about the currently running services, including their current Endpoint References (EPRs). Building on this information, a Discovery API is provided with caGrid that facilitates the querying of this information toward the aim of discovering service EPRs.


h2. Client API

The Discovery API is intended to be used by any applications or services that wish to consume of data, analytics, and core services provided by caGrid. While there are still cases when interacting with a particular instance of a service is desired, the Discovery API provides a means by which applications can locate services by the information or capabilities they provide. One of the key advantages of the grid approach to caBIG is the dynamic discovery of available resources.

{image-with-caption-link-to-larger:tablealign=left|pagename=imagegallery:300px-Discovery_Process.png|attachmentname=300px-Discovery_Process.png|caption=Discovery Process on caGrid|largepagename=imagegallery:Discovery_Process.png|largeattachmentname=Discovery_Process.png}In order to make use of the Discovery API, the discovery process must be "bootstrapped" using a well-known service address of an Index Service. The default constructor of the DiscoveryClient, the main interface to the Discovery API, should default to the official NCI Index Service. However, this behavior can be modified by using the constructor that takes the Index Service URL, or by calling the appropriate setter method (setIndexEPR). Additional details on this, as well as all Discovery API information, can be found in the Discovery section of the caGrid 1.1 Programmer's Guide.

\\


h2. Basic Use

The simplest discovery scenario is to just query the Index Service for all registered services. The boolean value specified in line 3 of the example, indicates whether services should be ignored if they do not expose the caGrid standard metadata. In most application scenarios, a value of "true" is used, as services without standard metadata are either: not compliant, not properly configurable, or inaccessible (e.g. behind a misconfigured firewall).

{code}
String indexUrl = "http://cagrid-index.nci.nih.gov:8080/wsrf/services/DefaultIndexService";
DiscoveryClient client = new DiscoveryClient(indexUrl);
EndpointReferenceType[] allServices = client.getAllServices(true);
for (EndpointReferenceType epr: allServices) {
System.out.println(epr.getAddress().toString());
}
{code}

There are many discovery operations available in the DiscoveryClient. They provide a range of capabilities from "full text search" suitable for a freeform webpage-like interface, simple text-based criteria such as specifying operation names or concept code, and complex criteria ("query by example") such as specification of point of contact information or UML class criteria. While there are many discovery methods that take a UMLClass prototype, to discover services based on data types, an example is shown in the example below. This method, discoverServiceByOperationInput, locates services that provide an operation that takes, as input, an instance of the specified data type. The example below shows services that provide operations that take caBIO's Gene instances as input. This prototype object can be as partially populated as desired (such as only specifying the package name, or being more explicit in specifying the exact project name and version).

{code}
EndpointReferenceType[] services = null;
UMLClass inputClass = new UMLClass();
inputClass.setClassName("Gene");
inputClass.setPackageName("gov.nih.nci.cabio.domain");

services = client.discoverServicesByOperationInput(inputClass);
{code}

Additionally, there are methods to discover services by "type". For example, there are several methods named like discoverDataServices*, which only return services that implement the standard Data Service operations. Services may also be discovered by identifying the concept code matching the service type of interest, and invoking the discoverServicesByConceptCode method, which searches for services based on concepts applied to the service. There is a concept representing "Grid Service" in the ontology and derived concepts such as "Analytical Grid Service" and "Data Grid Service". It is expected additional concepts will be derived in the future, as driven by the community.