----
h1. Metadata 1.4 Developers Guide

{code}import gov.nih.nci.cadsr.umlproject.domain.*;
import gov.nih.nci.cagrid.cadsr.client.*;
import gov.nih.nci.cagrid.cadsrservice.*;
import gov.nih.nci.cagrid.discovery.client.*;
import gov.nih.nci.cagrid.metadata.*;
import gov.nih.nci.cagrid.metadata.common.*;
import gov.nih.nci.cagrid.metadata.dataservice.*;
import gov.nih.nci.cagrid.metadata.exceptions.*;

import org.apache.axis.message.addressing.Address;
import org.apache.axis.message.addressing.EndpointReferenceType;
import org.apache.axis.types.URI.MalformedURIException;
{code}
{include:metadata14:Changes in caGrid 1.4}
h2. Working with caGrid Metadata

As described in the [metadata model documentation|Metadata Models], caGrid services all expose a standard ServiceMetadata model that describes the services capabilities. In order to interact with this metadata, there are a number of utility APIs provided.


All caGrid services are expected to expose a standard set of service metadata. Details about this design and the specifics of the metadata can be found in the metadata model documentation. This section describes the high-level API, which can be used to access and manipulate instances of this metadata. The APIs described here can be used access these models from services, and serialize and deserialize them to and from XML. These methods complement the [Discovery Client|#Discovery Client]. Once an EPR (End Point Reference) is returned from the Discovery API, these methods can be used to access and inspect the full metadata.


The ResourcePropertyHelper API, not detailed here, is the lower level API, which can be used to directly gather information about ResourceProperties (this is how metadata is exposed in caGrid). The MetadataUtils, described here, leverage this API, and expose some of its exceptions. The possible exceptions generated by the metadata utility methods are detailed below.

!ResourcePropertyHelper_exceptions.png!

A non-discerning client may simply opt to catch _ResourcePropertyRetrievalException_, as it is the base-checked exception. An additional non-checked exception, _InternalRuntimeException_, can also be thrown but is solely used to represent an internal logic error in the APIs. It is not expected clients can "recover" from such an exception. As such, clients should not attempt to catch this runtime exception for any other reason than to mask the problem.
_QueryInvalidException_ is thrown if an invalid XPath query is issued. Problems originating from remote services are thrown in the subclass _RemoteResourcePropertyRetrievalException_. During general use of the metadata utilities, this is the most likely exception clients may see, as it is thrown if a service is not properly exposing the proper metadata. Clients leveraging the lower level resource property APIs should take care to appropriately address each type of exception if they are communicating with services. For example, even though it is a caBIG requirement to expose the standard service metadata, clients should properly handle the case where it is not present. Asking for specific metadata that a service does not provide would yield an _InvalidResourcePropertyException_.

{include:metadata14:API Usage Examples}
{include:metadata14:Discovery API}
{include:metadata14:Introduce Support}