Package org.opentrafficsim.editor

Class XsdTreeNode

java.lang.Object
org.djutils.event.LocalEventProducer
org.opentrafficsim.editor.XsdTreeNode
All Implemented Interfaces:
EventProducer
Direct Known Subclasses:
XsdTreeNodeRoot
public class XsdTreeNode extends LocalEventProducer
Underlying data structure object of the editor. Starting with the root node "Ots", all the information is stored in a tree. The tree follows the XSD logic, e.g. "Ots.Network.Link". XsdTreeNode's have a Node object from the XSD DOM tree. From this information it can be derived what the child nodes should be, and which attributes are contained.

This class is mostly straightforward in the sense that there are direct parent-child relations, and that changing an option replaces a node. When an xsd:sequence is part of an xsd:choice or xsd:all, things become complex as the xsd:sequence is a single option. Therefore the xsd:sequence becomes a node visible in the tree, when it's an option under a choice. Furthermore, for each xsd:choice or xsd:all node an XsdTreeNode is created that is not visible in the tree. It stores all options XsdTreeNode's and knows what option is selected. Only one option is ever in the list of children of the parent node.

Copyright (c) 2023-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See OpenTrafficSim License.

Author:
Wouter Schakel

  • Field Details

    • VALUE_CHANGED

      public static final EventType VALUE_CHANGED
      Event when a node value is changed.

    • ATTRIBUTE_CHANGED

      public static final EventType ATTRIBUTE_CHANGED
      Event when an attribute value is changed.

    • OPTION_CHANGED

      public static final EventType OPTION_CHANGED
      Event when an option is changed.

    • ACTIVATION_CHANGED

      public static final EventType ACTIVATION_CHANGED
      Event when an option is changed.

    • MOVED

      public static final EventType MOVED
      Event when a node is moved.

  • Constructor Details

    • XsdTreeNode

      protected XsdTreeNode(Schema schema)
      Constructor for root node, based on an XsdSchema. Note: XsdTreeNodeRoot should be used for the root. The XsdSchema will be available to all nodes in the tree.
      Parameters:
      schema - XSD schema.

  • Method Details

    • getPath

      public List<XsdTreeNode> getPath()
      Returns the path from root to this node.
      Returns:
      list of node along the path.

    • getRoot

      public XsdTreeNodeRoot getRoot()
      Returns the root node.
      Returns:
      root node.

    • isSequence

      public boolean isSequence()
      Returns whether this is a virtual layer node representing a sequence.
      Returns:
      whether this is a virtual layer node representing a sequence

    • isChoice

      public boolean isChoice()
      Returns whether this node is (part of) a choice, i.e. should show an option can be set here.
      Returns:
      whether this node is (part of) a choice, i.e. should show an option can be set here.

    • getOptions

      public List<XsdOption> getOptions()
      Returns a list of options including current selection status.
      Returns:
      list of options including current selection status.

    • setOption

      public void setOption(XsdTreeNode node)
      Sets the node as newly selected option. All current nodes from the choice set are removed from the parent node.
      Parameters:
      node - newly selected node. Must be part of the choice that this node represents.

    • getOption

      public XsdTreeNode getOption()
      Returns the selected option.
      Returns:
      selected option.

    • isSingleChoiceType

      public boolean isSingleChoiceType()
      Returns whether this node only contains a single choice and nothing else. This can be used to shortcut information shown to a user, e.g. showing the selected child option in the presented name of this node.
      Returns:
      whether this node only contains a single choice and nothing else

    • getChildCount

      public int getChildCount()
      Returns the number of children.
      Returns:
      number of children.

    • setChild

      public void setChild(int index, XsdTreeNode child)
      Sets the given node as child of this node.
      Parameters:
      index - index to insert the node.
      child - child node.

    • getChild

      public XsdTreeNode getChild(int index)
      Returns the child at given index.
      Parameters:
      index - child index.
      Returns:
      child.

    • hasChild

      public boolean hasChild(String name)
      Returns whether this node has a child with given name.
      Parameters:
      name - child name
      Returns:
      whether this node has a child with given name

    • getFirstChild

      public XsdTreeNode getFirstChild(String name)
      Returns the first child with given name. The node may be within a series of xsd:sequence and xsd:choice/xsd:all intermediate nodes.
      Parameters:
      name - child name.
      Returns:
      child.
      Throws:
      NoSuchElementException - when no child with given name exists

    • getChildren

      public List<XsdTreeNode> getChildren()
      Returns a list of the child nodes.
      Returns:
      list of the child nodes; safe copy.

    • assureChildren

      protected void assureChildren()
      Assures children are present. If a child has minOccurs > 1, additional child nodes are added. Result is cached.

    • getParent

      public XsdTreeNode getParent()
      Returns the parent node.
      Returns:
      parent node, is null for the root.

    • attributeCount

      public int attributeCount()
      Returns the number of attributes.
      Returns:
      number of attributes.

    • getAttributeNode

      public Node getAttributeNode(int index)
      Returns the attributes at given index.
      Parameters:
      index - attribute index.
      Returns:
      attribute node.
      Throws:
      IndexOutOfBoundsException - when the index is not in the bounds for the number of attributes

    • setAttributeValue

      public void setAttributeValue(int index, String value)
      Sets an attribute value.
      Parameters:
      index - index of the attribute.
      value - value of the attribute.
      Throws:
      IndexOutOfBoundsException - when the index is not in the bounds for the number of attributes

    • getDefaultAttributeValue

      public Optional<String> getDefaultAttributeValue(int index)
      Returns the default value for the attribute.
      Parameters:
      index - attribute index.
      Returns:
      default value for the attribute, empty if there is no default value.
      Throws:
      IndexOutOfBoundsException - when the index is not in the bounds for the number of attributes

    • setAttributeValue

      public void setAttributeValue(String name, String value)
      Sets an attribute value.
      Parameters:
      name - name of the attribute.
      value - value of the attribute.
      Throws:
      NoSuchElementException - when the attribute is not in this node.

    • getAttributeValue

      public String getAttributeValue(int index)
      Returns an attribute value.
      Parameters:
      index - index of the attribute.
      Returns:
      value of the attribute.
      Throws:
      IndexOutOfBoundsException - when the index is not in the bounds for the number of attributes

    • getAttributeValue

      public String getAttributeValue(String attribute)
      Returns an attribute value.
      Parameters:
      attribute - name of the attribute.
      Returns:
      value of the attribute.
      Throws:
      NoSuchElementException - when the attribute is not in this node.

    • getAttributeIndexByName

      public int getAttributeIndexByName(String attribute)
      Returns the index of the named attribute.
      Parameters:
      attribute - attribute name.
      Returns:
      index of the named attribute.
      Throws:
      NoSuchElementException - when the attribute is not in this node.

    • getAttributeNameByIndex

      public String getAttributeNameByIndex(int index)
      Returns the name of the indexed attribute.
      Parameters:
      index - attribute index.
      Returns:
      name of the indexed attribute.
      Throws:
      IndexOutOfBoundsException - when the index is not in the bounds for the number of attributes

    • hasAttribute

      public boolean hasAttribute(String attribute)
      Returns whether this node has an attribute with given name.
      Parameters:
      attribute - attribute name.
      Returns:
      whether this node has an attribute with given name.

    • isActive

      public boolean isActive()
      Returns whether the node is active. If not, it only exists to show the user what type of node may be created here.
      Returns:
      whether the node is active.

    • setActive

      public void setActive()
      Sets this node to be active if it is not already. If this node is the selected node within a choice, it also activates all other options of the choice. For include nodes, or the included child nodes, activation is cascaded down the tree.

    • setInactive

      public void setInactive()
      Deactivates this node if it is not already. This does not remove child nodes but only sets a boolean toggle. For include nodes, or the included child nodes, deactivation is cascaded down the tree.

    • isIdentifiable

      public boolean isIdentifiable()
      Returns whether this node has an attribute named "Id". For inactive nodes false is returned as no id is editable.
      Returns:
      whether this node has an attribute named "Id".

    • setId

      public void setId(String id)
      Sets the value for an attribute with name "Id".
      Parameters:
      id - value to set.
      Throws:
      NoSuchElementException - when the node has no id attribute

    • getId

      public String getId()
      Returns the value of an attribute with name "Id".
      Returns:
      value of an attribute with name "Id".
      Throws:
      NoSuchElementException - when the node has no id attribute

    • isEditable

      public boolean isEditable()
      Returns whether this node is editable; i.e. whether a value can be set on the node, i.e. has a simple value, e.g. <Node>Simple value</Node>. For inactive nodes false is returned as no value is editable.
      Returns:
      whether this node is editable, i.e. whether a value can be set on the node.

    • setValue

      public void setValue(String value)
      Sets the value on this node.
      Parameters:
      value - value to set.

    • getValue

      public String getValue()
      Returns the value of this node.
      Returns:
      value of this node.

    • isIncluded

      public boolean isIncluded()
      Returns whether this node exists as its loaded from an include.
      Returns:
      whether this node exists as its loaded from an include.

    • isAddable

      public boolean isAddable()
      Returns whether a node of the same type may be added next to this node under the parent. This is based on maxOccurs.
      Returns:
      whether a node of the same type may be added next to this node under the parent.

    • add

      public XsdTreeNode add()
      Adds a node of similar type next to this node under the parent. If the node is a choice, the same selected option will be set in the added node. In this way the user sees that node option copied.
      Returns:
      added node.

    • duplicate

      public XsdTreeNode duplicate()
      Creates a full copy of this node, next to this node under the same parent.
      Returns:
      newly created node.

    • duplicate

      public XsdTreeNode duplicate(XsdTreeNode newParent)
      Duplicates this node, but under the given parent node.
      Parameters:
      newParent - parent node.
      Returns:
      newly created node.

    • emptyCopy

      public XsdTreeNode emptyCopy()
      Creates an empty copy of this node, i.e. without children, options, attributes.
      Returns:
      empty copy.

    • canContain

      public boolean canContain(XsdTreeNode copied)
      Returns whether this node can contain the information of the given node. This only checks equivalence of the underlying XSD nodes, or equivalence of the referencing XSD nodes.
      Parameters:
      copied - node that was copied, and may be pasted/inserted here.
      Returns:
      whether this node can contain the information of the given node.

    • copyInto

      public void copyInto(XsdTreeNode copyNode)
      Copies the active status, value, choice, attributes and children of this node in to the given node.
      Parameters:
      copyNode - node to copy data in to.

    • isRemovable

      public boolean isRemovable()
      Returns whether this node may be removed without violating "minOccurs" constraints, including deactivating nodes with minOccurs = 0.
      Returns:
      whether this node may be removed without violating "minOccurs" constraints.

    • remove

      public final void remove()
      Removes this node from the tree structure. For nodes with minOccurs = 0 that are the last of their type in the context of their parent, the node is deactivated rather than removed. This method also explicitly removes all children nodes recursively.

    • canMoveUp

      public boolean canMoveUp()
      Returns whether the node can be moved up in the parent.
      Returns:
      whether the node can be moved up in the parent.

    • canMoveDown

      public boolean canMoveDown()
      Returns whether the node can be moved down in the parent.
      Returns:
      whether the node can be moved down in the parent.

    • move

      public void move(int down)
      Move the node to a different position in the parent, relative to the current position. It is not checked whether this is allowed.
      Parameters:
      down - number of moves down. May be negative for up.

    • minOccurs

      public int minOccurs()
      Returns the minimum number of this element under the parent node, as defined in minOccurs in XSD.
      Returns:
      minimum number of this element under the parent node, as defined in minOccurs in XSD.

    • maxOccurs

      public int maxOccurs()
      Returns the maximum number of this element under the parent node, as defined in maxOccurs in XSD. The XSD value "unbounded" results in a value of -1.
      Returns:
      maximum number of this element under the parent node, as defined in maxOccurs in XSD.

    • getAttributeBaseType

      public String getAttributeBaseType(int index)
      Returns the base type of the attribute, e.g. xsd:double.
      Parameters:
      index - attribute index.
      Returns:
      base type of the attribute, e.g. xsd:double.

    • isType

      public boolean isType(String path)
      Returns whether this node is of the type defined by the path.
      Parameters:
      path - path of the type in dotted xpath notation, e.g. "SignalGroup.TrafficLight".
      Returns:
      whether this node is of the type defined by the path.

    • hasExpression

      public boolean hasExpression()
      Returns whether the value, any of the attributes, or any of the sub-elements, has an expression.
      Returns:
      whether the node has an expression.

    • valueIsExpression

      public boolean valueIsExpression()
      Returns whether the value is an expression.
      Returns:
      whether the value is an expression.

    • idIsExpression

      public boolean idIsExpression()
      Returns whether the Id is an expression.
      Returns:
      whether the Id is an expression.
      Throws:
      NoSuchElementException - when the node has no id attribute

    • attributeIsExpression

      public boolean attributeIsExpression(int index)
      Returns whether the attribute is an expression.
      Parameters:
      index - attribute index.
      Returns:
      whether the attribute is an expression.
      Throws:
      IndexOutOfBoundsException - when the index is not in the bounds for the number of attributes

    • addConsumer

      public void addConsumer(String menuItem, Consumer<XsdTreeNode> consumer)
      A consumer can be set externally and will receive this node when its menu item is selected.
      Parameters:
      menuItem - name of item as presented to the user.
      consumer - editor.

    • hasConsumer

      public boolean hasConsumer()
      Returns whether this node has any consumers.
      Returns:
      whether this node has any consumers.

    • getConsumerMenuItems

      public Set<String> getConsumerMenuItems()
      Returns the menu items for which this node has consumers.
      Returns:
      menu items for which this node has consumers.

    • consume

      public void consume(String menuItem)
      Triggers the node to be consumed.
      Parameters:
      menuItem - menu item.
      Throws:
      IllegalArgumentException - when there is no consumer for the given menu item

    • getNodeName

      public String getNodeName()
      Returns the name of this node, as appropriate in XML. Examples are Node, RoadLayout, and TacticalPlanner. Most typically this is the "name" attribute of an xsd:element. In other cases it is the ref={ref} attribute of the referring Node. In rare cases it is "xi:include".
      Returns:
      name of this node, as appropriate in XML.

    • getDescription

      public Optional<String> getDescription()
      Returns the description of this node.
      Returns:
      description of this node, empty if there is none.

    • getShortString

      public String getShortString()
      Returns a string that is the name of the node, without any additional information on id and additional string function.
      Returns:
      string that is the name of the node.

    • setStringFunction

      public void setStringFunction(Function<XsdTreeNode,String> stringFunction, boolean overwrite)
      This function can be set externally and supplies an additional String to clarify this node in the tree. It is presented after the regular node name between parenthesis. E.g. "Od Options Item (Global)" indicating the applicability of the option.
      Parameters:
      stringFunction - Function<XsdTreeNode, String> string function.
      overwrite - overwrite existing. When true, a possible existing string function is overwritten.

    • getPathString

      public String getPathString()
      Returns the path string of this element, e.g. "Ots.Definitions.RoadLayouts". This is used to identify each unique type of element.
      Returns:
      path string of this element, e.g. "Ots.Definitions.RoadLayouts".

    • toString

      public String toString()
      Returns the short string, appended with any additional information on id and optional string function.
      Overrides:
      toString in class Object
      Returns:
      short string, appended with any additional information on id and optional string function.

    • getIdRestrictions

      public List<String> getIdRestrictions()
      Returns all restrictions for Id attribute. These are not sorted and may contain duplicates. Id restrictions may be valid if the Id field points to another element.
      Returns:
      list of restrictions for the Id.

    • getValueRestrictions

      public List<String> getValueRestrictions()
      Returns all restrictions for the value. These are not sorted and may contain duplicates.
      Returns:
      list of restrictions for the value.

    • getAttributeRestrictions

      public List<String> getAttributeRestrictions(int index)
      Returns all restrictions for the given attribute. These are not sorted and may contain duplicates.
      Parameters:
      index - attribute number.
      Returns:
      list of restrictions for the attribute.
      Throws:
      IndexOutOfBoundsException - when the index is not in the bounds for the number of attributes

    • getCoupledNodeValue

      public Optional<XsdTreeNode> getCoupledNodeValue()
      Returns the node to which the value refers via a CoupledValidator.
      Returns:
      node to which the value refers via a CoupledValidator, empty if no such node.

    • getCoupledNodeAttribute

      public Optional<XsdTreeNode> getCoupledNodeAttribute(int index)
      Returns the node to which an attribute refers via a CoupledValidator.
      Parameters:
      index - index of the attribute.
      Returns:
      node to which an attribute refers via a CoupledValidator, empty if no such node.
      Throws:
      IndexOutOfBoundsException - when the index is not in the bounds for the number of attributes

    • getCoupledNodeAttribute

      public Optional<XsdTreeNode> getCoupledNodeAttribute(String attribute)
      Returns the node to which an attribute refers via a CoupledValidator.
      Parameters:
      attribute - attribute name.
      Returns:
      node to which an attribute refers via a CoupledValidator, empty if no such node.

    • isSelfValid

      public boolean isSelfValid()
      Returns whether the contents of the attributes, value and other aspects of the node itself are valid. This excludes child nodes.
      Returns:
      whether the contents of the attributes, value and other aspects of the node itself are valid.

    • isValid

      public boolean isValid()
      Returns whether the node, and all its children recursively, is valid. This means all required values are supplied, and all supplied values comply to their respective types and constraints.
      Returns:
      whether the node is valid.

    • invalidate

      public void invalidate()
      Sets the valid status of this node and all parent nodes to unknown.

    • addNodeValidator

      public void addNodeValidator(Function<XsdTreeNode,String> validator)
      Adds a validator for the node.
      Parameters:
      validator - validator.
      Throws:
      IllegalStateException - if a CoupledValidator is added while one was already added to the value before

    • addValueValidator

      public void addValueValidator(ValueValidator validator, Object field)
      Adds a validator for the value. The field object is any object that is returned to the validator in its getOptions() method, such that it can know for which field option values should be given.
      Parameters:
      validator - validator.
      field - field.
      Throws:
      IllegalStateException - if a CoupledValidator is added while one was already added to the value before

    • addAttributeValidator

      public void addAttributeValidator(String attribute, ValueValidator validator)
      Adds a validator for the value of an attribute.
      Parameters:
      attribute - attribute name.
      validator - validator.
      Throws:
      IllegalStateException - if a CoupledValidator is added while one was already added to the attribute before

    • addAttributeValidator

      public void addAttributeValidator(String attribute, ValueValidator validator, Object field)
      Adds a validator for the value of an attribute. The field object is any object that is returned to the validator in its getOptions() method, such that it can know for which field option values should be given.
      Parameters:
      attribute - attribute name.
      validator - validator.
      field - field.
      Throws:
      IllegalStateException - if a CoupledValidator is added while one was already added to the attribute before

    • reportInvalidNode

      public Optional<String> reportInvalidNode()
      Returns a message why the node is invalid, empty if it is valid. This only concerns validators on node level, i.e. not on attribute or value level. E.g. because the node is duplicate in its parent.
      Returns:
      message why the id is invalid, empty if it is valid.

    • reportInvalidId

      public Optional<String> reportInvalidId()
      Returns a message why the id is invalid, empty if it is valid.
      Returns:
      message why the id is invalid, empty if it is valid.

    • reportInvalidValue

      public Optional<String> reportInvalidValue()
      Returns a message why the value is invalid, empty if it is valid.
      Returns:
      message why the value is invalid, empty if it is valid.

    • reportInvalidAttributeValue

      public Optional<String> reportInvalidAttributeValue(int index)
      Returns a message why the attribute value is invalid, empty if it is valid.
      Parameters:
      index - index of the attribute.
      Returns:
      message why the attribute value is invalid, empty if it is valid.
      Throws:
      IndexOutOfBoundsException - when the index is not in the bounds for the number of attributes

    • saveXmlNodes

      public void saveXmlNodes(Document document, Node xmlParent)
      Saves the content of this node in a new XML element under the given XML parent. This involves a value, attributes, and children. Children are further saved in a recursive manner. If this node is not active, this method does nothing.

      If this node represents a sequence as a choice option, all children are saved directly under the given XML parent node, and no information of this node itself is saved (as such nodes have no attributes or value). In other words, in that case this node is only a virtual layer presented to the user, but does not result in a layer in XML.
      Parameters:
      document - used to create the new XML node.
      xmlParent - parent XML node.

    • loadXmlNodes

      public void loadXmlNodes(Node nodeXml)
      Parses the information from an XML node into this node. This entails a tag value, attributes, and children, for as far as each of these is present. In a recursive manner, all child nodes are further loaded.
      Parameters:
      nodeXml - node from XML.

    • loadChildren

      protected void loadChildren(org.opentrafficsim.editor.XsdTreeNodeUtil.LoadingIndices indices, NodeList childrenXml, boolean loadingSubSequence)
      Parses child nodes from XML in to this node's children, as far as it can given available inactive child nodes. Note that these child nodes are derived from the XSD schema. This method will first find a relevant node to load each child XML node into. The relevant node can be found in two ways:
      1. The previous child node is relevant for the XML child node. This happens when XML specifies multiple nodes of the same type, in a sequence or choice with multiple occurrence. The previous child node will be added, such that information of the XML child node can be loaded in to the added child node.
      2. We move to the next child node until we find a node that is relevant for the XML child node. This should only skip inactive nodes for which XML specifies no information.
      Next, the information from XML is loaded in to the relevant child node. This can happen in four ways:
      1. The relevant node is not a choice or sequence, information is loaded in to it with loadXmlNodes.
      2. The relevant node is a sequence. The relevant child in the sequence is found, and all XML child nodes that can be loaded in to it, are by calling loadChildren.
      3. The relevant node is a choice, where the relevant option is not a sequence. The option will be set in the choice. Information is loaded in to the selected option with loadXmlNodes.
      4. The relevant node is a choice, where the relevant option is a sequence. The option (sequence node) will be set in the choice. The relevant child in the sequence is found, and all XML child nodes that can be loaded in to it, are by calling loadChildren.
      Note that for case 3, the child content of a deeper XsdChildNode is defined at the same level in XML. Hence, only some of the XML children may be loaded in the deeper level. To keep track of which XML child nodes are loaded where, the value LoadingIndices.xmlNode is given as input (previous nodes have already been loaded at a higher level or in another choice sequence). In this value also the index of the first XML child node that could not be loaded in the choice sequence is returned.

      The parameter LoadingIndices is also used when an XML node cannot be loaded at all because it does not comply with the XSD schema. This will cause the loading to run through all children to see whether it can be loaded there. The second value LoadingIndices.xsdTreeNode is used as input to know where to continue in a second call to this method after an earlier call came across an XML node that could not be loaded. In LoadingIndices.xsdTreeNode the index of the last child node in to which XML data was loaded is given.
      Parameters:
      indices - index of the first XML child node to load, and first XsdTreeNode index to use.
      childrenXml - list of XML child nodes as specified within one parent XML tag.
      loadingSubSequence - whether this call is loading children as a sub-sequence.

    • addListener

      public boolean addListener(EventListener listener, EventType eventType, ReferenceType referenceType)

    • addListener

      public boolean addListener(EventListener listener, EventType eventType)