---

Orthogonal Routing Fixes API Review

Submitter: Kris.Richards@Sun.COM

Type: Fast Track

Tracking Issue: 133717

Short Description

Add two methods to the Anchor class that will allow the OrthogonalSearchRouter(non-API) to determine better orthogonal paths. These changes could be written into the users implementation of the Anchor, but this functionality should be in the api.

Target Milestone

NetBeans 6.5

Dependencies

These changes are fully backward compatible. Any code that has extended the Anchor class will be affected. See the changes section below.
These changes are needed by the UML module for stronger orthogonal routing. Currently a connection route must remain on the side facing its opposite connection.

Change in Current Architecture

Two method calls will be added to the Anchor class:

    /**
     * This is designed to be used with the SearchRouters. If an anchor 
     * allows arbitrary connection placement, the router can find better connection
     * routes.
     * @return true if this anchor can connected to from any direction. Otherwise
     * false. 
     */
    public boolean allowsArbitraryConnectionPlacement() {
        return false ;
    }

    /**
     * Designed to be used with SearchRouters. If the anchor allow arbitrary 
     * connection placement, the router will use the center of the anchor to
     * determine the best route. Once the best route is determined, the points
     * are send to the anchor for "fine tuning". The use case here is for the
     * anchor to adjust the end points to the appropriate boundary intersection
     * location.
     * @param bestPoints list of control points.
     * @return List of points adjusted to fit the anchor. If this call is not
     * overwritten, then it simply returns the point it was sent.
     */
    public List<Point> compute(List<Point> bestPoints) {
        return bestPoints ;
    }

If these methods are not overwritten, then the api behavior remains consistent with previous versions.

The new compute method allows more freedom to calculate the boundary intersection point based of the route of the connection and not just the centers of the two anchors on the connection. It is quite possible that a connection's "best route" may start from a side not facing the anchor at the other end of the connection. The router can check the allowsArbitraryConnectionPlacement() to see if it should commit the cycles to find a "best route" or simply find a route from the point at which it must connect. This is not possible in the current implementation since the only argument in the current compute method in an Entry.

These method calls are used in the OrthogonalSearchRouter (Non-API) to find strong routes between connected nodes. As stated above, if an anchor remains consistent with previous api versions, then the OrthogonalSearchRouter will work exactly as it did in the previous version.

Use Cases

User needs better orthogonal routing capabilities. The specific use case is from the UML module which needs this stronger routing.

Summary of Changes

Adding two public method calls to the api Anchor class for use with the OrthogonalRouter.

apichanges.xml

        <change>
            <api name="general"/>
            <summary>Anchor methods allowsArbitraryConnectionPlacement() and compute(List points) introducted.</summary>
            <version major="2" minor="14"/>
            <date day="30" month="4" year="2008"/>
            <author login="krichard"/>
            <compatibility addition="yes"/>
            <description>
                The new compute method allows more freedom to calculate the boundary 
                intersection point based of the route of the connection and not just 
                the centers of the two anchors on the connection. It is quite possible 
                that a connection's "best route" may start from a side not facing the 
                anchor at the other end of the connection. The router can check the 
                allowsArbitraryConnectionPlacement() to see if it should commit the 
                cycles to find a "best route" or simply find a route from the point 
                at which it must connect. This is not possible in the current 
                implementation since the only argument in the current compute method 
                in an Entry.
            </description>
            <class package="org.netbeans.api.visual.anchor" name="Anchor" link="yes"/>
            <issue number="133717"/>
        </change>

Impacted Interfaces

There are no current interfaces being impacted by this addition.