uk.ac.starlink.hdx

Interface HdxResourceFactory

public interface HdxResourceFactory

Unifies the various factories for constructing HDX and related objects from DOM elements and the URIs contained within them.

Implementations of this interface should be registered by the HdxResourceType.registerHdxResourceFactory(uk.ac.starlink.hdx.HdxResourceFactory) method on the object which represents the type.

Version:

$Id$

Author:

Norman Gray

Method Summary

Modifier and Type	Method and Description
Object	getObject(Element el) Returns the Java object which corresponds to the URL given in the `url' attribute of the given Element, as an Object.

Method Detail

getObject

Object getObject(Element el)
          throws HdxException

Returns the Java object which corresponds to the URL given in the `url' attribute of the given Element, as an Object. If the URL is not one that this accessor can handle, then it should signal this by returning null promptly, without error.

The DOM element should be regarded as the master representation of the data object, thus it is the Element which client code should generally hold on to, rather than the Java object, which can be extracted from the element using this method at any time. That is why this is a get... method rather than being referred to as a constructor.

Implementation note: When implementing this class, this intended usage should be borne in mind, and result of the transformation from Element to Object should be aggressively cached. The association between a DOM element and a Java object is not, in general, volatile. However, do note that in the implementations of some types, the DOM is modifiable (see HdxFacade), and any changes of state by this route should be respected.

Usage note: This interface is a helper interface, and should generally not be called directly by client code. Instead, call HdxFactory.getObject(org.w3c.dom.Element), which provides or constructs required context, and which may have other methods for constructing or recovering the object.

The URL will typically be an absolute URL (but not necessarily, since there are cases where there is no absolute URL readily definable), so that this method will not generally need to do any relative-to-absolute or URI-to-URL resolution. It is free to do so if this makes the method more robust, but in this case it is permitted to return null. There will also be a `uri' attribute on the element; if there is no `url' attribute, the method is free to use the `uri' attribute, but is not required to, and may ignore it.

An object may act as a factory for more than one element type, distinguishing between them by testing the name of the element parameter.

The Element will correspond to the HdxResourceType which this element was registered as handling (or one of them, if it was registered as handling more than one type).

XXX Note that this method will not work for URIs referring to the contents of transient jar files (for example): for that we will shortly add a similar method which is additionally passed an InputStream.

Parameters:

el - an element containing the information required to construct a Java object

Returns:

an object of the correct type, as an Object, or null if this constructor cannot handle this URL

Throws:

HdxException - if the constructor should be able to handle this element but is unable to. This should also be thrown for any this-can't-happen errors, such as the element argument being an unrecognised type.

PluginException - (unchecked exception) if the constructor returned an object which did not match the required class registered using HdxResourceType.setConstructedClass(java.lang.Class).