Interface DataNode

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      boolean allowsChildren()
      Indicates whether the node can in principle have child nodes.
      void configureDetail​(DetailViewer dv)
      Configures a DetailViewer object to show additional class-specific details associated with this node.
      java.util.Iterator getChildIterator()
      Gets an Iterator over the children of the object, each of which should itself be a DataNode.
      DataNodeFactory getChildMaker()
      Gets the factory which should in general be used to generate descendant nodes.
      CreationState getCreator()
      Retrieves information about how this node was created.
      java.lang.Object getDataObject​(DataType type)
      Returns a data object of a given type which corresponds to this node.
      java.lang.String getDescription()
      Gets a concise description of this object.
      javax.swing.Icon getIcon()
      Gets an Icon which can be used when displaying this node.
      java.lang.String getLabel()
      Gets the label of this object.
      java.lang.String getName()
      Gets the name of this object.
      java.lang.String getNodeTLA()
      Returns a short string indicating what kind of node this is.
      java.lang.String getNodeType()
      Returns a short sentence indicating what kind of node this is.
      java.lang.Object getParentObject()
      Returns an object which is in some sense the parent of the one this node is based on.
      java.lang.String getPathElement()
      Gets the contribution of this node to a pathname.
      java.lang.String getPathSeparator()
      Gets the delimiter string which separates the name of this node from the name of one of its children when constructing a pathname.
      boolean hasDataObject​(DataType type)
      Indicates whether this node can, on request, supply a data object of a particular type.
      void setChildMaker​(DataNodeFactory factory)
      Sets the factory which should in general be used to generate child nodes.
      void setCreator​(CreationState state)
      Stores information about how this node was created.
      void setLabel​(java.lang.String label)
      Sets a label for this object.
      void setParentObject​(java.lang.Object parentObj)
      Sets the object which is in some sense the parent of the one this node is based on.
    • Method Detail

      • allowsChildren

        boolean allowsChildren()
        Indicates whether the node can in principle have child nodes. Note this does not actually mean that it has any children.
        Returns:
        true if the node is of a type which can have child nodes, false otherwise
      • setLabel

        void setLabel​(java.lang.String label)
        Sets a label for this object. This is like a name but is not intrinsic to the object, so users of implementing classes may call this method to impose a label of their own.
        Parameters:
        label - the label to be given to this object
      • getChildIterator

        java.util.Iterator getChildIterator()
        Gets an Iterator over the children of the object, each of which should itself be a DataNode. Should only be called if hasChildren returns true. It is preferred that this method completes quickly, so if constructing the whole list of children may be time-consuming, implementing classes should avoid constructing the whole list before returning the iterator.

        Implementing classes should in general follow this strategy when generating children: the class should get the list of children in whatever way is appropriate for the type of node in question. It should then make use of its childMaker (the DataNodeFactory returned by the getChildMaker method) to turn these into DataNode objects to return as the children rather than using a particular constructor, such as one of its own, to generate them. In this way, children may turn out to be more specific objects of a type known about by DataNodeFactory but not by the implementing class.

        Returns:
        an Iterator over the children. Each object iterated over should be a DataNode. Behaviour is undefined if this method is called on an object for which allowsChildren returns false.
      • getParentObject

        java.lang.Object getParentObject()
        Returns an object which is in some sense the parent of the one this node is based on. The parent is not a DataNode, it is something which may get fed to a DataNodeFactory to create DataNode. If no such object exists, which may well be the case, null should be returned.
        Returns:
        an object which is the parent of this one, or null
      • setParentObject

        void setParentObject​(java.lang.Object parentObj)
        Sets the object which is in some sense the parent of the one this node is based on. The parent is not a DataNode, it is something which may get fed to a DataNodeFactory to create DataNode.
        Parameters:
        parentObj - an object which is the parent of this one
      • getLabel

        java.lang.String getLabel()
        Gets the label of this object. This ought to return the same value getName unless the user of the implementing class has previously called setLabel to change it.
        Returns:
        the label of the object
      • getName

        java.lang.String getName()
        Gets the name of this object. This is an intrinsic property of the object.
        Returns:
        the name of the object
      • getNodeTLA

        java.lang.String getNodeTLA()
        Returns a short string indicating what kind of node this is. The return value should preferably be a Three Letter Acronym. As a rough guideline the return value should indicate what the implementing class is.
        Returns:
        an abbreviated description of the type of this DataNode
      • getNodeType

        java.lang.String getNodeType()
        Returns a short sentence indicating what kind of node this is. The return value should be just a few words. As a rough guideline it should indicate what the implementing class is.
        Returns:
        a short description of the type of this DataNode
      • getDescription

        java.lang.String getDescription()
        Gets a concise description of this object. The form of the description will depend on the type of node, but it might detail the shape or type of data represented, or otherwise give some information additional to the name. It should not include the return value of the getName method, since they may be presented together. It should be on one line, and preferably no longer than around 70 characters. The null value may be returned if there is nothing to say.
        Returns:
        a short string describing this object
      • getIcon

        javax.swing.Icon getIcon()
        Gets an Icon which can be used when displaying this node. This should return an icon suitable for displaying in a JTree, ideally about 16x16 pixels. It should give some indication of the type of node.

        Implementations are encouraged to construct this icon lazily (i.e. not do it until this method is called), since using Icons usually causes a large number of Swing classes to be loaded, and in some circumstances (such as treeview -text) these may never be used.

        Returns:
        an Icon for display
      • getPathElement

        java.lang.String getPathElement()
        Gets the contribution of this node to a pathname. The return value should be the name of this node as it forms part of a path name. This may or may not be equal to the name member variable. Can be null to indicate the no pathname can be formed from this node.
        Returns:
        pathname name of this node
      • getPathSeparator

        java.lang.String getPathSeparator()
        Gets the delimiter string which separates the name of this node from the name of one of its children when constructing a pathname. If null is returned it indicates that no pathname can be formed from this node and one of its children (for instance if it has no children).
        Returns:
        short delimiter string
      • hasDataObject

        boolean hasDataObject​(DataType type)
        Indicates whether this node can, on request, supply a data object of a particular type. The idea is that if this node corresponds to a generic object such as a table, array, etc then components can ascertain that and present it in ways appropriate to that fact. If a DataNode claims to have an object for one of the defined DataTypes, it can in general forget about any special presentation specific to that type, on the grounds that generic node processing will take care of it.

        Invoking this method ought not to create such a data object if that is an expensive process, merely to indicate whether a subsequent invocation of getDataObject(uk.ac.starlink.datanode.nodes.DataType) using the same type is likely to be successful.

        Parameters:
        type - data object type of interest
        Returns:
        true iff a subsequent call of getDataObject(type) is likely to be successful
      • getDataObject

        java.lang.Object getDataObject​(DataType type)
                                throws DataObjectException
        Returns a data object of a given type which corresponds to this node. This method should only be invoked if a prior invocation of hasDataObject(uk.ac.starlink.datanode.nodes.DataType) using the same type has returned true (otherwise an IllegalArgumentException may be thrown). The returned object must be in instance of the class returned by type.getDataClass().
        Parameters:
        type - data object type of interest
        Returns:
        data object of type type
        Throws:
        DataObjectException
      • configureDetail

        void configureDetail​(DetailViewer dv)
        Configures a DetailViewer object to show additional class-specific details associated with this node. Implementing classes should call various methods on the given DetailViewer object to customise it to contain information about the node in question. This will consist of populating the main panel with basic and compact information about this node, and possibly adding further tabbed panes giving alternative views of the data attached to the node. See the documentation for DetailViewer for more information.

        Nodes which don't have much to say about themselves may implement this method as a no-op, though it will generally be a good idea to invoke the superclass's implementation if there is a superclass.

        Parameters:
        dv - the detail viewer which this node is given an opportunity to configure
      • setChildMaker

        void setChildMaker​(DataNodeFactory factory)
        Sets the factory which should in general be used to generate child nodes. This is not necessarily the factory which is used for generating children of this node, since this node may have special procedures for generating children. However it is the factory which should in general be used for creating descendants of this node.

        This method should only be used by applications which wish to restrict the type of node which can appear in a whole subtree of the node hierarchy. The childMaker is normally inherited from parent to child, so for instance customising the childMaker of the tree root by removing certain builders will prevent such nodes from appearing anywhere in the tree.

        Parameters:
        factory - the factory to use for generating children
      • getChildMaker

        DataNodeFactory getChildMaker()
        Gets the factory which should in general be used to generate descendant nodes.
        Returns:
        the factory used for generating children
      • setCreator

        void setCreator​(CreationState state)
        Stores information about how this node was created.
        Parameters:
        state - an object encapsulating the means by which this node was created
      • getCreator

        CreationState getCreator()
        Retrieves information about how this node was created.
        Returns:
        an object encapsulating the means by which this node was created. May be null if no information is available