Working with Metacards

Working with Metacards

A Metacard is a container for metadata. CatalogProviders accept Metacards as input for ingest, and Sources search for metadata and return matching Results that include Metacards. For more information, see Data Components in the Users Guide.

Creating Metacards

The quickest way to create a Metacard is to extend or construct the MetacardImpl object. MetacardImpl is the most commonly used and extended Metacard implementation in the system because it provides a convenient way for developers to retrieve and set Attributes without having to create a new MetacardType.  MetacardImpl uses BASIC_METACARD as its MetacardType (see below).

Metacard Extensibility

Often times the BASIC_METACARD MetacardType does not provide all the functionality or attributes necessary for a specific task. Sometimes for performance or convenience purposes it is necessary to create custom attributes even if others will not be aware of those attributes. One example would be if a user wanted to optimize a search for a date field that did not fit the definition of CREATED, MODIFIED, EXPIRATION, or EFFECTIVE.  The user could create an additional java.util.Date attribute in order to query the attribute separately. 

Metacard objects are extensible because they allow clients to store and retrieve standard and custom key/value Attributes from the Metacard.  All Metacards must return a MetacardType object that includes AttributeDescriptor for each Attribute, indicating it's key and value type.  AttributeType support is limited to those types defined by the Catalog, as documented in Data Components in the Users Guide.

New MetacardType implementations can be made by implementing the MetacardType interface.

Metacard Type Registry

MetacardTypes should be registered with the MetacardTypeRegistry.  The MetacardTypeRegistry makes those MetacardTypes available to other DDF CatalogFramework components.  Other components that need to know how to interpret metadata or Metacards should lookup the appropriate MetacardType from the registry.  By having these MetacardTypes available to the CatalogFramework, these components can be aware of the custom attributes. 

The MetacardTypeRegistry is accessible as an OSGi service.  The following blueprint snippet shows how to inject that service into another component. 

<bean id="sampleComponent class="ddf.catalog.SampleComponent">
    <argument ref="metacardTypeRegistry" />
</bean>
 
<!-- Access MetacardTypeRegistry -->
<reference id="metacardTypeRegistry" interface="ddf.catalog.data.MetacardTypeRegistry"/>

The reference to this service can then be used to register new MetacardTypes or to lookup existing ones. 

Typically new MetacardTypes will be registered by CatalogProviders or Sources indicating they know how to persist, index, and query attributes from that type.  Typically Endpoints or InputTransformers will use the lookup functionality to access a MetacardType based on a parameter in the incoming metadata.  Once the appropriate MetacardType is discovered and obtained from the registry, the component will know how to translate incoming raw metadata into a DDF Metacard.

Limitations

A given developer does not have all the information necessary to programmatically interact with any arbitrary Source. Developers hoping to query custom fields from extensible Metacards of other Sources cannot easily accomplish that task with the current API. A developer cannot question a random Source for all its queryable fields. A developer only knows about the MetacardTypes in which that individual developer has used or created previously. 

The only exception to this limitation is the Metacard.ID field, which is required in every Metacard that is stored in a Source. A developer can always request Metacards from a Source for which that developer has the Metacard.ID value.  The developer could also perform a wildcard search on the Metacard.ID field if the Source allows.

Processing Metacards

As Metacard objects are created, updated, and read throughout the Catalog, care should be taken by all Catalog Components to interrogate the MetacardType to ensure that additional Attributes are processed accordingly.

BasicTypes

The Catalog includes definitions of several Basic Types all found in the ddf.catalog.data.BasicTypes class.