com.spss.psapi.transform

Interface ProcessorDiagram

  • All Known Subinterfaces:
    CompositeProcessorDiagram, ProcessorStream


    public interface ProcessorDiagram
    This is the container used to assemble Processor objects into a connected flow or well-formed sequence of nodes.
    Since:
    PSAPI 1.2
    Version:
    1.0
    Author:
    Rob Duncan, Julian Clinton
    Specification Status:
    Under Development
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void clear()
      Deletes all nodes from this diagram.
      int commentCount()
      Returns the number of comments in the diagram.
      java.util.List<Comment> comments()
      Returns a list of comments in the diagram.
      Processor create(java.lang.String nodeType, java.lang.String name)
      Creates a Processor of the specified type and adds it to this diagram.
      Processor createAt(java.lang.String nodeType, java.lang.String name, int x, int y)
      Creates a Processor of the specified type and adds it to this diagram at the specified location.
      Comment createCommentAt(java.lang.String text, java.util.List<java.lang.String> nodeIds, int x, int y, int width, int height)
      Creates a Comment of the specified type and adds it to this diagram at the specified location.
      CompositeProcessor createCompositeAt(java.lang.String label, java.util.List<Processor> nodes, java.util.List<Comment> comments, int x, int y)
      Creates a CompositeProcessor containing the specified nodes and comments.
      Processor createModelApplier(ModelOutput modelOutput, java.lang.String name)
      Creates a ModelApplier derived from the supplied model output object.
      Processor createModelApplierAt(ModelOutput modelOutput, java.lang.String name, int x, int y)
      Creates a ModelApplier derived from the supplied model output object.
      void delete(Processor node)
      Deletes the specified node from this diagram.
      void deleteAll(java.util.Collection nodes)
      Deletes all the specified nodes from this diagram.
      boolean deleteComment(Comment comment)
      Deletes the specified comment from this diagram.
      boolean deleteComments(java.util.List<?> comments)
      Deletes the specified comments from this diagram.
      void disconnect(Processor node)
      Removes any links between the supplied node and any other nodes in this diagram.
      java.util.List<?> expandComposite(CompositeProcessor node)
      Expands a CompositeProcessor into the nodes that make up the composite node.
      java.util.Collection findAll(ProcessorFilter filter, boolean recursive)
      Returns a collection of all nodes accepted by the specified filter.
      java.util.Collection findAll(ProcessorType type, java.lang.String label)
      Returns a list of all nodes with the specified type and name.
      java.util.Collection findAll(java.lang.String type, java.lang.String label)
      Returns a list of all nodes with the specified type and name.
      Processor findByID(java.lang.String id)
      Returns the node with the supplied ID or null if no such node exists.
      Processor findByType(java.lang.String type, java.lang.String label)
      Returns the node with the supplied type and/or label.
      Comment findCommentByID(java.lang.String commentId)
      Returns the comment with the specified ID from the diagram or null if no such comment can be found.
      java.util.List findDownstream(java.util.List<Processor> fromNodes)
      Searches from the supplied list of nodes and returns the set of nodes downstream of the supplied nodes.
      Processor findProcessorForID(java.lang.String id)
      Returns the node with the supplied ID or null if no such node exists.
      Processor findProcessorForID(java.lang.String id, boolean recursive)
      Returns the node with the supplied ID or null if no such node exists.
      java.util.Collection findProcessorLabel(java.lang.String label)
      Returns a list of all nodes with the specified label.
      java.util.Collection findProcessorType(ProcessorType type)
      Returns a list of all nodes with the specified com.spss.psapi.transform.type.
      java.util.List findUpstream(java.util.List<Processor> fromNodes)
      Searches from the supplied list of nodes and returns the set of nodes upstream of the supplied nodes.
      void flushCaches()
      Flushes the caches of any cache-enabled Processor objects in the diagram.
      int getHeight()
      Returns the height of the diagram in pixels.
      int getProcessorCount()
      Deprecated.  
      ProcessorFactory getProcessorFactory()
      Returns the ProcessorFactory for this diagram.
      int getWidth()
      Returns the width of the diagram in pixels.
      java.util.List insert(ProcessorDiagram source, java.util.List nodes, boolean newIDs)
      Inserts copies of the nodes in the supplied list.
      java.util.List insert(ProcessorDiagram source, java.util.List nodes, java.util.List comments, boolean newIDs)
      Inserts copies of the nodes and comments in the supplied list.
      boolean isEnabled(Processor node)
      Returns true if the supplied node is enabled.
      boolean isOwner(Processor node)
      Returns true if the node is owned by this diagram.
      boolean isValidLink(Processor source, Processor target)
      Returns true if it would be valid to create a link between the specified source and target nodes.
      java.util.Iterator iterator()
      Returns an iterator over the Processor objects contained in this diagram.
      void link(Processor source, java.util.List targets)
      Creates new links between the source and each target node in the supplied list.
      void link(Processor source, Processor target)
      Creates a new link between the source and the target.
      void linkBetween(Processor inserted, Processor source, Processor target)
      Connects a Processor between two other instances and sets the position of the inserted node to be between those.
      void linkPath(java.util.List path)
      Creates a new path between Processor instances.
      void linkUpdater(Processor updater, Processor updatable)
      Creates a new update link between the updater and the updatable.
      Processor predecessorAt(Processor node, int index)
      Returns the specified immediate predecessor of the supplied node or null if the index is out of bounds
      int predecessorCount(Processor node)
      Returns the number of immediate predecessors of the supplied node.
      java.util.List predecessors(Processor node)
      Returns the immediate predecessors of the supplied node.
      java.util.Iterator processorIterator()
      Deprecated.  
      void replace(Processor originalNode, Processor replacementNode, boolean discardOriginal)
      Replaces the specified node from this diagram.
      void setEnabled(Processor node, boolean enabled)
      Sets the enabled state of the supplied node.
      void setSize(int width, int height)
      Sets the size of the diagram.
      int size()
      Returns the number of Processor objects contained in this diagram.
      Processor successorAt(Processor node, int index)
      Returns the specified immediate successor of the supplied node or null if the index is out of bounds
      int successorCount(Processor node)
      Returns the number of immediate successors of the supplied node.
      java.util.List successors(Processor node)
      Returns the immediate successors of the supplied node.
      void unlink(Processor source, java.util.List targets)
      Removes any direct links between the source and each object in the targets list.
      void unlink(Processor source, Processor target)
      Removes any direct link between the source and the target.
      void unlinkPath(java.util.List path)
      Removes any path that exists between Processor instances.
      void unlinkUpdater(Processor updater, Processor updatable)
      Removes any update link between the updater and the updatable.
    • Method Detail

      • isOwner

        boolean isOwner(Processor node)
        Returns true if the node is owned by this diagram.
        Parameters:
        node - the node
        Returns:
        true if the node is owned by this diagram
      • flushCaches

        void flushCaches()
        Flushes the caches of any cache-enabled Processor objects in the diagram. Has no effect if caches are not enabled or are not full.
      • getProcessorCount

        int getProcessorCount()
        Deprecated. 
        Returns the number of Processor objects contained in this diagram.
        Returns:
        the node count
        See Also:
        size()
      • size

        int size()
        Returns the number of Processor objects contained in this diagram.
        Returns:
        the node count
      • processorIterator

        java.util.Iterator processorIterator()
        Deprecated. 
        Returns an iterator over the Processor objects contained in this diagram. The behaviour of the iterator if the diagram is modified between calls of next() is undefined.

        Note: the iterator returns "top-level" nodes and does not recursively descend into any composite nodes.

        Returns:
        an iterator
        See Also:
        iterator()
      • iterator

        java.util.Iterator iterator()
        Returns an iterator over the Processor objects contained in this diagram. The behaviour of the iterator if the diagram is modified between calls of next() is undefined.

        Note: the iterator returns "top-level" nodes and does not recursively descend into any composite nodes.

        Returns:
        an iterator
      • findByType

        Processor findByType(java.lang.String type,
                           java.lang.String label)
        Returns the node with the supplied type and/or label. Either the type or name may be null in which case the other parameter is used. If multiple nodes match then an arbitrary one is chosen and returned. If no nodes match then the return value is null.
        Parameters:
        type - the node type
        label - the node label
        Returns:
        a matching node or null
        Since:
        PSAPI 16.0
        See Also:
        findByID(String), findProcessorLabel(String), findProcessorType(ProcessorType)
      • findAll

        java.util.Collection findAll(java.lang.String type,
                                   java.lang.String label)
        Returns a list of all nodes with the specified type and name. Either the type or name may be null in which case the other parameter is used.
        Parameters:
        type - the node type
        label - the node label
        Returns:
        a list of nodes of the specified type and label
        Since:
        PSAPI 16.0
        See Also:
        findAll(ProcessorType, String), findByType(String, String), findByID(String)
      • findProcessorForID

        Processor findProcessorForID(java.lang.String id)
        Returns the node with the supplied ID or null if no such node exists. Only searches within the current diagram i.e. is equivalent to:

        findProcessorForID(id, false)

        Parameters:
        id - the node ID
        Returns:
        a node or null
        Since:
        PSAPI 2.0
        See Also:
        findProcessorForID(String, boolean)
      • findProcessorForID

        Processor findProcessorForID(java.lang.String id,
                                   boolean recursive)
        Returns the node with the supplied ID or null if no such node exists. If the recursive flag is true then any composite nodes within this diagram are also searched.
        Parameters:
        id - the node ID
        recursive - if true then composite nodes should be recursively searched
        Returns:
        a node or null
        Since:
        PSAPI 12.0
        See Also:
        findProcessorForID(String)
      • findProcessorType

        java.util.Collection findProcessorType(ProcessorType type)
        Returns a list of all nodes with the specified com.spss.psapi.transform.type.
        Parameters:
        type - the node type
        Returns:
        a list of nodes of the specified type
        See Also:
        findProcessorLabel(String)
      • findAll

        java.util.Collection findAll(ProcessorType type,
                                   java.lang.String label)
        Returns a list of all nodes with the specified type and name.
        Parameters:
        type - the node type
        label - the node label
        Returns:
        a list of nodes of the specified type and label
        See Also:
        findByType(String, String), findByID(String)
      • findAll

        java.util.Collection findAll(ProcessorFilter filter,
                                   boolean recursive)
        Returns a collection of all nodes accepted by the specified filter. If the recursive flag is true then any supernodes within this diagram are also searched.
        Parameters:
        filter - the node filter
        recursive - if true then composite nodes should be recursively searched
        Returns:
        a collection of all nodes accepted by the specified filter
        Since:
        PSAPI 13.0
        See Also:
        findByType(String, String), findByID(String)
      • replace

        void replace(Processor originalNode,
                   Processor replacementNode,
                   boolean discardOriginal)
                     throws OwnerException,
                            ObjectLockedException,
                            InvalidEditException
        Replaces the specified node from this diagram. The both nodes must be owned by this diagram.
        Parameters:
        originalNode - the node to be replaced
        replacementNode - the new node
        discardOriginal - if true, the id of the original node is assigned to the new node and the original node is automatically deleted from the diagram. If false, the original node is retained and the replacement node id is unchanged
        Throws:
        OwnerException - if any node is not owned by this diagram
        ObjectLockedException - if the diagram is currently locked
        InvalidEditException - is the link operation is invalid
        Since:
        PSAPI 11.1
      • deleteAll

        void deleteAll(java.util.Collection nodes)
                       throws OwnerException,
                              ObjectLockedException
        Deletes all the specified nodes from this diagram. All nodes in the collection must belong to this diagram.
        Parameters:
        nodes - the collection of nodes to be removed
        Throws:
        OwnerException - if any node parameters are not owned by this diagram
        ObjectLockedException - if the diagram is currently locked
        java.lang.ClassCastException - if any item in the collection is not of type Processor
      • unlink

        void unlink(Processor source,
                  java.util.List targets)
                    throws OwnerException,
                           ObjectLockedException
        Removes any direct links between the source and each object in the targets list.
        Parameters:
        source - the source node
        targets - the list of target nodes
        Throws:
        OwnerException - if any node parameters are not owned by this diagram
        ObjectLockedException - if the diagram is currently locked
        java.lang.ClassCastException - if targets does not contain instances of Processor
      • linkPath

        void linkPath(java.util.List path)
                      throws OwnerException,
                             ObjectLockedException,
                             InvalidEditException
        Creates a new path between Processor instances. The first node is linked to the second, the second is linked to the third etc. If any link would be invalid (for example, the nodes are already linked, the source is a terminal node, the target is a source node or the target cannot accept any more links), a PredictiveServerException is thrown and no changes are made to the diagram.
        Parameters:
        path - the set of Processor instances
        Throws:
        OwnerException - if any objects in the path are not owned by this diagram
        ObjectLockedException - if the diagram is currently locked
        InvalidEditException - if a link between two adjacent nodes in the path cannot be created.
      • linkBetween

        void linkBetween(Processor inserted,
                       Processor source,
                       Processor target)
                         throws OwnerException,
                                ObjectLockedException,
                                InvalidEditException
        Connects a Processor between two other instances and sets the position of the inserted node to be between those. Any direct link between the source and target is removed first. If any link would be invalid (the source is a terminal node, the target is a source node or the target cannot accept any more links), a PredictiveServerException is thrown and no changes are made to the diagram.
        Parameters:
        inserted - the node to be inserted
        source - the source node
        target - the target node
        Throws:
        OwnerException - if any of the nodes are not owned by the diagram
        ObjectLockedException - if the diagram has been locked because of another operation
        InvalidEditException - if the edit is invalid e.g., the target already has the maximum number of input connections
        Since:
        PSAPI 16.0.0
      • unlinkPath

        void unlinkPath(java.util.List path)
                        throws OwnerException,
                               ObjectLockedException
        Removes any path that exists between Processor instances. If no link exists between two adjacent nodes in the path, these are silently ignored i.e., no exception will be thrown.
        Parameters:
        path - the list of Processor instances
        Throws:
        ObjectLockedException - if the diagram is currently locked
        OwnerException - if any objects in the path are not owned by this diagram
      • isValidLink

        boolean isValidLink(Processor source,
                          Processor target)
                            throws OwnerException
        Returns true if it would be valid to create a link between the specified source and target nodes. This checks that both objects belong to this diagram, that the source can supply a link and the target can receive a link, and that creating such a link will not cause a circularity in the diagram.
        Parameters:
        source - the source node
        target - the target node
        Returns:
        true if a link would be valid, false otherwise
        Throws:
        OwnerException - if the source or target node are not owned by this diagram
      • predecessors

        java.util.List predecessors(Processor node)
                                    throws OwnerException
        Returns the immediate predecessors of the supplied node.
        Parameters:
        node - the node
        Returns:
        the immediate predecessors
        Throws:
        OwnerException - if the node is not owned by this diagram
      • isEnabled

        boolean isEnabled(Processor node)
                          throws OwnerException
        Returns true if the supplied node is enabled.
        Parameters:
        node - the node
        Returns:
        true if the supplied node is enabled
        Throws:
        OwnerException - if the node is not owned by this diagram
        Since:
        PSAPI 13.0.2
      • setEnabled

        void setEnabled(Processor node,
                      boolean enabled)
                        throws OwnerException
        Sets the enabled state of the supplied node.
        Parameters:
        node - the node
        enabled - whether the node should be enabled
        Throws:
        OwnerException - if the node is not owned by this diagram
        Since:
        PSAPI 13.0.2
      • createAt

        Processor createAt(java.lang.String nodeType,
                         java.lang.String name,
                         int x,
                         int y)
                           throws ObjectCreationException,
                                  ObjectLockedException
        Creates a Processor of the specified type and adds it to this diagram at the specified location. If either x < 0 or y < 0, the location is not set.
        Parameters:
        nodeType - the node type name
        name - the object's name
        x - the x location
        y - the y location
        Returns:
        a Processor
        Throws:
        ObjectCreationException - if the node cannot be created for some reason
        ObjectLockedException - if the node cannot be added to the stream
        Since:
        PSAPI 16.0.0
      • createModelApplierAt

        Processor createModelApplierAt(ModelOutput modelOutput,
                                     java.lang.String name,
                                     int x,
                                     int y)
                                       throws ObjectCreationException,
                                              ObjectLockedException
        Creates a ModelApplier derived from the supplied model output object.
        Parameters:
        modelOutput - the model output object
        name - the new object's name
        x - the x location
        y - the y location
        Returns:
        a Processor
        Throws:
        ObjectCreationException - if the node cannot be created for some reason
        ObjectLockedException - if the node cannot be added to the stream
        Since:
        PSAPI 16.0.0
      • getProcessorFactory

        ProcessorFactory getProcessorFactory()
        Returns the ProcessorFactory for this diagram.
        Returns:
        the ProcessorFactory
        See Also:
        ProcessorFactory
      • findUpstream

        java.util.List findUpstream(java.util.List<Processor> fromNodes)
        Searches from the supplied list of nodes and returns the set of nodes upstream of the supplied nodes. The returned list includes the originally supplied nodes.
        Parameters:
        fromNodes - the start point of the search
        Returns:
        the list of upstream nodes
        See Also:
        findDownstream(List)
      • findDownstream

        java.util.List findDownstream(java.util.List<Processor> fromNodes)
        Searches from the supplied list of nodes and returns the set of nodes downstream of the supplied nodes. The returned list includes the originally supplied nodes.
        Parameters:
        fromNodes - the start point of the search
        Returns:
        the list of downstream nodes
        See Also:
        findUpstream(List)
      • insert

        java.util.List insert(ProcessorDiagram source,
                            java.util.List nodes,
                            boolean newIDs)
                              throws ObjectLockedException,
                                     InvalidEditException
        Inserts copies of the nodes in the supplied list. It is assumed that all nodes in the supplied list are contained within the specified diagram. The new IDs flag indicates whether new IDs should be generated for each node, or whether the existing ID should be copied across. It is assumed that all nodes in a diagram have a unique ID so this flag must be set true if the source diagram is the same as this diagram. The method returns the list of newly inserted nodes where the order of the nodes is undefined (i.e. the ordering is not necessarily the same as the order of nodes in the input list).

        Equivalent to calling:

        
         insert(source, nodes, , newIDs)
         
        Parameters:
        source - the diagram that owns the nodes to be inserted
        nodes - the nodes to be copied
        newIDs - true if new IDs should be generated for each node or false if the existing IDs should be re-used
        Returns:
        a list of the newly inserted nodes
        Throws:
        ObjectLockedException - if the diagram has been locked because of another operation
        InvalidEditException - if the edit would be invalid
        Since:
        PSAPI 16.0.0
        See Also:
        findUpstream(List), findDownstream(List), insert(ProcessorDiagram, List, boolean)
      • insert

        java.util.List insert(ProcessorDiagram source,
                            java.util.List nodes,
                            java.util.List comments,
                            boolean newIDs)
                              throws ObjectLockedException,
                                     InvalidEditException
        Inserts copies of the nodes and comments in the supplied list. It is assumed that all nodes and comments in the supplied list are contained within the specified diagram. The new IDs flag indicates whether new IDs should be generated for each node and comment, or whether the existing ID should be copied across. It is assumed that all nodes and comments in a diagram have a unique ID so this flag must be set true if the source diagram is the same as this diagram. The method returns the list of newly inserted objects where the order of the objects is undefined.
        Parameters:
        source - the diagram that owns the nodes to be inserted
        nodes - the nodes to be copied
        comments - the comments to be copied
        newIDs - true if new IDs should be generated for each node or false if the existing IDs should be re-used
        Returns:
        a list of the newly inserted nodes
        Throws:
        ObjectLockedException - if the diagram has been locked because of another operation
        InvalidEditException - if the edit would be invalid
        Since:
        PSAPI 18.1
        See Also:
        findUpstream(List), findDownstream(List), insert(ProcessorDiagram, List, boolean)
      • unlinkUpdater

        void unlinkUpdater(Processor updater,
                         Processor updatable)
                           throws OwnerException,
                                  ObjectLockedException
        Removes any update link between the updater and the updatable. It is expected that updater implements the Updater interface while the updatable implements the Updatable interface.
        Parameters:
        updater - the updater node
        updatable - the target node
        Throws:
        OwnerException - if any node parameters are not owned by this diagram
        ObjectLockedException - if the diagram is currently locked
        Since:
        PSAPI 16.0
        See Also:
        Updater, Updatable
      • getWidth

        int getWidth()
        Returns the width of the diagram in pixels.
        Returns:
        the width of the diagram
        Since:
        PSAPI 18.1
      • getHeight

        int getHeight()
        Returns the height of the diagram in pixels.
        Returns:
        the height of the diagram
        Since:
        PSAPI 18.1
      • setSize

        void setSize(int width,
                   int height)
        Sets the size of the diagram.
        Parameters:
        width - the width in pixels
        height - the height in pixels
        Since:
        PSAPI 18.1
      • commentCount

        int commentCount()
        Returns the number of comments in the diagram.
        Returns:
        the number of comments
        Since:
        PSAPI 18.1
      • comments

        java.util.List<Comment> comments()
        Returns a list of comments in the diagram.
        Returns:
        a list of comments
        Since:
        PSAPI 18.1
      • findCommentByID

        Comment findCommentByID(java.lang.String commentId)
        Returns the comment with the specified ID from the diagram or null if no such comment can be found.
        Returns:
        the specified comment or null
        Since:
        PSAPI 18.1
      • createCommentAt

        Comment createCommentAt(java.lang.String text,
                              java.util.List<java.lang.String> nodeIds,
                              int x,
                              int y,
                              int width,
                              int height)
                                throws ObjectLockedException
        Creates a Comment of the specified type and adds it to this diagram at the specified location. If width or height is <= 0, the default size is used.
        Parameters:
        text - the initial text in the comment
        nodeIds - the listed of associated node IDs
        x - the x location
        y - the y location
        width - the width
        height - the height
        Returns:
        the new comment
        Throws:
        ObjectLockedException - if the comment cannot be added to the stream
        Since:
        PSAPI 18.1
      • deleteComment

        boolean deleteComment(Comment comment)
                              throws OwnerException,
                                     ObjectLockedException
        Deletes the specified comment from this diagram. The comment must be owned to this diagram.
        Parameters:
        comment - the comment to be removed
        Returns:
        true if the diagram was modified, false otherwise
        Throws:
        OwnerException - if the comment is not owned by this diagram
        ObjectLockedException - if the diagram is currently locked
        Since:
        PSAPI 18.1
      • deleteComments

        boolean deleteComments(java.util.List<?> comments)
                               throws OwnerException,
                                      ObjectLockedException
        Deletes the specified comments from this diagram. All comments in the collection must belong to this diagram.
        Parameters:
        comments - the collection of comments to be removed
        Returns:
        true if the diagram was modified, false otherwise
        Throws:
        OwnerException - if the node is not owned by this diagram
        ObjectLockedException - if the diagram is currently locked
        java.lang.ClassCastException - if any item in the collection is not of type Comment
        Since:
        PSAPI 18.1
      • createCompositeAt

        CompositeProcessor createCompositeAt(java.lang.String label,
                                           java.util.List<Processor> nodes,
                                           java.util.List<Comment> comments,
                                           int x,
                                           int y)
                                             throws ObjectLockedException,
                                                    InvalidEditException
        Creates a CompositeProcessor containing the specified nodes and comments. Note that care should be taken to ensure that the set of nodes and comments being encapsulated is valid since certain errors may not be caught until some changes have already been applied to the diagram.
        Parameters:
        labels - the label of the new node
        nodes - the nodes to be encapsulated
        comments - the comments to be encapsulated
        x - the x location
        y - the y location
        Returns:
        the new composite processor
        Throws:
        ObjectLockedException - if the comment cannot be added to the stream
        InvalidEditException - if the specified objects cannot be encapsulated
        Since:
        PSAPI 18.1

(C) Copyright IBM Corp. 1994, 2015. All Rights Reserved.