Package org.jetbrains.mps.openapi.model

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