Interface SNode


  • public interface SNode
    NODE STATES A node can have 2 states: it can be either attached to some repository or not. In case it's not attached, it behaves just like any simple Java object. After getting attached to a repository, the node starts checking correct read/write access permissions (locks) through repository.getModelAccess() and also starts sending notifications about node reads.

    CHILDREN Child nodes must have a global ordering meaning that the order in which child nodes are returned by getNextSibling, getPrevSibling, getChildren and other methods, must be consistent with order determined by child add operations. The ordering should be consistent not only for children in any particular role, but also for nodes with different roles.

    NODE MANIPULATION After detaching from a model, the node is held in a special place in the repository until the end of the current Command (UnregisteredNodes/ImmatureReferences) so that all references in the node and from the outside still work. E.g. we have A,B and C nodes in model M, where A and B references C. After C.delete or M.removeRoot(C) or C.getParent().removeChild(C), A and B will still have C as a target of reference until the end the current command. If a node has been detached from its parent, it becomes detached from the whole tree. SModel.getRootNodes will not return it as a root in this case.

    STORING NODES Keeping references to nodes between subsequent read actions will cause errors and possible memory leaks. See getReference()

    EXTERNAL CONSTRAINTS SNode represents the raw node in the AST. SNode does not know about constraints, behavior, getters and setters for props/refs.

    READ NOTIFICATIONS Accessing node triggers read notifications (SNodeAccessListener and legacy 'event casters'). Notifications for a node are dispatched the moment node is made available to outer world, not the moment its property or reference is read, i.e. if we read 3 properties and 2 references of a node A, we get single nodeRead(A) followed by 3 propertyRead() and 2 referenceRead() notifications.

    SEE ALSO SNodeUtil, SNodeAccessUtil

    • Method Detail

      • getModel

        @Nullable
        SModel getModel()
        Containing model or null if the node is not contained in any model Does not produce node read event as the function depending on model is not a pure node function.
        See Also:
        SNodeAccessListener
      • getNodeId

        SNodeId getNodeId()
        Uniquely identifies the node within its containing model. May also be null. Does not produce node read event as the result value can't be changed.
      • getReference

        @NotNull
        SNodeReference getReference()
        Uniquely identifies the node in a repository. Never changes between subsequent read and write actions and behaves as a "weak reference" for a node Represents the only correct way to pass or store nodes between read/write actions. Does not produce node read event as the node is already obtained, and the read event has already happened. If obtained for a node that is not in repository, can return invalid reference
      • getConcept

        @NotNull
        SConcept getConcept()
        The concept that this node represents. Concepts can be checked for equality with equals().
      • getPresentation

        String getPresentation()
        A string representing the node used to show the node in UI
      • getName

        @Nullable
        String getName()
        For instances of INamedConcept concepts retrieves "name" property
        Returns:
        null if node is not instance of INamedConcept
      • insertChildBefore

        void insertChildBefore​(@NotNull
                               SContainmentLink role,
                               @NotNull
                               SNode child,
                               @Nullable
                               SNode anchor)
        Inserts the given node as a child of the current node of the specified role right in front of the anchor node.
        Parameters:
        role - a role to insert new child into
        child - a node to insert
        anchor - a new child node will be inserted just before this node. If anchor is not specified, a new child is inserted as a last child. If anchor is the first child element, newly added child becomes head of collection
      • insertChildAfter

        void insertChildAfter​(@NotNull
                              SContainmentLink role,
                              @NotNull
                              SNode child,
                              @Nullable
                              SNode anchor)
        Inserts the given node as a child of the current node of the specified role right after the anchor node.
        Parameters:
        role - a role to insert new child into
        child - a node to insert
        anchor - a new child node will be inserted just after this node. If anchor is not specified, a new child is inserted as a first child. If anchor is the last child element, newly added child becomes tail of collection
      • removeChild

        void removeChild​(@NotNull
                         SNode child)
        Removes the child of this node. See "node manipulation" section in class doc
      • delete

        void delete()
        If the node is a root, removes it from a model, else removes the node from its parent. See "node manipulation" section in class doc
      • getParent

        @Nullable
        SNode getParent()
        Returns the parent of this node Does not produce read on current as current is already obtained, does notify read for the parent.
        Returns:
        parent of this node
      • getContainingRoot

        @NotNull
        SNode getContainingRoot()
        Returns the ancestor of current node, which parent is null Does not produce read on current as current is already obtained
        Returns:
        root containing this node
      • getContainmentLink

        @Nullable
        SContainmentLink getContainmentLink()
        Returns role of this node in parent node Returns null if a node has no parent
      • getFirstChild

        @Nullable
        SNode getFirstChild()
        Works together with getLastChild(). Allows to iterate through a collection of all children.
        Returns:
        first element in a collection of children
      • getLastChild

        @Nullable
        SNode getLastChild()
        Works together with getFirstChild(). Allows to iterate through a collection of all children.
        Returns:
        last element in a collection of children
      • getPrevSibling

        @Nullable
        SNode getPrevSibling()
        no parent -> no sibling. Root has no siblings Does not produce read on current as current is already obtained Notifies read for the parent node and sibling node, if any.
      • getNextSibling

        @Nullable
        SNode getNextSibling()
        no parent -> no sibling. Root has no siblings Does not produce read on current as current is already obtained. Notifies read for the parent node and sibling node, if any.
      • getChildren

        @NotNull
        Iterable<? extends SNode> getChildren​(SContainmentLink role)
        Returns an immutable collection of children in the specified role. Does not produce read on current as current is already obtained, produces read accesses to child nodes lazily (when really accessed), does not produce read accesses for skipped children
      • getChildren

        @NotNull
        Iterable<? extends SNode> getChildren()
        Returns an immutable collection of all children. Read access policy is same to getChildren(role)
      • setReferenceTarget

        void setReferenceTarget​(@NotNull
                                SReferenceLink role,
                                @Nullable
                                SNode target)
        Sets a reference of the given role to a particular node. null target effectively removes the reference
      • setReference

        void setReference​(@NotNull
                          SReferenceLink role,
                          ResolveInfo resolveInfo)
        Establish an association with node determined by an abstraction that captures mechanism to resolve a target. There are association with fixed aka 'static' targets as well as association with 'dynamic' targets that utilize external scope implementations to determine target node based on resolveInfo additional information.
        This is a low-level mechanism, intended to replace setReference(SReferenceLink, SReference) and to hide specific SReference implementation differences spread throughout the code. End-user code is supposed to go through higher-level methods of SLinkOperations and SNodeAccessUtil. Exemplary clients of this methods are persistence, M2M (Generator) and model copy/clone facilities.
        FIXME dynamic references are generally not persisted, don't use them in models that are serialized using regular MPS persistence At the moment, we support String auxiliary resolution information, see ResolveInfo.of(String) FIXME null for resolveInfo - does it mean anything specific (broken dynamic reference or dropReference?)
        Parameters:
        role - meta-object that identifies association relation.
        resolveInfo - auxiliary information for use to find proper target in a scope
        Since:
        2020.2
      • getReferenceTarget

        @Nullable
        SNode getReferenceTarget​(@NotNull
                                 SReferenceLink role)
        Null means the reference has not been set or was set to null. It's impossible to the distinguish the two cases.
      • getReference

        @Nullable
        SReference getReference​(@NotNull
                                SReferenceLink role)
        Retrieves an SReference of the given role to a node. Since SReference can refer to nodes by name and resolve them dynamically, this method may be able to help you resolve the target node even when working with invalid code.
      • setReference

        @Deprecated
        void setReference​(@NotNull
                          SReferenceLink role,
                          @Nullable
                          SReference reference)
        Deprecated.
        cumbersome api, use explicit #dropReference() for null case, or another method that doesn't require construction of an object with source/link already specified.
        Sets a reference of the given role to a node that is resolved from the SReference. Since SReference can refer to nodes by name and resolve them dynamically, this method may be able to resolve the target node even when working with invalid code.
      • dropReference

        void dropReference​(@NotNull
                           SReferenceLink role)
        Clears association between this node and whatever target node associated with the specified role
        Parameters:
        role - association meta-object
      • getReferences

        @NotNull
        Iterable<? extends SReference> getReferences()
        Retrieves all SReferences from the node. Since SReference can refer to nodes by name and resolve them dynamically, this method may be able to help you resolve the target nodes even when working with invalid code.

        The returned collection is immutable. Produces read access on the node.

      • getProperties

        @NotNull
        Iterable<SProperty> getProperties()
        Retrieves keys of all properties. The returned collection is immutable.
      • getProperty

        @Nullable
        String getProperty​(@NotNull
                           SProperty property)
        Returns the value of this property
        Returns:
        value of a property or null if the property was not set
      • setProperty

        void setProperty​(@NotNull
                         SProperty property,
                         @Nullable
                         String propertyValue)
        Sets the value of the raw property. Constraints are not checked.
      • getRoleInParent

        @Deprecated
        String getRoleInParent()
        Deprecated.
        use getContainmentLink()
      • hasProperty

        @Deprecated
        boolean hasProperty​(String propertyName)
        Deprecated.
        use hasProperty(SProperty), or jetbrains.mps.smodel.SNodeLegacy for compatibility code
      • getProperty

        @Deprecated
        String getProperty​(String propertyName)
        Deprecated.
        use getProperty(SProperty), or jetbrains.mps.smodel.SNodeLegacy for compatibility code
      • setProperty

        @Deprecated
        void setProperty​(String propertyName,
                         String propertyValue)
        Deprecated.
        use setProperty(SProperty), or jetbrains.mps.smodel.SNodeLegacy for compatibility code
      • setReferenceTarget

        @Deprecated
        void setReferenceTarget​(String role,
                                @Nullable
                                SNode target)
        Deprecated.
        use setReferenceTarget(SReferenceLink, SNode), or jetbrains.mps.smodel.SNodeLegacy for compatibility code
      • getReferenceTarget

        @Deprecated
        SNode getReferenceTarget​(String role)
        Deprecated.
        use getReferenceTarget(SReferenceLink), or jetbrains.mps.smodel.SNodeLegacy for compatibility code
      • getReference

        @Deprecated
        SReference getReference​(String role)
        Deprecated.
        use getReference(SReferenceLink), or jetbrains.mps.smodel.SNodeLegacy for compatibility code
      • setReference

        @Deprecated
        void setReference​(String role,
                          SReference reference)
        Deprecated.
        use setReference(SReferenceLink, SReference), or jetbrains.mps.smodel.SNodeLegacy for compatibility code
      • insertChildBefore

        @Deprecated
        void insertChildBefore​(String role,
                               SNode child,
                               @Nullable
                               SNode anchor)
        Deprecated.
        use insertChildBefore(SContainmentLink, SNode, SNode), or jetbrains.mps.smodel.SNodeLegacy for compatibility code
      • addChild

        @Deprecated
        void addChild​(String role,
                      SNode child)
        Deprecated.
        use addChild(SContainmentLink, SNode), or jetbrains.mps.smodel.SNodeLegacy for compatibility code
      • getChildren

        @Deprecated
        Iterable<? extends SNode> getChildren​(String role)
        Deprecated.
        use getChildren(SContainmentLink), or jetbrains.mps.smodel.SNodeLegacy for compatibility code