FileDocCategorySizeDatePackage
LinkPortal.javaAPI DocphoneME MR2 API (J2ME)6242Wed May 02 18:00:02 BST 2007com.sun.midp.links

LinkPortal

public class LinkPortal extends Object
This class provides foreign methods of the Isolate class. (For discussion of foreign methods, see Fowler, _Refactoring_, "Introduce Foreign Method", p. 162.) The technique for passing links between isolates is implemented as a separate class in order to avoid short term dependencies on the implementation of the Isolate class in CLDC. These functions will eventually be moved to the Isolate class of CLDC. IMPL_NOTE The current arrangement is highly problematic and therefore should be considered only as a temporary solution. The portal keeps track of links by isolate ID. However, an isolate ID is only assigned after the isolate has been started. Therefore, getLinks() must block until the parent isolate has had a chance to call setLinks(). The sender and receiver must agree to pass this initial set of links. This is pretty fragile, but it's only necessary for passing the initial set of links. Any additional links can be passed via the initial set of links. If an isolate dies before it gets its links, they'll be stranded in the portal. The parent isolate can overwrite them, though, and they should be collected. Worse, if an isolate dies and another isolate is created and gets the same IDs, it can get the links that were destined for the first. This requires the parent isolate to be responsible for cleaning up any unused links passed to its children, which could be difficult in general.

Fields Summary
Constructors Summary
private LinkPortal()
Prevents construction of any instances.
Methods Summary
private static native intgetLinkCount0()

public static synchronized Link[]getLinks()
Gets the links for this isolate that had been set by its creator. If
links are available, this returns immediately. If no links are
available, this method will block until the creator sets them. This
requires close cooperation between the creator isolate and the newly
created isolate. The typical usage is that the creator creates the new
isolate and passes one set of links to it, and the first thing the new
new isolate does is to get this initial set of links. Any subsequent
links should be passed through the initial set of links.
        int count = getLinkCount0();

        Link[] la = new Link[count];

        for (int i = 0; i < count; i++) {
            la[i] = new Link();
        }

        /*
         * IMPL_NOTE - race condition
         * The creator could change the number of links between the call to 
         * getCount0() and the call to getLinks0().
         */

        getLinks0(la);
        return la;
    
private static native voidgetLinks0(Link[] linkarray)
public static voidsetLinks(com.sun.cldc.isolate.Isolate isolate, Link[] linkarray)
Sets the array of links for the given isolate. Once set, the array of
links can be retrieved by the designated isolate using the getLinks()
method.

Setting of links should be done after the isolate is started and before
it terminates, so that a valid id is available. However, this
introduces a race condition between the starting of the isolate, the
call to setLinks(), and the new isolate calling getLinks(). This means
that the new isolate code will need to call getLinks() until it gets
the array of links it expects.

The linkarray parameter may be null, in which case it removes any links
that had been previously set for isolate. If getLinks() is called at
this point, it will block until a non-null array is set. Passing a
null linkarray to setLinks() differs from passing a zero-length array,
which will satisfy a call to getLinks() and cause it to return a
zero-length array.

If linkarray is an array whose length is greater than zero, every entry
must be a valid (non-null) Link object.
throws
NullPointerException if isolate is null
throws
NullPointerException if any entry in linkarray is null
throws
IllegalArgumentException if any link in linkarray is closed
throws
IllegalStateException if isolate hasn't been started or has
been terminated
        if (isolate == null) {
            throw new NullPointerException();
        }

        if (linkarray != null) {
            for (int i = 0; i < linkarray.length; i++) {
                if (linkarray[i] == null) {
                    throw new NullPointerException();
                }
            }
        }

        int id = isolate.id();
        if (id == -1 || isolate.isTerminated()) {
            throw new IllegalStateException();
        }

        /*
         * IMPL_NOTE - race conditions
         * The array could change between these checks and the call to
         * setLinks0(). The state of the isolate could also change.
         */

        setLinks0(id, linkarray);
    
private static native voidsetLinks0(int isolateid, Link[] linkarray)