uk.ac.starlink.array
Class BridgeNDArray.BridgeNDArrayHdxFacade

java.lang.Object
  extended by uk.ac.starlink.hdx.AbstractHdxFacade
      extended by uk.ac.starlink.array.BridgeNDArray.BridgeNDArrayHdxFacade
All Implemented Interfaces:
Cloneable, HdxFacade
Enclosing class:
BridgeNDArray

protected class BridgeNDArray.BridgeNDArrayHdxFacade
extends AbstractHdxFacade


Constructor Summary
BridgeNDArray.BridgeNDArrayHdxFacade(HdxResourceType type)
           
 
Method Summary
 HdxResourceType getHdxResourceType()
          Obtains the HdxResourceType which this is a facade for.
 Object getObject(Element el)
          Obtains the object which the given Element is a facade for.
 Object synchronizeElement(Element el, Object memento)
          Adds attributes and children to the given element, to represent the current state of the object as a DOM.
 
Methods inherited from class uk.ac.starlink.hdx.AbstractHdxFacade
addChildBefore, clone, getSource, replaceChild, setAttribute
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BridgeNDArray.BridgeNDArrayHdxFacade

public BridgeNDArray.BridgeNDArrayHdxFacade(HdxResourceType type)
Method Detail

synchronizeElement

public Object synchronizeElement(Element el,
                                 Object memento)
                          throws HdxException
Description copied from interface: HdxFacade
Adds attributes and children to the given element, to represent the current state of the object as a DOM. The implementing object should add or update elements and attributes on the given element using the Document obtained by invoking Node.getOwnerDocument() on the element. This Document will in fact be an instance of HdxDocument, which implements the standard Document interface with the addition of HdxDocument.createElement(HdxFacade), which the implementing code is therefore free to use (this is an understatement -- the entire point of this interface is to give an implementing class the opportunity of using this method).

The element will have the type this.getHdxResourceType().xmlname().

This method is called frequently, and the implementing object should therefore take care to do no more work than is necessary. To assist in this, the caller will preserve a memento on behalf of the implementor. This memento is the object returned by this method, which is re-presented when the synchronizeElement method is next called (this is an example of `memento' pattern, although that is more commonly associated with undo actions than the cache-like operation described here). If the implementing object needs to preserve some state, to remind it of its own state when it last synchronised the element, then it should wrap that state in some object or other and return it from this method. This might be as simple as a hash-code.

The first time this method is called, the memento will be null.

The returned memento may be null if, for example, the implementor can extract all its relevant state information from the DOM it receives in the Element; or if the object is immutable, so that the Element attributes and children are correct if they are there at all. This null memento will be duly returned to the implementor on any future invocation. In such a case, the implementor might need to be careful to distinguish this returned null memento from the null memento provided when the method is called the first time.

It is perfectly feasible for the implementor to return itself as the memento.

Specified by:
synchronizeElement in interface HdxFacade
Specified by:
synchronizeElement in class AbstractHdxFacade
Parameters:
el - an element which is to be made consistent with the current state of the object
memento - either null, if this is the first time this method has been called, or the object which was returned by this method last time it was called (which may be null if that is what the method chose to return)
Returns:
an object or null, which is to be returned to the method next time it is called
Throws:
HdxException - if it is for some reason impossible to update the DOM. The method should regard this as something akin to a `can't happen' error: this thrown exception will be converted to a DOMException if that is reasonable for the caller, but if not, may be converted to a PluginException.

getObject

public Object getObject(Element el)
                 throws HdxException
Description copied from interface: HdxFacade
Obtains the object which the given Element is a facade for. The caller should know what (Java) type of object this will be (that is, Ndx, HdxContainer, or the like), and will therefore be able to cast the result appropriately.

The returned element must match the class appropriate for the Hdx type this element corresponds to. That is the return value obj must be such that the following are true

for any instance facade of this interface, and if el is the Element which this facade is linked to.

Specified by:
getObject in interface HdxFacade
Specified by:
getObject in class AbstractHdxFacade
Parameters:
el - an Element which is to be transformed into an object
Returns:
the Java object which this element is a facade for. The object must not be null.
Throws:
HdxException - if the facade does not know how to recover the object type it has been asked for. This will also happen if the element el does not correspond to a known HdxResourceType.

getHdxResourceType

public HdxResourceType getHdxResourceType()
Description copied from interface: HdxFacade
Obtains the HdxResourceType which this is a facade for.

This is not (just) a convenience method. Although the same information is retrievable by calling HdxFacade.getSource(java.net.URI), and calling HdxResourceType.match(Element) on the top element obtained from it,

  1. calling getSource may involve significant processing, and
  2. it is not trivial to retrieve the top element from a Source, since the root of the resulting document (matched by the XPath /) is not guaranteed to be the `top' node of the DOM (see DOMSource.DOMSource(Node))

Specified by:
getHdxResourceType in interface HdxFacade
Specified by:
getHdxResourceType in class AbstractHdxFacade
Returns:
the HdxResourceType this facade represents


Copyright © 2015 Central Laboratory of the Research Councils. All Rights Reserved.