linkportal.java

来自「This is a resource based on j2me embedde」· Java 代码 · 共 162 行

/*
 *
 *
 * Copyright  1990-2007 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 only, as published by the Free Software Foundation.
 * 
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License version 2 for more details (a copy is
 * included at /legal/license.txt).
 * 
 * You should have received a copy of the GNU General Public License
 * version 2 along with this work; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 * 
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 or visit www.sun.com if you need additional
 * information or have any questions.
 */

package com.sun.midp.links;

import com.sun.cldc.isolate.Isolate;


/**
 * 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.
 */
public class LinkPortal {


    /**
     * 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.
     */
    public synchronized static Link[] getLinks() {
        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;
    }


    /**
     * 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
     */
    public static void setLinks(Isolate isolate, Link[] linkarray) {
        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);
    }


    /**
     * Prevents construction of any instances.
     */
    private LinkPortal() {
    }


    private static native int getLinkCount0();

    private static native void getLinks0(Link[] linkarray);

    private static native void setLinks0(int isolateid, Link[] linkarray);
}